vechain_flutter_sdk 0.0.5-dev
vechain_flutter_sdk: ^0.0.5-dev copied to clipboard
A native Flutter/Dart SDK for VeChainThor. Pure Dart: wallets, transactions, fee delegation and VeBetter X-to-Earn integration.
Changelog #
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Versioning by phase: each phase is built in small -dev sub-versions
and closes with a consolidation release. Phase 1 runs from 0.0.1-dev
and closes at 0.1.0-dev; Phase 2 starts at 0.1.1-dev and closes at
0.2.0-dev, and so on.
0.0.5-dev #
Phase 1 in progress: secp256k1 signatures and public key recovery.
Added #
VeChainKeyPair.sign, which signs a 32-byte hash and returns aVeChainSignatureVeChainSignature: a validated 65-byte signature (r + s + recovery) withfromBytes,bytes,r,s,recovery, value equality and a hextoStringVeChainSignature.recoverPublicKeyandVeChainSignature.recoverAddress, which identify the signer of a hashsignandrecoverPublicKeyin the internalVeChainSecp256k1class, with the recovery byte and public key recovery implemented by the SDK (SEC 1, section 4.1.6)- 26 unit tests, including the official signature vector from the VeChain SDK for JavaScript and an independent vector with recovery byte 1
- Example:
example/phase1/signature_example.dart
Design Decisions #
- Signatures use RFC 6979 (a deterministic nonce derived with HMAC-SHA256), so the same hash and key always give the same signature, matching the official SDK byte for byte
- Signatures are always normalized to a low S, because the VeChainThor transaction pool rejects high-S signatures (including the gas payer signature under VIP-191) to prevent signature malleability
VeChainSignature.fromBytesrejects a high S, where the official SDK accepts it; such a signature would be rejected by the network anyway, so the SDK reports it early with a clear message- The recovery byte is 0 or 1, as in the official SDK, not 27 or 28 as in Ethereum transactions
- Only 32-byte hashes can be signed or recovered; the SDK never signs a raw message
Status #
Phase 1 in progress: signatures and public key recovery complete and
verified against the official VeChain signature vector.
Not ready for production use.
Next: Mnemonic (BIP-39) (0.0.6-dev).
0.0.4-dev #
Phase 1 in progress: secp256k1 key pairs, address derivation, and the EIP-55 address checksum.
Added #
VeChainKeyPair.generate, usingRandom.secure()and discarding any value outside the valid range [1, n - 1]VeChainKeyPair.fromPrivateKey, validating the key length and rangeVeChainKeyPairgetters for the private key, the 65-byte uncompressed public key, the 33-byte compressed public key, and the addressVeChainAddress.fromPublicKey(compressed or uncompressed key),VeChainAddress.parse, andVeChainAddress.fromBytesVeChainAddress.toStringwith the EIP-55 mixed-case checksum, and value equality by bytesVeChainCryptoExceptionfor invalid keys and curve points, andVeChainAddressExceptionfor invalid addresses- 67 unit tests, including the official key and address vectors from the VeChain SDK for JavaScript and the EIP-55 specification vectors
- Example:
example/phase1/keypair_example.dart
Design Decisions #
VeChainAddress.parseenforces EIP-55: a mixed-case address must match its checksum; the official SDK accepts any mixed case without checking it- Short addresses are rejected instead of being padded with zeros, as
the official
Address.ofdoes, because padding produces a different valid-looking address - Public keys are decoded and validated explicitly: only
0x02/0x03(33 bytes) or0x04(65 bytes), with the curve equation checked and compressed points decompressed by the SDK itself, because pointycastle'sdecodePointskips the on-curve check for uncompressed points - Key pair getters return copies and
toStringshows only the address; private key bytes cannot be reliably wiped from memory in Dart, so the SDK limits exposure instead of promising to erase them - secp256k1 operations live in an internal
VeChainSecp256k1class shared by keys and addresses; it is not exported
Status #
Phase 1 in progress: key pairs, address derivation and the EIP-55
checksum complete and verified against the official VeChain vectors.
Not ready for production use.
Next: Signatures and public key recovery (0.0.5-dev).
0.0.3-dev #
Phase 1 in progress: the two hash functions VeChainThor uses, and a strict hex codec.
Added #
VeChainHash.blake2b256andVeChainHash.keccak256, each returning 32 bytesVeChainHash.blake2b256ConcatandVeChainHash.keccak256Concat, which hash several parts as if they were concatenated, mirroring the node's multi-input hash functionsVeChainHex.encode(always0xplus lowercase digits) andVeChainHex.decode(optional0xprefix, any case)VeChainCodecException, thrown for invalid hex strings- 33 unit tests, including the official BLAKE2b-256 and Keccak-256 vectors from the VeChain SDK for JavaScript
- Example:
example/phase1/hash_example.dart
Design Decisions #
- Keccak-256 is the legacy Keccak used by Ethereum and by the
VeChainThor node (
NewLegacyKeccak256), not SHA3-256; a dedicated test guards against mixing them up - BLAKE2b is configured with a 32-byte digest explicitly, because the pointycastle default is 64 bytes
VeChainHex.decoderejects an odd number of digits instead of padding with a leading zero as the officialHextype does: this codec handles bytes (hashes, addresses, signatures), where a missing digit is a copy error, not an equivalent value
Status #
Phase 1 in progress: hashing (BLAKE2b-256, Keccak-256) and the hex
codec complete and verified against the official VeChain vectors.
Not ready for production use.
Next: Keypair, address and checksum (0.0.4-dev).
0.0.2-dev #
Phase 1 in progress: network configuration, the identity every transaction depends on.
Added #
VeChainNetwork: an immutable network definition withname,genesisId,nodeUrl, a derivedchainTag, and anodeUrigetter- Official networks as
constvalues, usable as default parameters:VeChainNetwork.mainnet(chain tag0x4a),VeChainNetwork.testnet(0x27) andVeChainNetwork.solo(0xf6) VeChainNetwork.customfor private or local nodes, with validation: non-empty name, a genesis ID of0xplus 64 hex characters, and an absolutehttp/httpsnode URL with a host- Input normalization in
VeChainNetwork.custom: surrounding whitespace is trimmed, the genesis ID is lowercased, and trailing slashes are removed from the node URL - Value equality (
==andhashCode) and a readabletoStringthat shows the chain tag in hex VeChainNetworkException, thrown for any invalid network definition- 27 unit tests covering the official constants, custom networks, normalization, equality, and every validation error
- Example:
example/phase1/network_example.dart
Design Decisions #
- The chain tag is derived from the last byte of the genesis ID instead of being stored, so a network with an inconsistent chain tag cannot be built
nodeUrlis aStringrather than aUri, becauseUricannot beconst; official networks need to beconstto work as default parameter values- The solo node uses
http://127.0.0.1:8669instead oflocalhost, following the official SDK, which does so to avoid IPv6 resolution issues - The EVM chain ID (
0x186a9on mainnet,0x186aaon testnet) is intentionally left out: native VeChain transactions use the chain tag, and the EVM chain ID will be added with the contracts phase
0.0.1-dev #
Added #
- Project scaffolding: package structure, MIT license, lint rules
(
very_good_analysis), CI workflow, andpre_commitscripts for macOS/Linux (.sh) and Windows (.ps1) - Test layout: unit tests in
test/src/mirroringlib/src/, and integration tests against the VeChain testnet intest/integration/