wative-core 2.4.7 → 2.5.1

package/dist/{svm-BVmGEWtP.d.cts → svm-CjNIJZ4l.d.cts}

@@ -1,4 +1,4 @@
-import { c as Address, G as SvmTxBuildParams, F as SvmTransaction } from './workspace-B3nsEAmk.cjs';
+import { c as Address, J as SvmTxBuildParams, I as SvmTransaction } from './workspace-DqUdScht.cjs';
 
 interface SvmInstruction {
     readonly programId: string;

package/dist/{svm-B0khNLa5.d.ts → svm-D8zsWS64.d.ts}

@@ -1,4 +1,4 @@
-import { c as Address, G as SvmTxBuildParams, F as SvmTransaction } from './workspace-B3nsEAmk.js';
+import { c as Address, J as SvmTxBuildParams, I as SvmTransaction } from './workspace-DqUdScht.js';
 
 interface SvmInstruction {
     readonly programId: string;

package/dist/{workspace-B3nsEAmk.d.cts → workspace-DqUdScht.d.cts}

@@ -44,7 +44,7 @@ interface NetworkInit {
     };
     multicallAddress?: string;
     color?: string;
-    vm: ChainVM;
+    vm: VmToken;
 }
 declare class Network {
     readonly slug: Slug;
@@ -58,7 +58,7 @@ declare class Network {
     };
     readonly multicallAddress?: string;
     readonly color?: string;
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     
     get symbol(): string;
     
@@ -111,6 +111,7 @@ type SuiAddress = Brand<string, "SuiAddress">;
 type ChainId = Brand<number, "ChainId">;
 type AssetId = Brand<number, "AssetId">;
 type ChainVM = "evm" | "svm" | "sui";
+type VmToken = ChainVM | (string & {});
 
 type NetworkLike = Network | ChainId | string;
 
@@ -233,8 +234,34 @@ interface SvmTxBuildParams {
     addressLookupTables?: ReadonlyArray<string>;
     memo?: string;
 }
+
+type AssetRef = {
+    native: true;
+} | {
+    address: string;
+} | {
+    symbol: string;
+};
+
+interface TransferRequest {
+    to: string;
+    asset?: AssetRef;
+    amount: bigint;
+}
+
+type TransferPayload = {
+    readonly vm: "evm";
+    readonly to: string;
+    readonly value: bigint;
+    readonly data: string;
+} | {
+    readonly vm: "svm";
+    readonly recipient: string;
+    readonly amount: bigint;
+    readonly instructions?: ReadonlyArray<unknown>;
+};
 interface Transaction {
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     readonly status: TransactionStatus;
     sign(): Promise<this> | this;
     send(): TransactionTracker;
@@ -261,7 +288,7 @@ interface TransactionStateChange {
 }
 interface TransactionReceipt {
     readonly hash: string;
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     readonly blockNumber: number | null;
     readonly blockHash: string | null;
     readonly index: number | null;
@@ -435,7 +462,7 @@ declare class SvmTransaction implements Transaction {
 
 interface AddressInit {
     publicKey: EvmAddress | SvmAddress | SuiAddress;
-    vm: ChainVM;
+    vm: VmToken;
     network: Network;
     ciphertext: string;
     assets?: Asset[];
@@ -444,7 +471,7 @@ interface AddressInit {
 declare class Address {
     #private;
     readonly publicKey: EvmAddress | SvmAddress | SuiAddress;
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     readonly network: Network;
     readonly assets: AssetCollection;
     
@@ -471,6 +498,8 @@ declare class Address {
     buildTransaction(params: EvmTxBuildParams): EvmTransaction;
     buildTransaction(params: SvmTxBuildParams): SvmTransaction;
     
+    buildTransferPayload(req: TransferRequest): TransferPayload;
+    
     signTransaction<T extends Transaction>(transaction: T): T;
     
     sendTransaction(transaction: Transaction): TransactionTracker;
@@ -481,6 +510,10 @@ declare class Address {
     refreshBalances(assetId: AssetId): Settling<AssetBalance>;
     readonly _wallet: Wallet;
 }
+declare class EvmSigner extends Address {
+}
+declare class SvmSigner extends Address {
+}
 
 interface WalletInit {
     id: number;
@@ -498,12 +531,12 @@ declare class Wallet {
     
     _addAddress(address: Address): void;
     _setAddresses(addresses: Address[]): void;
-    get evm(): Address | null;
-    get svm(): Address | null;
+    get evm(): EvmSigner | null;
+    get svm(): SvmSigner | null;
     get sui(): Address | null;
     
     toJson(): ReadonlyArray<{
-        vm: ChainVM;
+        vm: VmToken;
         publicKey: string;
         network: {
             slug: Slug;
@@ -546,7 +579,7 @@ interface PersistedWallet {
 }
 interface PersistedAddress {
     publicKey: string;
-    vm: ChainVM;
+    vm: VmToken;
     networkSlug: string;
     ciphertext: string;
 }
@@ -778,4 +811,4 @@ declare class Workspace {
     } | null;
 }
 
-export { Account as A, type Slug as B, type ChainId as C, type SvmAddress as D, type EvmAddress as E, SvmTransaction as F, type SvmTxBuildParams as G, type TransactionReceipt as H, type TransactionStateChange as I, type TransactionStatus as J, type TransactionTracker as K, type LogLevel as L, type WalletCollection as M, Network as N, type OpenOptions as O, Provider as P, WativeError as Q, Record$1 as R, type Settling as S, type Transaction as T, type WativeErrorCode as U, type WativeErrorOpts as V, Wallet as W, Workspace as X, type WorkspaceConfig as Y, newMnemonic as Z, type AccountCollection as a, type AccountOrgType as b, Address as c, Asset as d, type AssetBalance as e, type AssetCollection as f, type AssetId as g, type AssetInitObject as h, type ChainVM as i, ConsoleSink as j, type ContainerState as k, type EvmRawTx as l, EvmTransaction as m, type EvmTxBuildParams as n, EvmTxType as o, type LogRecord as p, type LogSink as q, Logger as r, type LoggerConfig as s, type NetworkCollection as t, type NetworkInit as u, type NetworkLike as v, type RecordInit as w, type RecordType as x, type SimulationResult as y, type SinkConfig as z };
+export { type WativeErrorCode as $, Account as A, type SimulationResult as B, type ChainId as C, type SinkConfig as D, type EvmAddress as E, type Slug as F, type SvmAddress as G, SvmSigner as H, SvmTransaction as I, type SvmTxBuildParams as J, type TransactionReceipt as K, type LogLevel as L, type TransactionStateChange as M, Network as N, type OpenOptions as O, Provider as P, type TransactionStatus as Q, Record$1 as R, type Settling as S, type Transaction as T, type TransactionTracker as U, type TransferPayload as V, type TransferRequest as W, type VmToken as X, Wallet as Y, type WalletCollection as Z, WativeError as _, type AccountCollection as a, type WativeErrorOpts as a0, Workspace as a1, type WorkspaceConfig as a2, newMnemonic as a3, type SuiAddress as a4, type AccountOrgType as b, Address as c, Asset as d, type AssetBalance as e, type AssetCollection as f, type AssetId as g, type AssetInitObject as h, type AssetRef as i, type ChainVM as j, ConsoleSink as k, type ContainerState as l, type EvmRawTx as m, EvmSigner as n, EvmTransaction as o, type EvmTxBuildParams as p, EvmTxType as q, type LogRecord as r, type LogSink as s, Logger as t, type LoggerConfig as u, type NetworkCollection as v, type NetworkInit as w, type NetworkLike as x, type RecordInit as y, type RecordType as z };

package/dist/{workspace-B3nsEAmk.d.ts → workspace-DqUdScht.d.ts}

@@ -44,7 +44,7 @@ interface NetworkInit {
     };
     multicallAddress?: string;
     color?: string;
-    vm: ChainVM;
+    vm: VmToken;
 }
 declare class Network {
     readonly slug: Slug;
@@ -58,7 +58,7 @@ declare class Network {
     };
     readonly multicallAddress?: string;
     readonly color?: string;
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     
     get symbol(): string;
     
@@ -111,6 +111,7 @@ type SuiAddress = Brand<string, "SuiAddress">;
 type ChainId = Brand<number, "ChainId">;
 type AssetId = Brand<number, "AssetId">;
 type ChainVM = "evm" | "svm" | "sui";
+type VmToken = ChainVM | (string & {});
 
 type NetworkLike = Network | ChainId | string;
 
@@ -233,8 +234,34 @@ interface SvmTxBuildParams {
     addressLookupTables?: ReadonlyArray<string>;
     memo?: string;
 }
+
+type AssetRef = {
+    native: true;
+} | {
+    address: string;
+} | {
+    symbol: string;
+};
+
+interface TransferRequest {
+    to: string;
+    asset?: AssetRef;
+    amount: bigint;
+}
+
+type TransferPayload = {
+    readonly vm: "evm";
+    readonly to: string;
+    readonly value: bigint;
+    readonly data: string;
+} | {
+    readonly vm: "svm";
+    readonly recipient: string;
+    readonly amount: bigint;
+    readonly instructions?: ReadonlyArray<unknown>;
+};
 interface Transaction {
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     readonly status: TransactionStatus;
     sign(): Promise<this> | this;
     send(): TransactionTracker;
@@ -261,7 +288,7 @@ interface TransactionStateChange {
 }
 interface TransactionReceipt {
     readonly hash: string;
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     readonly blockNumber: number | null;
     readonly blockHash: string | null;
     readonly index: number | null;
@@ -435,7 +462,7 @@ declare class SvmTransaction implements Transaction {
 
 interface AddressInit {
     publicKey: EvmAddress | SvmAddress | SuiAddress;
-    vm: ChainVM;
+    vm: VmToken;
     network: Network;
     ciphertext: string;
     assets?: Asset[];
@@ -444,7 +471,7 @@ interface AddressInit {
 declare class Address {
     #private;
     readonly publicKey: EvmAddress | SvmAddress | SuiAddress;
-    readonly vm: ChainVM;
+    readonly vm: VmToken;
     readonly network: Network;
     readonly assets: AssetCollection;
     
@@ -471,6 +498,8 @@ declare class Address {
     buildTransaction(params: EvmTxBuildParams): EvmTransaction;
     buildTransaction(params: SvmTxBuildParams): SvmTransaction;
     
+    buildTransferPayload(req: TransferRequest): TransferPayload;
+    
     signTransaction<T extends Transaction>(transaction: T): T;
     
     sendTransaction(transaction: Transaction): TransactionTracker;
@@ -481,6 +510,10 @@ declare class Address {
     refreshBalances(assetId: AssetId): Settling<AssetBalance>;
     readonly _wallet: Wallet;
 }
+declare class EvmSigner extends Address {
+}
+declare class SvmSigner extends Address {
+}
 
 interface WalletInit {
     id: number;
@@ -498,12 +531,12 @@ declare class Wallet {
     
     _addAddress(address: Address): void;
     _setAddresses(addresses: Address[]): void;
-    get evm(): Address | null;
-    get svm(): Address | null;
+    get evm(): EvmSigner | null;
+    get svm(): SvmSigner | null;
     get sui(): Address | null;
     
     toJson(): ReadonlyArray<{
-        vm: ChainVM;
+        vm: VmToken;
         publicKey: string;
         network: {
             slug: Slug;
@@ -546,7 +579,7 @@ interface PersistedWallet {
 }
 interface PersistedAddress {
     publicKey: string;
-    vm: ChainVM;
+    vm: VmToken;
     networkSlug: string;
     ciphertext: string;
 }
@@ -778,4 +811,4 @@ declare class Workspace {
     } | null;
 }
 
-export { Account as A, type Slug as B, type ChainId as C, type SvmAddress as D, type EvmAddress as E, SvmTransaction as F, type SvmTxBuildParams as G, type TransactionReceipt as H, type TransactionStateChange as I, type TransactionStatus as J, type TransactionTracker as K, type LogLevel as L, type WalletCollection as M, Network as N, type OpenOptions as O, Provider as P, WativeError as Q, Record$1 as R, type Settling as S, type Transaction as T, type WativeErrorCode as U, type WativeErrorOpts as V, Wallet as W, Workspace as X, type WorkspaceConfig as Y, newMnemonic as Z, type AccountCollection as a, type AccountOrgType as b, Address as c, Asset as d, type AssetBalance as e, type AssetCollection as f, type AssetId as g, type AssetInitObject as h, type ChainVM as i, ConsoleSink as j, type ContainerState as k, type EvmRawTx as l, EvmTransaction as m, type EvmTxBuildParams as n, EvmTxType as o, type LogRecord as p, type LogSink as q, Logger as r, type LoggerConfig as s, type NetworkCollection as t, type NetworkInit as u, type NetworkLike as v, type RecordInit as w, type RecordType as x, type SimulationResult as y, type SinkConfig as z };
+export { type WativeErrorCode as $, Account as A, type SimulationResult as B, type ChainId as C, type SinkConfig as D, type EvmAddress as E, type Slug as F, type SvmAddress as G, SvmSigner as H, SvmTransaction as I, type SvmTxBuildParams as J, type TransactionReceipt as K, type LogLevel as L, type TransactionStateChange as M, Network as N, type OpenOptions as O, Provider as P, type TransactionStatus as Q, Record$1 as R, type Settling as S, type Transaction as T, type TransactionTracker as U, type TransferPayload as V, type TransferRequest as W, type VmToken as X, Wallet as Y, type WalletCollection as Z, WativeError as _, type AccountCollection as a, type WativeErrorOpts as a0, Workspace as a1, type WorkspaceConfig as a2, newMnemonic as a3, type SuiAddress as a4, type AccountOrgType as b, Address as c, Asset as d, type AssetBalance as e, type AssetCollection as f, type AssetId as g, type AssetInitObject as h, type AssetRef as i, type ChainVM as j, ConsoleSink as k, type ContainerState as l, type EvmRawTx as m, EvmSigner as n, EvmTransaction as o, type EvmTxBuildParams as p, EvmTxType as q, type LogRecord as r, type LogSink as s, Logger as t, type LoggerConfig as u, type NetworkCollection as v, type NetworkInit as w, type NetworkLike as x, type RecordInit as y, type RecordType as z };

package/examples/20-custom-chain-dialect.test.cjs

@@ -0,0 +1,155 @@
+// 20 — Custom chain: subclass ChainDialect and register a vm to add a blockchain the library does not ship; the "xvm" chain, its toy formats and stand-in signer are illustrative only.
+
+const test = require("node:test");
+const assert = require("node:assert");
+const { mkdtempSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+const { Workspace, Network, Address, ChainDialect, registerDialect } = require("wative-core");
+
+// A super-simple, dependency-free digest standing in for a real hash — illustrative only, not collision-resistant.
+function toyHash(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+// The signer subclass a chain author exports, mirroring EvmSigner / SvmSigner.
+class XvmSigner extends Address {}
+
+// The dialect a chain author writes: the keyless ChainDialect contract for "xvm".
+class XvmDialect extends ChainDialect {
+  get vm() {
+    return "xvm";
+  }
+  get curve() {
+    return "ed25519";
+  }
+
+  signMessage(ctx, message) {
+    const raw = ctx._signBytes(new TextEncoder().encode(`xvm:${message}`));
+    return `xvm-sig:${Buffer.from(raw).toString("hex")}`;
+  }
+  signMessageEncoded(ctx, message, _encoding) {
+    return { signature: this.signMessage(ctx, message), messageHash: `0x${toyHash(message)}` };
+  }
+  signTypedData(ctx, typedData, _chainId) {
+    const payload = JSON.stringify(typedData);
+    return {
+      signature: this.signMessage(ctx, payload),
+      domainSeparator: `0x${toyHash(`domain:${payload}`)}`,
+      structHash: `0x${toyHash(`struct:${payload}`)}`,
+    };
+  }
+  buildTransaction(ctx, params) {
+    return { vm: "xvm", from: String(ctx.publicKey), to: params.to, value: params.value ?? 0n, nonce: params.nonce ?? 0 };
+  }
+  buildTransferPayload(ctx, req) {
+    const payload = { vm: "xvm", from: String(ctx.publicKey), to: req.to, amount: req.amount };
+    if (req.asset && req.asset.address) payload.token = req.asset.address;
+    return payload;
+  }
+  derive(seed, index) {
+    const h = toyHash(`${Buffer.from(seed).toString("hex")}:${index}`);
+    return { publicKey: `xvm1${h}${index}`, privateKey: `xsk1${h}${index}` };
+  }
+  addressFromPrivateKey(privateKey) {
+    if (typeof privateKey !== "string" || !privateKey.startsWith("xsk1")) throw new Error("malformed xvm private key");
+    return `xvm1${privateKey.slice(4)}`;
+  }
+  privateKeyMatches(privateKey, publicKey) {
+    try {
+      return this.addressFromPrivateKey(privateKey) === publicKey;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// One call teaches the library about "xvm" and opens the vm whitelist to that token.
+registerDialect("xvm", () => new XvmDialect());
+
+test("a registered vm becomes a first-class network; an unknown vm is refused", async () => {
+  const root = mkdtempSync(join(tmpdir(), "wative-xvm-net-"));
+  const ws = await Workspace.open({ path: root, password: "wsp-pwd" });
+
+  const xnet = new Network({
+    slug: "xvm-testnet",
+    name: "XVM Testnet",
+    chainId: 909090,
+    rpcUrl: "https://rpc.xvm.example",
+    nativeCurrency: { name: "XVM", symbol: "XVM", decimals: 9 },
+    vm: "xvm",
+  });
+  await ws.networks.add(xnet);
+  assert.strictEqual(ws.networks.bySlug("xvm-testnet").vm, "xvm");
+
+  assert.throws(
+    () =>
+      new Network({
+        slug: "nope-net",
+        name: "Nope",
+        chainId: 111111,
+        rpcUrl: "https://nope.example",
+        nativeCurrency: { name: "N", symbol: "N", decimals: 9 },
+        vm: "totally-unregistered",
+      }),
+  );
+
+  await ws.lock();
+});
+
+test("the custom dialect signs, builds a tx, and transfers via a keyless ctx", () => {
+  const dialect = new XvmDialect();
+  assert.strictEqual(dialect.vm, "xvm");
+  assert.strictEqual(dialect.curve, "ed25519");
+
+  const ctx = {
+    publicKey: "xvm1deadbeef0",
+    vm: "xvm",
+    network: null,
+    assets: [],
+    _signBytes: (bytes) => new Uint8Array([bytes.length & 0xff, 0x42, 0x99]),
+  };
+
+  const sig = dialect.signMessage(ctx, "hello");
+  assert.ok(sig.startsWith("xvm-sig:"));
+
+  const tx = dialect.buildTransaction(ctx, { to: "xvm1recipient", value: 1000n, nonce: 7 });
+  assert.strictEqual(tx.vm, "xvm");
+  assert.strictEqual(tx.from, "xvm1deadbeef0");
+  assert.strictEqual(tx.to, "xvm1recipient");
+  assert.strictEqual(tx.nonce, 7);
+
+  const native = dialect.buildTransferPayload(ctx, { to: "xvm1bob", amount: 500n });
+  assert.strictEqual(native.to, "xvm1bob");
+  assert.strictEqual(native.amount, 500n);
+  assert.strictEqual(native.token, undefined);
+
+  const token = dialect.buildTransferPayload(ctx, { to: "xvm1bob", asset: { address: "xtoken1" }, amount: 5n });
+  assert.strictEqual(token.token, "xtoken1");
+});
+
+test("the custom dialect derives addresses and round-trips private keys", () => {
+  const dialect = new XvmDialect();
+  const seed = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+
+  const { publicKey, privateKey } = dialect.derive(seed, 0);
+  assert.ok(publicKey.startsWith("xvm1"));
+  assert.ok(privateKey.startsWith("xsk1"));
+
+  assert.strictEqual(dialect.addressFromPrivateKey(privateKey), publicKey);
+  assert.ok(dialect.privateKeyMatches(privateKey, publicKey));
+  assert.ok(!dialect.privateKeyMatches("xsk1wrongkey", publicKey));
+  assert.ok(!dialect.privateKeyMatches("not-even-an-xvm-key", publicKey));
+
+  assert.notStrictEqual(dialect.derive(seed, 1).publicKey, publicKey);
+});
+
+test("XvmSigner extends Address — the per-chain signer pattern", () => {
+  assert.ok(XvmSigner.prototype instanceof Address);
+});

package/examples/21-token-transfer.test.cjs

@@ -0,0 +1,85 @@
+// 21 — Token-aware buildTransferPayload(): one intent lowered per chain into the buildTransaction payload — native value, ERC-20 by address, SPL by mint, and by symbol. Payload only (does not send); amounts are raw base units.
+
+const test = require("node:test");
+const assert = require("node:assert");
+const { mkdtempSync } = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+
+const { Workspace } = require("wative-core");
+
+const MNEMONIC =
+  "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
+
+// Real mainnet token identifiers, used only for their format; the EVM address is lowercase and gets canonicalized.
+const USDC_EVM = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
+const USDC_SVM_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+
+// A workspace with two wallets: wallet 0 sends, wallet 1's public keys are valid recipients on each chain.
+async function twoWallets() {
+  const root = mkdtempSync(join(tmpdir(), "wative-transfer-"));
+  const ws = await Workspace.open({ path: root, password: "wsp-pwd" });
+  const acc = await ws.accounts.create("Desk", "wsp-pwd", MNEMONIC);
+  await acc.deriveWallets(1);
+  return { ws, w0: acc.wallets[0], w1: acc.wallets[1] };
+}
+
+test("buildTransferPayload() —native value on EVM and SVM (asset omitted)", async () => {
+  const { ws, w0, w1 } = await twoWallets();
+
+  const evmTx = w0.evm.buildTransferPayload({ to: String(w1.evm.publicKey), amount: 1_000_000_000_000_000n });
+  assert.strictEqual(String(evmTx.to).toLowerCase(), String(w1.evm.publicKey).toLowerCase());
+  assert.strictEqual(evmTx.value, 1_000_000_000_000_000n);
+
+  const svmTx = w0.svm.buildTransferPayload({ to: String(w1.svm.publicKey), amount: 5000n });
+  assert.ok(svmTx);
+
+  await ws.lock();
+});
+
+test("buildTransferPayload() —EVM ERC-20 by contract address", async () => {
+  const { ws, w0, w1 } = await twoWallets();
+  const tx = w0.evm.buildTransferPayload({ to: String(w1.evm.publicKey), asset: { address: USDC_EVM }, amount: 1_000_000n });
+
+  assert.strictEqual(String(tx.to).toLowerCase(), USDC_EVM.toLowerCase());
+  assert.strictEqual(tx.value, 0n);
+  assert.strictEqual(String(tx.data).slice(0, 10), "0xa9059cbb");
+  assert.strictEqual((String(tx.data).length - 2) / 2, 68);
+
+  await ws.lock();
+});
+
+test("buildTransferPayload() —SVM SPL by mint prepends an idempotent recipient-ATA create", async () => {
+  const { ws, w0, w1 } = await twoWallets();
+  const tx = w0.svm.buildTransferPayload({ to: String(w1.svm.publicKey), asset: { address: USDC_SVM_MINT }, amount: 1_000_000n });
+
+  assert.ok(Array.isArray(tx.instructions));
+  assert.strictEqual(tx.instructions.length, 2);
+
+  await ws.lock();
+});
+
+test("buildTransferPayload() —by token symbol resolves to native vs token", async () => {
+  const { ws, w0, w1 } = await twoWallets();
+
+  const usdc = w0.evm.buildTransferPayload({ to: String(w1.evm.publicKey), asset: { symbol: "USDC" }, amount: 1_000_000n });
+  assert.strictEqual(String(usdc.data).slice(0, 10), "0xa9059cbb");
+
+  const eth = w0.evm.buildTransferPayload({ to: String(w1.evm.publicKey), asset: { symbol: "ETH" }, amount: 777n });
+  assert.strictEqual(eth.value, 777n);
+
+  await ws.lock();
+});
+
+test("buildTransferPayload() —an out-of-range amount is a PARAMETER_ERROR", async () => {
+  const { ws, w0, w1 } = await twoWallets();
+  let code;
+  try {
+    w0.evm.buildTransferPayload({ to: String(w1.evm.publicKey), asset: { address: USDC_EVM }, amount: -1n });
+  } catch (e) {
+    code = e.code;
+  }
+  assert.strictEqual(code, "PARAMETER_ERROR");
+
+  await ws.lock();
+});

package/examples/README.md

@@ -34,8 +34,8 @@ All tests work fully offline — no RPC calls, no real networks. Each test creat
 | [01-quick-start.test.cjs](01-quick-start.test.cjs) | Open a workspace, create an HD account, derive 5 wallets, inspect EVM + Solana addresses, lock. |
 | [02-hd-account.test.cjs](02-hd-account.test.cjs) | HD-specific flows — deriving / slicing wallets, dumping the mnemonic, account-level passwords with `resetPassword`, round-trip across lock + reopen. |
 | [03-pk-account.test.cjs](03-pk-account.test.cjs) | PK accounts — creating from a private key, importing more keys, and the three key formats accepted (EVM hex, Solana base58, `solana-keygen` JSON) with the chain inferred from the key. Also shows each import producing an address on both chains, duplicate-import rejection, and dropping wallets. |
-| [04-network-management.test.cjs](04-network-management.test.cjs) | The 10 pre-loaded networks, adding a brand-new network, overriding a pre-loaded RPC URL via `update()`, dropping user networks, the built-in protection guard. |
-| [05-asset-management.test.cjs](05-asset-management.test.cjs) | The 25 pre-loaded tokens, adding a custom user token, id collision rejection, contract-address collision rejection, dropping user tokens, `workspace.filter(q, "Asset")` search. |
+| [04-network-management.test.cjs](04-network-management.test.cjs) | The 14 pre-loaded networks, adding a brand-new network, overriding a pre-loaded RPC URL via `update()`, dropping user networks, the built-in protection guard. |
+| [05-asset-management.test.cjs](05-asset-management.test.cjs) | The 29 pre-loaded tokens, adding a custom user token, id collision rejection, contract-address collision rejection, dropping user tokens, `workspace.filter(q, "Asset")` search. |
 | [06-address-signing.test.cjs](06-address-signing.test.cjs) | Personal-message signing on EVM and Solana, building a transaction fully offline (no RPC). |
 | [07-custom-provider.test.cjs](07-custom-provider.test.cjs) | Taking over the record layer as well, by extending `Provider` rather than `ContainerProvider` — for storage that has its own encryption or its own idea of a record. Longer than [19](19-simple-provider.test.cjs); start there unless you need this. |
 | [08-persistence.test.cjs](08-persistence.test.cjs) | Round-trip across `lock()` + reopen — multiple accounts, user networks, custom assets, and logger configuration. |
@@ -50,6 +50,8 @@ All tests work fully offline — no RPC calls, no real networks. Each test creat
 | [17-locked-state.test.cjs](17-locked-state.test.cjs) | What locking enforces — which operations refuse and with which error code, that a locked account holds no mnemonic in the clear, and that unlocking restores identical behaviour. |
 | [18-envelope-v3.test.cjs](18-envelope-v3.test.cjs) | `HybridProviderV3` — writing a workspace that derives one key for the whole workspace instead of one per stored secret, reopening it, and confirming a wrong password is still refused. |
 | [19-simple-provider.test.cjs](19-simple-provider.test.cjs) | The short way to write a storage backend — extend `ContainerProvider` and implement six methods that move bytes. Runs a whole workspace on a `Map`, signs from a derived address, reopens it, and checks that nothing readable reaches the store. |
+| [20-custom-chain-dialect.test.cjs](20-custom-chain-dialect.test.cjs) | Adding a whole new blockchain — subclass `ChainDialect` and `registerDialect` its vm, the same shape as extending `Provider`. A fictional `xvm` chain becomes a first-class network (and an unregistered vm is still refused), its dialect signs / builds a transaction / builds transfer payloads / derives through the keyless `ChainCtx`, and `XvmSigner` names the per-chain signer just as `EvmSigner` / `SvmSigner` do. |
+| [21-token-transfer.test.cjs](21-token-transfer.test.cjs) | `address.buildTransferPayload({ to, asset, amount })` — one intent lowered per chain into the payload for `buildTransaction`: native value, EVM ERC-20 by contract address, SVM SPL by mint (with an idempotent recipient-ATA create), and by token `symbol`. Payload only (does not send); `amount` is raw base units. |
 
 ## Adapting for your project
 
@@ -69,3 +71,4 @@ map.
 - **No real money.** The mnemonics and private keys used in these tests are well-known testing values. Never fund them.
 - **No network calls.** Tests sign offline only. To actually broadcast a transaction, configure a real RPC URL on the network and call `address.sendTransaction(tx)` — see the README for the full lifecycle.
 - **Custom Provider example** uses a deliberately simple cipher (XOR). Real Providers should seal data with an authenticated cipher — see the bundled `HybridProvider` for a reference implementation.
+- **Custom chain example** uses a fictional chain with a toy hash, toy address/transaction formats, and a stand-in signer — illustrative only. A real chain declares a real curve and real formats; the example shows the extension *shape*, not production cryptography.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wative-core",
-  "version": "2.4.7",
+  "version": "2.5.1",
   "description": "Hyperscale crypto wallet management library — multi-workspace, multi-chain, originally designed for on-chain market makers",
   "type": "module",
   "main": "./dist/index.node.cjs",