@arxiumlabs/sdk 0.5.0 → 0.9.0

package/README.md

@@ -13,7 +13,7 @@ npm install -g @arxiumlabs/sdk   # arx CLI
 
 ## Releasing
 
-Bump `version` here, run the release checks, then push a `sdk-vX.Y.Z` tag. `.github/workflows/sdk.yml` publishes to npm through trusted publishing (no token) with provenance.
+Bump `version` here, run the release checks, then push a `sdk-vX.Y.Z` tag. `.github/workflows/sdk.yml` publishes to npm through trusted publishing (no token). It publishes without a provenance attestation while the repository is private, because npm accepts provenance only from public repositories.
 
 ```sh
 cd Arxium && cargo test -p arxd-runtime writes_typescript_signed_action_fixtures && git diff --exit-code sdk/ts/fixtures
@@ -29,7 +29,28 @@ const rpc = new ArxiumRpc({ rpc: "https://node.example", token: process.env.ARX_
 const payload = encodeTransfer("arx1...", arxToIum("1.5"));
 ```
 
-All token amounts are `bigint`: `1 ARX = 1_000_000_000 IUM`.
+All token amounts are `bigint`: `1 ARX = 1_000_000_000 IUM`. That includes amounts in RPC responses (`balance`, `total_supply`, `frozen_amount`, …): the node writes u128 amounts as plain JSON numbers, so the client parses them with `parseJson`, which never rounds them. `JSON.stringify` throws on a `bigint`, so pass `bigintReplacer` when you serialize a response.
+
+### Fees
+
+An action costs `action_fee + weight × weight_fee`. The weight is the action type's base weight plus the signed action's size in bytes, plus 5,000 when a stateful account policy signs it. `actionFee` matches the node's metering exactly, and the tests check it against weights the node itself produced:
+
+```ts
+const fee = actionFee(await rpc.feeParams(), sender, nonce, payload);            // single-key signature
+const fee2 = actionFee(params, sender, nonce, payload, { signatureLength: multisigSignatureLength(2, 3) }); // before a 2-of-3 multisig signs
+```
+
+`CreateToken` also pays `token_create_fee` (`rpc.actionFee()`). `ACTION_FEE` is deprecated, because it is only the flat floor.
+
+### Reading the chain
+
+`ArxiumRpc` returns typed responses for status, accounts, stake, assets (`listAssets`, `asset`, `assetByAlias`, `assetHolders`, `assetBalance`), attestors, validators (`validator`, `validatorPower`, `operatorValidators`), block effects, evidence and Merkle proofs. Each method takes a type parameter if you need a different shape.
+
+### Sending
+
+`sendAction` signs at the account's current nonce. The node's nonce doesn't count actions still in the mempool, so one client runs sends for the same sender one after another. Concurrent calls each wait their turn and never collide on a nonce. Two separate processes sending for one sender still need their own coordination. For a multisig or programmable-account sender, pass `sign(message, nonce)` instead of `privateKey` and return the combined witness.
+
+`rpc.sendAction({ privateKey, sender, payload })` signs, submits and waits for the block. If the chain refuses the action it throws `ActionDroppedError`, whose `reason` is the node's exact text. `rpc.assets(address)` returns the account's asset balances with `transfer_eligible` and `eligibility_reason`, so an app can check the sending side before the user signs. Walkthrough: https://arxium.network/docs/sdk-quickstart
 
 ### Chain binding
 
@@ -52,6 +73,22 @@ A co-signer should see what they're signing before they sign it. `decodePayload(
 
 Set the resulting address as an admin role (genesis or `SetAdmin`) or as an asset issuer (`TransferIssuer`). To rotate members, move the role to a new multisig address.
 
+### Atomic DvP (delivery versus payment)
+
+`SettleDvp` swaps two assets between two parties in one action: both legs settle or neither does. Each leg is `"native"` (IUM) or `{ asset }` (an RWA asset, with its full compliance gates, or a token). The counterparty signs the order first, at its current nonce. The initiator then sends it and pays the fee:
+
+```ts
+const order: DvpOrder = { give: { asset: bondRef }, giveAmount: 10n, counterparty: buyer, take: { asset: cashRef }, takeAmount: 500n, expiresAt: height + 100n };
+const consent = await signDvpConsent(buyerKey, genesis, seller, order, buyerNonce);    // on the buyer's machine
+await rpc.sendAction({ privateKey: sellerKey, sender: seller, payload: encodeSettleDvp(order, consent) });
+```
+
+Settling consumes the counterparty's nonce, so the consent can't be replayed, and any other action the counterparty sends first cancels it. The node refuses the order after height `expiresAt`. A multisig counterparty's members each sign `dvpConsentBytes(…)` and combine them with `multisigSignature`. A programmable-account counterparty is not supported yet.
+
+### Programmable accounts
+
+The SDK exports bounded account-policy codecs and stateful owner/session/guardian witness helpers. `arx multisig build|sign|combine|link` lets each member sign separately, for both immutable and stateful account addresses. To verify a historical action, `verifySignedAction` needs the proven pre-action policy for stateful witnesses, and `arx verify SIGNATURE --policy FILE` accepts that policy. See [the programmable-account guide](../../docs/Programmable_Accounts.md).
+
 ## Key files
 
 `arx` reads and writes Console's encrypted export JSON unchanged:
@@ -85,7 +122,7 @@ printf '%s' "$SEED_HEX" | arx keys import
 arx keys show --key arxium-devnet-key-abc.json   # no passphrase needed
 
 arx sign transfer arx1recipient 1500000000 --key key.json             # nonce fetched from --rpc
-arx sign transfer arx1recipient 1500000000 --key key.json --nonce 7   # fully offline
+arx sign transfer arx1recipient 1500000000 --key key.json --nonce 7   # skips the nonce lookup; still reads the genesis hash from --rpc
 arx submit signed-action.json
 arx send transfer arx1recipient 1500000000 --key key.json
 
@@ -100,30 +137,51 @@ arx query search arx1address
 arx verify signature
 ```
 
-Supported signed actions are `transfer`, `stake`, `unstake`, `join-validator`, `leave-validator`, `register-bls-key`, `authorize-operator`, `revoke-operator`, `grant-attestation`, `revoke-attestation`, `register-asset`, `issue-asset`, `transfer-asset`, `apply-attestor`, `block-attestor`, `propose-add-attestor`, `propose-remove-attestor`, `propose-unblock-attestor`, `vote` and `execute-proposal`. Amount arguments are raw base-unit integers (IUM for ARX, the asset's smallest unit for an asset).
+`arx sign` always needs a reachable node. Every signature covers the chain's genesis hash (see Chain binding above), and `sign` reads it from `--rpc` (`GET /genesis-hash`) on every run. `--nonce` only skips the account-nonce lookup. There is no fully offline signing mode: with no node the command exits 1 with the fetch error.
+
+Supported signed actions are `transfer`, `stake`, `unstake`, `join-validator`, `leave-validator`, `register-bls-key`, `authorize-operator`, `revoke-operator`, `grant-attestation`, `revoke-attestation`, `register-asset`, `issue-asset`, `transfer-asset`, `apply-attestor`, `block-attestor`, `propose-add-attestor`, `propose-remove-attestor`, `propose-unblock-attestor`, `vote`, `execute-proposal` and `settle-dvp`, plus the issuer, corporate-action and token commands below. Amount arguments are raw base-unit integers (IUM for ARX, the asset's smallest unit for an asset).
 
 ```sh
 arx send apply-attestor "Arxium Bank" <owner>,<owner>,<owner> 2 <evidence-hash> <evidence-uri>   # sender is the 2-of-N multisig; validators vote
 arx send propose-remove-attestor <attestor> "reason"   # validators only; blocks that attestor's grants while the vote runs
 arx send vote <proposal-id> yes   # then, after the window: arx send execute-proposal <proposal-id>
 arx send block-attestor   # attestor emergency stop; only a governance vote lifts it
-arx send register-asset fund-a FUNDA "Fund A" 0 kyc CH,LI   # <asset-id> <symbol> <name> <decimals> [topics] [jurisdictions]
+arx send register-asset fund-a FUNDA "Fund A" 0 kyc CH,LI   # <asset-id> <symbol> <name> <decimals> [topics] [jurisdictions] [controls]
+arx send register-asset fund-b FUNDB "Fund B" 0 - - freeze_asset,recover_holder   # only these issuer controls, forever
 arx send issue-asset arxasset1... 1000
 arx send transfer-asset arxasset1... arx1recipient 100
+arx send set-asset-limits arxasset1... - 150 -   # <max-holders|-> [max-balance-per-holder|-] [max-attestation-age-blocks|-]; - = no limit
+arx send freeze-holder arxasset1... arx1holder   # unfreeze-holder to lift
+arx send freeze-asset arxasset1... "reason"   # unfreeze-asset arxasset1... "reason" to lift
+arx send issue-asset-to arxasset1... arx1holder 100
+arx send lock-holder-amount arxasset1... arx1holder 50 [until-height]   # unlock-holder-amount to release
+arx send forced-transfer arxasset1... arx1from arx1to 10 "court order"
+arx send recover-holder arxasset1... arx1lost arx1replacement
+arx send burn-asset arxasset1... 10
+arx send lock-issuance arxasset1...   # one-way
+arx send transfer-issuer arxasset1... arx1newissuer
+arx send set-metadata-uri arxasset1... ipfs://...   # - clears it
+arx send set-private-claims arxasset1... on|off
+arx send snapshot-holders arxasset1...   # then, by the snapshot height:
+arx send distribute arxasset1... <height> arxasset1payout... 1000
+arx send redeem-holders arxasset1... <height>
+arx send split-asset arxasset1... <height> 2 1
+arx send create-token ABC "Abc Token" 6 1000000 - mintable   # <max-supply|-> mintable|fixed
+arx send mint-token arxasset1... arx1to 100   # transfer-token, burn-token, renounce-mint
+arx dvp-consent arx1seller arxasset1bond... 10 native 500 <expires-at-height> --key buyer.json   # buyer signs; prints the "send" args
+arx send settle-dvp arxasset1bond... 10 arx1buyer native 500 <expires-at-height> <buyer-signature> --key seller.json
+
+arx query assets [arx1address]   # all assets, or one account's balances
+arx query asset arxasset1...
+arx query holders arxasset1...
+arx query balance arx1address arxasset1...
+arx query attestors   # attestor <address>
+arx query validator arx1address
+arx query stakes arx1address
+arx query fee
 ```
 
 Builder docs (devnet quickstart, RWA walkthrough, arx-verify): https://arxium.network/docs
-# Programmable-account tooling (0.1.5)
-
-The SDK exports bounded account-policy codecs and stateful owner/session/guardian
-witness helpers. `arx multisig build|sign|combine|link` provides an individual
-member signing workflow for both immutable and stateful account addresses.
-Historical `verifySignedAction` calls require the proven pre-action policy for
-stateful witnesses; `arx verify SIGNATURE --policy FILE` accepts that policy.
-
-See [the programmable-account guide](../../docs/Programmable_Accounts.md) for
-configuration shapes, fees, block-height windows, recovery and reset requirements.
-
 ## Release validation
 
 CI builds and installs the packed SDK on pull requests. Run `npm ci`,
@@ -133,7 +191,7 @@ public entry point and checks the CLI version; it makes no chain calls.
 
 Publication runs only for an approved `sdk-vX.Y.Z` tag matching package.json.
 The publish job builds its own checkout, checks the packed files and smoke-tests
-the tarball, then publishes that exact tarball with provenance. Existing npm
+the tarball, then publishes that exact tarball (no provenance while the repo is private). Existing npm
 versions cannot be replaced. npm trusted-publisher configuration and release
 authorization are still required; a passing package check is not publication
 or on-chain compatibility proof.

package/dist/actions.d.ts

@@ -1,4 +1,4 @@
-import { POLICY_VARIANT } from "./policy.js";
+import { POLICY_VARIANT, type SpendAsset } from "./policy.js";
 /** These indices are ActionPayload's positional bincode discriminants. Never derive them. */
 export declare const ACTION_VARIANT: {
     readonly transfer: 0;
@@ -39,6 +39,7 @@ export declare const ACTION_VARIANT: {
     readonly executeProposal: 32;
     readonly applyAttestor: 41;
     readonly blockAttestor: 42;
+    readonly settleDvp: 43;
 };
 /** `ActionPayload::Token(TokenAction)` is variant 39; these are `TokenAction`'s own discriminants, written after it. */
 export declare const TOKEN_ACTION = 39;
@@ -66,6 +67,13 @@ declare const TOPIC: {
 };
 export type AssetClass = keyof typeof CLASS;
 export type ClaimTopic = keyof typeof TOPIC;
+/** `IssuerControls` field order — positional bincode, append only. Fixed for the asset's life once registered. */
+export declare const ISSUER_CONTROLS: readonly ["freeze_asset", "freeze_holder", "lock_holder_amount", "forced_transfer", "recover_holder", "redeem", "split", "set_limits", "set_metadata_uri"];
+export type IssuerControl = (typeof ISSUER_CONTROLS)[number];
+export type IssuerControls = Record<IssuerControl, boolean>;
+/** Every power on, the chain's default (what assets had before controls were selectable). */
+export declare const ALL_ISSUER_CONTROLS: IssuerControls;
+/** `controls` omitted means every power on, matching the node's default. */
 export type AssetMetadata = {
     asset_class: AssetClass;
     decimals: number;
@@ -75,7 +83,9 @@ export type AssetMetadata = {
     metadata_uri: string | null;
     symbol: string;
     name: string;
+    controls?: IssuerControls;
 };
+/** @deprecated The flat floor only. The node charges `action_fee + weight × weight_fee`: use `actionFee(await rpc.feeParams(), …)`. */
 export declare const ACTION_FEE = 1000000n;
 export declare function encodeTransfer(to: string, amount: bigint): Uint8Array;
 export declare function encodeJoinValidator(validator: string, stake: bigint, blsPubkey: Uint8Array, blsPop: Uint8Array): Uint8Array;
@@ -128,6 +138,28 @@ export declare function encodeRenounceMint(tokenRef: string): Uint8Array;
 export declare function encodeApplyAttestor(name: string, owners: string[], threshold: number, evidenceHash: string, evidenceUri: string): Uint8Array;
 /** Emergency stop: the sending attestor can no longer grant new attestations. Only a governance vote lifts it. */
 export declare function encodeBlockAttestor(): Uint8Array;
+/**
+ * Atomic delivery-versus-payment. The sender (initiator) delivers `giveAmount` of `give` to `counterparty`, who delivers
+ * `takeAmount` of `take` back, both legs or neither. `"native"` is IUM; `{ asset }` is an RWA asset or a token ref.
+ */
+export type DvpOrder = {
+    give: SpendAsset;
+    giveAmount: bigint;
+    counterparty: string;
+    take: SpendAsset;
+    takeAmount: bigint;
+    expiresAt: bigint;
+};
+/** `DvpTerms.domain`: no `ActionPayload` can start with it, so a consent never doubles as an ordinary action signature. */
+export declare const DVP_DOMAIN = 4294967295;
+/**
+ * What the counterparty signs, mirroring `dvp_consent(…).signing_bytes`: the order, bound to the genesis hash and the
+ * counterparty's current nonce, which settling consumes. Sending any other action first cancels the consent. A multisig
+ * counterparty's members each sign these bytes and combine them with `multisigSignature`.
+ */
+export declare function dvpConsentBytes(genesis: Uint8Array, initiator: string, order: DvpOrder, counterpartyNonce: number | bigint): Uint8Array;
+export declare function signDvpConsent(privateKey: CryptoKey, genesis: Uint8Array, initiator: string, order: DvpOrder, counterpartyNonce: number | bigint): Promise<string>;
+export declare function encodeSettleDvp(order: DvpOrder, counterpartySignature: string): Uint8Array;
 /** `GovernanceAction`'s own discriminants (after `SetChainParams` 0, `TreasurySpend` 1, `ResolveDispute` 2, `ReinstateValidator` 3). Only the attestor actions are encodable here. */
 export declare const GOVERNANCE_ACTION: {
     readonly addAttestor: 4;

package/dist/actions.js

@@ -1,6 +1,6 @@
 import { MULTISIG_TAG, decodeAddress, encodeAddress } from "./bech32.js";
 import { Reader, Writer, asBuffer, fromHex, toHex } from "./bincode.js";
-import { ACCOUNT_POLICY_ACTION, POLICY_VARIANT, encodeAccountPolicy, readAccountPolicy } from "./policy.js";
+import { ACCOUNT_POLICY_ACTION, POLICY_VARIANT, encodeAccountPolicy, readAccountPolicy, readSpendAsset, writeSpendAsset } from "./policy.js";
 /** These indices are ActionPayload's positional bincode discriminants. Never derive them. */
 export const ACTION_VARIANT = {
     transfer: 0, joinValidator: 1, leaveValidator: 2, stake: 3, unstake: 4, registerBlsKey: 6,
@@ -12,13 +12,18 @@ export const ACTION_VARIANT = {
     snapshotHolders: 33, distributeToHolders: 34, redeemHolders: 35, splitAsset: 36,
     verifyClaimProof: 37, setPrivateClaims: 38,
     submitProposal: 30, voteProposal: 31, executeProposal: 32,
-    applyAttestor: 41, blockAttestor: 42,
+    applyAttestor: 41, blockAttestor: 42, settleDvp: 43,
 };
 /** `ActionPayload::Token(TokenAction)` is variant 39; these are `TokenAction`'s own discriminants, written after it. */
 export const TOKEN_ACTION = 39;
 export const TOKEN_VARIANT = { createToken: 0, mintToken: 1, transferToken: 2, burnToken: 3, renounceMint: 4 };
 const CLASS = { other: 0, real_estate: 1, equity: 2, bond: 3, stablecoin: 4, commodity: 5, token: 6 };
 const TOPIC = { kyc: 0, aml: 1, accredited: 2, jurisdiction: 3 };
+/** `IssuerControls` field order — positional bincode, append only. Fixed for the asset's life once registered. */
+export const ISSUER_CONTROLS = ["freeze_asset", "freeze_holder", "lock_holder_amount", "forced_transfer", "recover_holder", "redeem", "split", "set_limits", "set_metadata_uri"];
+/** Every power on, the chain's default (what assets had before controls were selectable). */
+export const ALL_ISSUER_CONTROLS = Object.fromEntries(ISSUER_CONTROLS.map((c) => [c, true]));
+/** @deprecated The flat floor only. The node charges `action_fee + weight × weight_fee`: use `actionFee(await rpc.feeParams(), …)`. */
 export const ACTION_FEE = 1000000n;
 export function encodeTransfer(to, amount) { return new Writer().varint(ACTION_VARIANT.transfer).string(to).varint(amount).bytes(); }
 export function encodeJoinValidator(validator, stake, blsPubkey, blsPop) { return new Writer().varint(ACTION_VARIANT.joinValidator).string(validator).varint(stake).vec(Array.from(blsPubkey), (w, b) => w.u8(b)).vec(Array.from(blsPop), (w, b) => w.u8(b)).bytes(); }
@@ -30,7 +35,8 @@ export function encodeAuthorizeOperator(operator) { return new Writer().varint(A
 export function encodeRevokeOperator() { return new Writer().varint(ACTION_VARIANT.revokeOperator).bytes(); }
 export function encodeGrantAttestation(subject, hash, topics, jurisdiction) { return new Writer().varint(ACTION_VARIANT.grantAttestation).string(subject).string(hash).vec(topics, (w, topic) => w.varint(TOPIC[topic])).option(jurisdiction, (w, value) => w.string(value)).bytes(); }
 export function encodeRevokeAttestation(subject) { return new Writer().varint(ACTION_VARIANT.revokeAttestation).string(subject).bytes(); }
-export function encodeRegisterAsset(assetId, complianceRequired, metadata) { return new Writer().varint(ACTION_VARIANT.registerAsset).string(assetId).bool(complianceRequired).varint(CLASS[metadata.asset_class]).u8(metadata.decimals).vec(metadata.required_claims, (w, topic) => w.varint(TOPIC[topic])).option(metadata.allowed_jurisdictions, (w, codes) => w.vec(codes, (ww, code) => ww.string(code))).option(metadata.max_supply, (w, cap) => w.varint(BigInt(cap))).option(metadata.metadata_uri, (w, uri) => w.string(uri)).string(metadata.symbol).string(metadata.name).bytes(); }
+export function encodeRegisterAsset(assetId, complianceRequired, metadata) { const w = new Writer().varint(ACTION_VARIANT.registerAsset).string(assetId).bool(complianceRequired).varint(CLASS[metadata.asset_class]).u8(metadata.decimals).vec(metadata.required_claims, (w, topic) => w.varint(TOPIC[topic])).option(metadata.allowed_jurisdictions, (w, codes) => w.vec(codes, (ww, code) => ww.string(code))).option(metadata.max_supply, (w, cap) => w.varint(BigInt(cap))).option(metadata.metadata_uri, (w, uri) => w.string(uri)).string(metadata.symbol).string(metadata.name); const controls = metadata.controls ?? ALL_ISSUER_CONTROLS; for (const c of ISSUER_CONTROLS)
+    w.bool(controls[c]); return w.bytes(); }
 export function encodeIssueAsset(asset, amount) { return new Writer().varint(ACTION_VARIANT.issueAsset).string(asset).varint(amount).bytes(); }
 export function encodeTransferAsset(asset, to, amount) { return new Writer().varint(ACTION_VARIANT.transferAsset).string(asset).string(to).varint(amount).bytes(); }
 export function encodeFreezeAsset(asset, frozen, reason) { return new Writer().varint(frozen ? ACTION_VARIANT.freezeAsset : ACTION_VARIANT.unfreezeAsset).string(asset).string(reason).bytes(); }
@@ -73,6 +79,30 @@ export function encodeRenounceMint(tokenRef) { return token("renounceMint").stri
 export function encodeApplyAttestor(name, owners, threshold, evidenceHash, evidenceUri) { return new Writer().varint(ACTION_VARIANT.applyAttestor).string(name).vec(owners, (w, o) => w.string(o)).u8(threshold).string(evidenceHash).string(evidenceUri).bytes(); }
 /** Emergency stop: the sending attestor can no longer grant new attestations. Only a governance vote lifts it. */
 export function encodeBlockAttestor() { return new Writer().varint(ACTION_VARIANT.blockAttestor).bytes(); }
+/** `DvpTerms.domain`: no `ActionPayload` can start with it, so a consent never doubles as an ordinary action signature. */
+export const DVP_DOMAIN = 0xffff_ffff;
+/**
+ * What the counterparty signs, mirroring `dvp_consent(…).signing_bytes`: the order, bound to the genesis hash and the
+ * counterparty's current nonce, which settling consumes. Sending any other action first cancels the consent. A multisig
+ * counterparty's members each sign these bytes and combine them with `multisigSignature`.
+ */
+export function dvpConsentBytes(genesis, initiator, order, counterpartyNonce) {
+    const w = new Writer().varint(DVP_DOMAIN).string(initiator);
+    writeSpendAsset(w, order.give);
+    w.varint(order.giveAmount);
+    writeSpendAsset(w, order.take);
+    w.varint(order.takeAmount).varint(order.expiresAt);
+    return signingBytes(genesis, order.counterparty, counterpartyNonce, w.bytes());
+}
+export async function signDvpConsent(privateKey, genesis, initiator, order, counterpartyNonce) { return toHex(new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, asBuffer(dvpConsentBytes(genesis, initiator, order, counterpartyNonce))))); }
+export function encodeSettleDvp(order, counterpartySignature) {
+    const w = new Writer().varint(ACTION_VARIANT.settleDvp);
+    writeSpendAsset(w, order.give);
+    w.varint(order.giveAmount).string(order.counterparty);
+    writeSpendAsset(w, order.take);
+    w.varint(order.takeAmount).varint(order.expiresAt).string(counterpartySignature);
+    return w.bytes();
+}
 /** `GovernanceAction`'s own discriminants (after `SetChainParams` 0, `TreasurySpend` 1, `ResolveDispute` 2, `ReinstateValidator` 3). Only the attestor actions are encodable here. */
 export const GOVERNANCE_ACTION = { addAttestor: 4, removeAttestor: 5, unblockAttestor: 6 };
 /** An active validator opens a vote. `addAttestor` needs the attestor's multisig address and its owners; applicants who are not validators use `encodeApplyAttestor`. A removal blocks that attestor's new grants while it runs. */
@@ -130,6 +160,7 @@ export function encodePayload({ name, input }) {
         case "executeProposal": return encodeExecuteProposal(BigInt(input.proposal));
         case "applyAttestor": return encodeApplyAttestor(input.name, input.owners, input.threshold, input.evidenceHash, input.evidenceUri);
         case "blockAttestor": return encodeBlockAttestor();
+        case "settleDvp": return encodeSettleDvp({ give: input.give, giveAmount: BigInt(input.giveAmount), counterparty: input.counterparty, take: input.take, takeAmount: BigInt(input.takeAmount), expiresAt: BigInt(input.expiresAt) }, input.counterpartySignature);
         case "createToken": return encodeCreateToken(input.symbol, input.name, input.decimals, BigInt(input.initialSupply), nullableBig(input.maxSupply), input.mintable);
         case "mintToken": return encodeMintToken(input.token, input.to, BigInt(input.amount));
         case "transferToken": return encodeTransferToken(input.token, input.to, BigInt(input.amount));
@@ -168,7 +199,7 @@ export function decodePayload(payload) {
         revokeOperator: () => ({}),
         grantAttestation: () => ({ subject: str(), hash: str(), topics: topics(), jurisdiction: r.option(str) }),
         revokeAttestation: () => ({ subject: str() }),
-        registerAsset: () => ({ assetId: str(), complianceRequired: r.bool(), metadata: { asset_class: known(CLASS_NAME[Number(r.varint())], "asset class"), decimals: r.u8(), required_claims: topics(), allowed_jurisdictions: r.option((rr) => rr.vec(str)), max_supply: r.option(amount), metadata_uri: r.option(str), symbol: str(), name: str() } }),
+        registerAsset: () => ({ assetId: str(), complianceRequired: r.bool(), metadata: { asset_class: known(CLASS_NAME[Number(r.varint())], "asset class"), decimals: r.u8(), required_claims: topics(), allowed_jurisdictions: r.option((rr) => rr.vec(str)), max_supply: r.option(amount), metadata_uri: r.option(str), symbol: str(), name: str(), controls: Object.fromEntries(ISSUER_CONTROLS.map((c) => [c, r.bool()])) } }),
         issueAsset: () => ({ asset: str(), amount: amount() }),
         transferAsset: () => ({ asset: str(), to: str(), amount: amount() }),
         freezeAsset: () => ({ asset: str(), frozen: true, reason: str() }),
@@ -196,6 +227,7 @@ export function decodePayload(payload) {
         executeProposal: () => ({ proposal: amount() }),
         applyAttestor: () => ({ name: str(), owners: r.vec((rr) => rr.string()), threshold: r.u8(), evidenceHash: str(), evidenceUri: str() }),
         blockAttestor: () => ({}),
+        settleDvp: () => ({ give: readSpendAsset(r), giveAmount: amount(), counterparty: str(), take: readSpendAsset(r), takeAmount: amount(), expiresAt: amount(), counterpartySignature: str() }),
         createToken: () => ({ symbol: str(), name: str(), decimals: r.u8(), initialSupply: amount(), maxSupply: r.option(amount), mintable: r.bool() }),
         mintToken: () => ({ token: str(), to: str(), amount: amount() }),
         transferToken: () => ({ token: str(), to: str(), amount: amount() }),

package/dist/cli.js

@@ -3,10 +3,10 @@ import { readFile, writeFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { stdin as input, stderr, stdout } from "node:process";
 import { createPrivateKey, createPublicKey } from "node:crypto";
-import { ArxiumRpc, RpcError, encodeApplyAttestor, encodeBlockAttestor, encodeExecuteProposal, encodeSubmitProposal, encodeVoteProposal, encodeAuthorizeOperator, encodeGrantAttestation, encodeIssueAsset, encodeRegisterAsset, encodeTransferAsset, encodeJoinValidator, encodeLeaveValidator, encodeRegisterBlsKey, encodeRevokeAttestation, encodeRevokeOperator, encodeStake, encodeTransfer, encodeUnstake, generateKey, isKeyFile, signAction, submitBody, unlockKey, verifyKeyFile, verifySignedAction, wrapPkcs8, encodeAddress, toHex, toKeyFile, PKCS8_ED25519_PREFIX, assemblePolicySignature, decodePayload, encodePayload, fromHex, multisigAddress, multisigSignature, signingBytes, asBuffer, } from "./index.js";
+import { ArxiumRpc, RpcError, encodeApplyAttestor, encodeBlockAttestor, encodeExecuteProposal, encodeSubmitProposal, encodeVoteProposal, encodeAuthorizeOperator, encodeGrantAttestation, encodeIssueAsset, encodeRegisterAsset, encodeFreezeAsset, encodeSetHolderFrozen, encodeSetAssetLimits, encodeTransferAsset, encodeJoinValidator, encodeLeaveValidator, encodeRegisterBlsKey, encodeRevokeAttestation, encodeRevokeOperator, encodeStake, encodeTransfer, encodeUnstake, generateKey, isKeyFile, signAction, submitBody, unlockKey, verifyKeyFile, verifySignedAction, wrapPkcs8, encodeAddress, toHex, toKeyFile, PKCS8_ED25519_PREFIX, assemblePolicySignature, decodePayload, encodePayload, fromHex, multisigAddress, multisigSignature, signingBytes, asBuffer, ALL_ISSUER_CONTROLS, ISSUER_CONTROLS, bigintReplacer, encodeBurnAsset, encodeIssuerForcedTransfer, encodeRecoverHolder, encodeIssueAssetTo, encodeLockHolderAmount, encodeLockHolderAmountUntil, encodeLockIssuance, encodeTransferIssuer, encodeSetAssetMetadataUri, encodeSetPrivateClaims, encodeSnapshotHolders, encodeDistributeToHolders, encodeRedeemHolders, encodeSplitAsset, encodeCreateToken, encodeMintToken, encodeTransferToken, encodeBurnToken, encodeRenounceMint, encodeSettleDvp, signDvpConsent, } from "./index.js";
 class UsageError extends Error {
 }
-function output(value, json) { stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : typeof value === "string" ? `${value}\n` : `${JSON.stringify(value, null, 2)}\n`); }
+function output(value, json) { stdout.write(!json && typeof value === "string" ? `${value}\n` : `${JSON.stringify(value, bigintReplacer, 2)}\n`); }
 function parseGlobals(args) { let rpc = process.env.ARX_RPC ?? "http://127.0.0.1:8080", token = process.env.ARX_TOKEN, key = process.env.ARX_KEY, json = false, nonce; const rest = []; for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--rpc")
@@ -95,13 +95,80 @@ function payload(action, args) { const topics = (list) => list ? list.split(",")
     case "register-asset": {
         const [assetId, symbol, name, decimals] = args;
         if (!assetId || !symbol || !name || !/^\d+$/.test(decimals ?? ""))
-            throwUsage("register-asset needs <asset-id> <symbol> <name> <decimals> [topics] [jurisdictions]");
-        return encodeRegisterAsset(assetId, false, { asset_class: "other", decimals: Number(decimals), required_claims: topics(args[4]), allowed_jurisdictions: args[5] ? args[5].split(",") : null, max_supply: null, metadata_uri: null, symbol, name });
+            throwUsage("register-asset needs <asset-id> <symbol> <name> <decimals> [topics|-] [jurisdictions|-] [controls: all|none|freeze_asset,forced_transfer,...]");
+        return encodeRegisterAsset(assetId, false, { asset_class: "other", decimals: Number(decimals), required_claims: args[4] === "-" ? [] : topics(args[4]), allowed_jurisdictions: args[5] && args[5] !== "-" ? args[5].split(",") : null, max_supply: null, metadata_uri: null, symbol, name, controls: controlsArg(args[6]) });
     }
     case "issue-asset": return encodeIssueAsset(args[0] ?? throwUsage("issue-asset needs <asset-ref> <amount>"), amount(1));
     case "transfer-asset": return encodeTransferAsset(args[0] ?? throwUsage("transfer-asset needs <asset-ref> <to> <amount>"), args[1] ?? throwUsage("transfer-asset needs <asset-ref> <to> <amount>"), amount(2));
-    default: throwUsage(`unsupported action: ${action}`);
+    case "set-asset-limits": {
+        const asset = args[0] ?? throwUsage("set-asset-limits needs <asset-ref> <max-holders|-> [max-balance-per-holder|-] [max-attestation-age-blocks|-]");
+        const opt = (index) => { const value = args[index]; if (value === undefined || value === "-")
+            return null; if (!/^\d+$/.test(value))
+            throwUsage("limits must be integers, or - for no limit"); return BigInt(value); };
+        const holders = opt(1);
+        return encodeSetAssetLimits(asset, holders === null ? null : Number(holders), opt(2), opt(3));
+    }
+    case "freeze-asset":
+    case "unfreeze-asset": return encodeFreezeAsset(args[0] ?? throwUsage(`${action} needs <asset-ref> <reason>`), action === "freeze-asset", args[1] ?? throwUsage(`${action} needs <asset-ref> <reason>`));
+    case "freeze-holder":
+    case "unfreeze-holder": return encodeSetHolderFrozen(args[0] ?? throwUsage(`${action} needs <asset-ref> <holder>`), args[1] ?? throwUsage(`${action} needs <asset-ref> <holder>`), action === "freeze-holder");
+    default: return morePayload(action, args);
 } }
+/** Issuer, corporate and token actions. `<…>` arguments are required; amounts and heights are raw integers. */
+const USAGE = {
+    "burn-asset": "<asset-ref> <amount>", "forced-transfer": "<asset-ref> <from> <to> <amount> <reason>", "recover-holder": "<asset-ref> <lost> <replacement>",
+    "issue-asset-to": "<asset-ref> <to> <amount>", "lock-holder-amount": "<asset-ref> <holder> <amount> [until-height]", "unlock-holder-amount": "<asset-ref> <holder> <amount>",
+    "lock-issuance": "<asset-ref>", "transfer-issuer": "<asset-ref> <new-issuer>", "set-metadata-uri": "<asset-ref> <uri|->", "set-private-claims": "<asset-ref> on|off",
+    "snapshot-holders": "<asset-ref>", "distribute": "<asset-ref> <snapshot-height> <payout-asset-ref> <total>", "redeem-holders": "<asset-ref> <snapshot-height>",
+    "split-asset": "<asset-ref> <snapshot-height> <numerator> <denominator>",
+    "create-token": "<symbol> <name> <decimals> <initial-supply> <max-supply|-> mintable|fixed", "mint-token": "<token-ref> <to> <amount>",
+    "transfer-token": "<token-ref> <to> <amount>", "burn-token": "<token-ref> <amount>", "renounce-mint": "<token-ref>",
+    "settle-dvp": "<give-asset-ref|native> <give-amount> <counterparty> <take-asset-ref|native> <take-amount> <expires-at-height> <counterparty-signature>",
+};
+const spendArg = (value) => value === "native" ? "native" : { asset: value };
+function morePayload(action, args) {
+    const usage = USAGE[action] ?? throwUsage(`unsupported action: ${action}`);
+    const arg = (i) => args[i] ?? throwUsage(`${action} needs ${usage}`);
+    const int = (i) => { const value = arg(i); if (!/^\d+$/.test(value))
+        throwUsage(`${action} needs ${usage} (integers in base units)`); return BigInt(value); };
+    switch (action) {
+        case "burn-asset": return encodeBurnAsset(arg(0), int(1));
+        case "forced-transfer": return encodeIssuerForcedTransfer(arg(0), arg(1), arg(2), int(3), arg(4));
+        case "recover-holder": return encodeRecoverHolder(arg(0), arg(1), arg(2));
+        case "issue-asset-to": return encodeIssueAssetTo(arg(0), arg(1), int(2));
+        case "lock-holder-amount": return args[3] === undefined ? encodeLockHolderAmount(arg(0), arg(1), int(2), true) : encodeLockHolderAmountUntil(arg(0), arg(1), int(2), int(3));
+        case "unlock-holder-amount": return encodeLockHolderAmount(arg(0), arg(1), int(2), false);
+        case "lock-issuance": return encodeLockIssuance(arg(0));
+        case "transfer-issuer": return encodeTransferIssuer(arg(0), arg(1));
+        case "set-metadata-uri": return encodeSetAssetMetadataUri(arg(0), arg(1) === "-" ? null : arg(1));
+        case "set-private-claims": {
+            const on = arg(1);
+            if (on !== "on" && on !== "off")
+                throwUsage(`${action} needs ${usage}`);
+            return encodeSetPrivateClaims(arg(0), on === "on");
+        }
+        case "snapshot-holders": return encodeSnapshotHolders(arg(0));
+        case "distribute": return encodeDistributeToHolders(arg(0), int(1), arg(2), int(3));
+        case "redeem-holders": return encodeRedeemHolders(arg(0), int(1));
+        case "split-asset": return encodeSplitAsset(arg(0), int(1), int(2), int(3));
+        case "create-token": {
+            const kind = arg(5);
+            if (kind !== "mintable" && kind !== "fixed")
+                throwUsage(`${action} needs ${usage}`);
+            return encodeCreateToken(arg(0), arg(1), Number(int(2)), int(3), arg(4) === "-" ? null : int(4), kind === "mintable");
+        }
+        case "mint-token": return encodeMintToken(arg(0), arg(1), int(2));
+        case "transfer-token": return encodeTransferToken(arg(0), arg(1), int(2));
+        case "burn-token": return encodeBurnToken(arg(0), int(1));
+        case "settle-dvp": return encodeSettleDvp({ give: spendArg(arg(0)), giveAmount: int(1), counterparty: arg(2), take: spendArg(arg(3)), takeAmount: int(4), expiresAt: int(5) }, arg(6));
+        default: return encodeRenounceMint(arg(0));
+    }
+}
+/** Enabled issuer controls, fixed for the asset's life. Omitted or "all" keeps every power (the node's default). */
+function controlsArg(value) { if (!value || value === "all")
+    return ALL_ISSUER_CONTROLS; const on = value === "none" ? [] : value.split(","); for (const c of on)
+    if (!ISSUER_CONTROLS.includes(c))
+        throwUsage(`unknown control: ${c} (${ISSUER_CONTROLS.join(", ")})`); return Object.fromEntries(ISSUER_CONTROLS.map((c) => [c, on.includes(c)])); }
 function hexArg(value) { if (!value || !/^[0-9a-f]*$/i.test(value) || value.length % 2)
     throwUsage("expected even-length hex"); return Uint8Array.from(value.match(/../g)?.map((byte) => Number.parseInt(byte, 16)) ?? []); }
 async function main() {
@@ -113,7 +180,7 @@ async function main() {
         return;
     }
     if (!command)
-        throwUsage("use: arx keys|sign|submit|send|query|verify");
+        throwUsage("use: arx keys|sign|submit|send|dvp-consent|query|verify");
     if (command === "keys") {
         const [operation, ...keyArgs] = rest;
         if (operation === "new") {
@@ -220,6 +287,19 @@ async function main() {
         }
         throwUsage("use: arx multisig address|build|sign|combine|link");
     }
+    // The counterparty's half of a DvP: sign the order at its current nonce. The initiator sends it with `arx send settle-dvp`.
+    if (command === "dvp-consent") {
+        const use = "dvp-consent needs <initiator> <give-asset-ref|native> <give-amount> <take-asset-ref|native> <take-amount> <expires-at-height>", [initiator, give, giveAmount, take, takeAmount, expiresAt] = rest;
+        if (!initiator || !give || !take || ![giveAmount, takeAmount, expiresAt].every((v) => /^\d+$/.test(v ?? "")))
+            throwUsage(use);
+        const { file, privateKey } = await loadKey(globals.key);
+        const nonce = globals.nonce ?? await rpc.account(file.address).then((account) => account.nonce, (error) => { if (error instanceof RpcError && error.status === 404)
+            return 0; throw error; });
+        const order = { give: spendArg(give), giveAmount: BigInt(giveAmount), counterparty: file.address, take: spendArg(take), takeAmount: BigInt(takeAmount), expiresAt: BigInt(expiresAt) };
+        const signature = await signDvpConsent(privateKey, await rpc.genesisHash(), initiator, order, nonce);
+        output({ counterparty: file.address, counterpartyNonce: nonce, signature, send: ["settle-dvp", give, giveAmount, file.address, take, takeAmount, expiresAt, signature] }, true);
+        return;
+    }
     if (command === "sign" || command === "send") {
         const action = rest[0] ?? throwUsage(`${command} needs an action`), { file, privateKey } = await loadKey(globals.key), encoded = payload(action, rest.slice(1));
         if (command === "sign") {
@@ -255,7 +335,17 @@ async function main() {
     }
     if (command === "query") {
         const [operation, value] = rest;
-        const result = operation === "status" ? await rpc.status() : operation === "account" ? await rpc.account(value ?? throwUsage("account needs an address")) : operation === "block" ? (/^\d+$/.test(value ?? "") ? await rpc.block(Number(value)) : await rpc.blockByHash(value ?? throwUsage("block needs a height or hash"))) : operation === "action" ? await rpc.action(value ?? throwUsage("action needs a signature")) : operation === "validators" ? await rpc.validators() : operation === "finality" ? await rpc.finality() : operation === "search" ? await rpc.search(value ?? throwUsage("search needs a query")) : throwUsage("use: arx query status|account|block|action|validators|finality|search");
+        const result = operation === "status" ? await rpc.status() : operation === "account" ? await rpc.account(value ?? throwUsage("account needs an address")) : operation === "block" ? (/^\d+$/.test(value ?? "") ? await rpc.block(Number(value)) : await rpc.blockByHash(value ?? throwUsage("block needs a height or hash"))) : operation === "action" ? await rpc.action(value ?? throwUsage("action needs a signature")) : operation === "validators" ? await rpc.validators() : operation === "finality" ? await rpc.finality() : operation === "search" ? await rpc.search(value ?? throwUsage("search needs a query"))
+            : operation === "assets" ? (value ? await rpc.assets(value) : await rpc.listAssets())
+                : operation === "asset" ? await rpc.asset(value ?? throwUsage("asset needs an asset ref"))
+                    : operation === "holders" ? await rpc.assetHolders(value ?? throwUsage("holders needs an asset ref"))
+                        : operation === "balance" ? await rpc.assetBalance(value ?? throwUsage("balance needs <address> <asset-ref>"), rest[2] ?? throwUsage("balance needs <address> <asset-ref>"))
+                            : operation === "attestors" ? await rpc.attestors()
+                                : operation === "attestor" ? await rpc.attestor(value ?? throwUsage("attestor needs an address"))
+                                    : operation === "validator" ? await rpc.validator(value ?? throwUsage("validator needs an address"))
+                                        : operation === "stakes" ? await rpc.stakes(value ?? throwUsage("stakes needs an address"))
+                                            : operation === "fee" ? await rpc.actionFee()
+                                                : throwUsage("use: arx query status|account|block|action|validators|validator|finality|search|assets [address]|asset|holders|balance|attestors|attestor|stakes|fee");
         output(result, globals.json);
         return;
     }

package/dist/fees.d.ts

@@ -0,0 +1,26 @@
+/** `action_fee` and `weight_fee` from `GET /action-fee` (`rpc.feeParams()`). */
+export type FeeParams = {
+    actionFee: bigint;
+    weightFee: bigint;
+};
+/** `POLICY_AUTHORIZATION_WEIGHT`: added when a stateful account policy authorizes the action. */
+export declare const POLICY_AUTHORIZATION_WEIGHT = 5000;
+/** A single-key ed25519 signature: 64 bytes as hex. */
+export declare const SINGLE_SIGNATURE_LENGTH = 128;
+/** Hex length of a `threshold`-of-`members` multisig witness (`multisigSignature`), for estimating a fee before anyone signs. */
+export declare const multisigSignatureLength: (threshold: number, members: number) => number;
+/**
+ * Weight that the node charges for an action. Pass the real `signature` once it is signed. Before signing, pass
+ * `signatureLength` instead (128 for one key, longer for a multisig witness), and set `policy` when a stateful account policy will sign.
+ */
+export declare function actionWeight(sender: string, nonce: number | bigint, payload: Uint8Array, options?: {
+    signature?: string;
+    signatureLength?: number;
+    policy?: boolean;
+}): number;
+/** The fee the node charges, in IUM. `CreateToken` also pays `token_create_fee` on top (see `rpc.feeParams()`). */
+export declare function actionFee(params: FeeParams, sender: string, nonce: number | bigint, payload: Uint8Array, options?: {
+    signature?: string;
+    signatureLength?: number;
+    policy?: boolean;
+}): bigint;

package/dist/fees.js

@@ -0,0 +1,63 @@
+import { ACTION_VARIANT, TOKEN_ACTION, TOKEN_VARIANT } from "./actions.js";
+import { Reader } from "./bincode.js";
+import { ACCOUNT_POLICY_ACTION } from "./policy.js";
+/** `base_weight` in metering.rs, by `ActionPayload` discriminant. Token and account-policy actions are handled below. */
+const BASE_WEIGHT = {
+    [ACTION_VARIANT.transfer]: 50,
+    [ACTION_VARIANT.stake]: 100, [ACTION_VARIANT.unstake]: 100,
+    [ACTION_VARIANT.joinValidator]: 1_500, [ACTION_VARIANT.registerBlsKey]: 1_500,
+    [ACTION_VARIANT.leaveValidator]: 150,
+    [ACTION_VARIANT.authorizeOperator]: 100, [ACTION_VARIANT.revokeOperator]: 100,
+    7 /* VerifyIdentityCredential */: 5_000, [ACTION_VARIANT.verifyClaimProof]: 5_000,
+    [ACTION_VARIANT.grantAttestation]: 100, [ACTION_VARIANT.revokeAttestation]: 100,
+    [ACTION_VARIANT.applyAttestor]: 150, [ACTION_VARIANT.blockAttestor]: 150,
+    [ACTION_VARIANT.registerAsset]: 150,
+    [ACTION_VARIANT.issueAsset]: 150, [ACTION_VARIANT.issueAssetTo]: 150, [ACTION_VARIANT.transferAsset]: 150,
+    [ACTION_VARIANT.issuerForcedTransfer]: 150, [ACTION_VARIANT.burnAsset]: 150, [ACTION_VARIANT.recoverHolder]: 150,
+    [ACTION_VARIANT.freezeAsset]: 100, [ACTION_VARIANT.unfreezeAsset]: 100, [ACTION_VARIANT.setHolderFrozen]: 100,
+    [ACTION_VARIANT.lockHolderAmount]: 100, [ACTION_VARIANT.lockHolderAmountUntil]: 100, [ACTION_VARIANT.unlockHolderAmount]: 100,
+    [ACTION_VARIANT.setAssetLimits]: 100, [ACTION_VARIANT.setPrivateClaims]: 100, [ACTION_VARIANT.lockIssuance]: 100,
+    [ACTION_VARIANT.transferIssuer]: 100, [ACTION_VARIANT.setAssetMetadataUri]: 100,
+    [ACTION_VARIANT.snapshotHolders]: 2_000, [ACTION_VARIANT.distributeToHolders]: 15_000,
+    [ACTION_VARIANT.redeemHolders]: 10_000, [ACTION_VARIANT.splitAsset]: 10_000,
+    [ACTION_VARIANT.settleDvp]: 350,
+    [ACTION_VARIANT.submitProposal]: 150, [ACTION_VARIANT.voteProposal]: 150, [ACTION_VARIANT.executeProposal]: 150,
+    5 /* SubmitEquivocationEvidence */: 2_000,
+    15 /* SubmitExecutionFault */: 500_000,
+};
+/** `POLICY_AUTHORIZATION_WEIGHT`: added when a stateful account policy authorizes the action. */
+export const POLICY_AUTHORIZATION_WEIGHT = 5_000;
+/** A single-key ed25519 signature: 64 bytes as hex. */
+export const SINGLE_SIGNATURE_LENGTH = 128;
+/** Hex length of a `threshold`-of-`members` multisig witness (`multisigSignature`), for estimating a fee before anyone signs. */
+export const multisigSignatureLength = (threshold, members) => 2 * (2 + 32 * members + 65 * threshold);
+function baseWeight(payload) {
+    const r = new Reader(payload), variant = Number(r.varint());
+    if (variant === TOKEN_ACTION)
+        return Number(r.varint()) === TOKEN_VARIANT.createToken ? 150 : 100;
+    if (variant === ACCOUNT_POLICY_ACTION)
+        return 1_000;
+    const weight = BASE_WEIGHT[variant];
+    if (weight === undefined)
+        throw new Error(`unknown action variant: ${variant}`);
+    return weight;
+}
+/** bincode `standard()` varint length. */
+const varintLength = (n) => (n <= 250 ? 1 : n <= 0xffff ? 3 : n <= 0xffff_ffff ? 5 : 9);
+const isPolicyWitness = (signature) => signature.length > 128 && /^a7(00|01|02)/i.test(signature);
+/**
+ * Weight that the node charges for an action. Pass the real `signature` once it is signed. Before signing, pass
+ * `signatureLength` instead (128 for one key, longer for a multisig witness), and set `policy` when a stateful account policy will sign.
+ */
+export function actionWeight(sender, nonce, payload, options = {}) {
+    const sigLength = options.signature?.length ?? options.signatureLength ?? SINGLE_SIGNATURE_LENGTH;
+    const policy = options.signature !== undefined ? isPolicyWitness(options.signature) : !!options.policy;
+    const senderLength = new TextEncoder().encode(sender).length;
+    // `ActionWire`: sender string, nonce, `Some(signature)`, payload as a length-prefixed byte string.
+    const size = varintLength(senderLength) + senderLength + varintLength(Number(nonce)) + 1 + varintLength(sigLength) + sigLength + varintLength(payload.length) + payload.length;
+    return baseWeight(payload) + size + (policy ? POLICY_AUTHORIZATION_WEIGHT : 0);
+}
+/** The fee the node charges, in IUM. `CreateToken` also pays `token_create_fee` on top (see `rpc.feeParams()`). */
+export function actionFee(params, sender, nonce, payload, options = {}) {
+    return params.actionFee + BigInt(actionWeight(sender, nonce, payload, options)) * params.weightFee;
+}

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./bincode.js";
 export * from "./keys.js";
 export * from "./rpc.js";
 export * from "./policy.js";
+export * from "./fees.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./bincode.js";
 export * from "./keys.js";
 export * from "./rpc.js";
 export * from "./policy.js";
+export * from "./fees.js";

package/dist/policy.d.ts

@@ -1,4 +1,4 @@
-import { Reader } from "./bincode.js";
+import { Reader, Writer } from "./bincode.js";
 export declare const ACCOUNT_POLICY_ACTION = 40;
 export declare const POLICY_VARIANT: {
     readonly setAccountPolicy: 0;
@@ -39,7 +39,11 @@ export type AccountPolicy = {
     } | null;
 };
 export type PolicyMode = "owner" | "session" | "guardian";
+declare function asset(w: Writer, a: SpendAsset): void;
+export { asset as writeSpendAsset };
 export declare function encodeAccountPolicy(name: keyof typeof POLICY_VARIANT, input: Record<string, any>): Uint8Array;
+declare function readAsset(r: Reader): SpendAsset;
+export { readAsset as readSpendAsset };
 export declare function readAccountPolicy(r: Reader): {
     name: keyof typeof POLICY_VARIANT;
     input: Record<string, any>;

package/dist/policy.js

@@ -16,6 +16,7 @@ function asset(w, a) { if (a === "native")
     w.varint(0);
 else
     w.varint(1).string(a.asset); }
+export { asset as writeSpendAsset };
 function recipients(w, list) { if (list.length > 64 || list.some((a, i) => i > 0 && list[i - 1] >= a))
     throw new Error("recipients must be bounded, unique and sorted"); w.vec(list, (ww, a) => ww.string(a)); }
 function session(w, s) { w.raw(key(s.publicKey)).varint(bounded(s.expiresAt, 64)); asset(w, s.asset); w.varint(bounded(s.allowance, 128)); recipients(w, s.recipients); }
@@ -56,6 +57,7 @@ function readThreshold(r) { return { threshold: r.u8(), members: r.vec(readKey)
 function readAsset(r) { const tag = r.varint(); if (tag === 0n)
     return "native"; if (tag === 1n)
     return { asset: r.string() }; throw new Error("unknown spend asset"); }
+export { readAsset as readSpendAsset };
 function readSession(r) { return { publicKey: readKey(r), expiresAt: r.varint().toString(), asset: readAsset(r), allowance: r.varint().toString(), recipients: r.vec(rr => rr.string()) }; }
 export function readAccountPolicy(r) {
     const variant = Number(r.varint()), name = Object.keys(POLICY_VARIANT).find(n => POLICY_VARIANT[n] === variant);

package/dist/rpc.d.ts

@@ -1,4 +1,5 @@
-import { type SignedAction } from "./actions.js";
+import { type AssetClass, type IssuerControls, type SignedAction } from "./actions.js";
+import type { FeeParams } from "./fees.js";
 import { type AccountPolicy } from "./policy.js";
 export type RpcOptions = {
     rpc: string;
@@ -19,10 +20,15 @@ export type ActionStatus = {
 } | {
     status: "unknown";
 };
+/**
+ * `privateKey` signs as a single-key sender. For a multisig or programmable-account sender, pass `sign` instead: it gets the
+ * exact signing bytes and the nonce, and returns the action's `signature` field (e.g. from `multisigSignature`).
+ */
 export type SendActionOptions = {
-    privateKey: CryptoKey;
     sender: string;
     payload: Uint8Array;
+    privateKey?: CryptoKey;
+    sign?: (message: Uint8Array, nonce: number) => Promise<string>;
     pollIntervalMs?: number;
     timeoutMs?: number;
     finalized?: boolean;
@@ -31,34 +37,211 @@ export declare class RpcError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/** The chain refused the action. `reason` is the node's exact text, e.g. `compliance check failed: arx1… is not KYC'd/allowlisted`. */
+export declare class ActionDroppedError extends Error {
+    readonly reason: string;
+    readonly action: SignedAction;
+    constructor(reason: string, action: SignedAction);
+}
+export type ClaimTopicName = "Kyc" | "Aml" | "Accredited" | "Jurisdiction";
+export type NodeStatus = {
+    chain_name: string;
+    version: string;
+    genesis_hash: string;
+    tip_height: number;
+    tip_hash: string;
+    finalized_height: number | null;
+    final_watermark: number;
+    settled_height: number;
+    block_interval_secs: number | null;
+    storage_schema: number;
+    min_migratable_schema: number;
+    open_dispute_height: number | null;
+    open_dispute_header: string | null;
+    open_dispute_cause: string | null;
+};
+export type Account = {
+    balance: bigint;
+    nonce: number;
+    identity_hash: string | null;
+    zk_identity_verified: boolean;
+    attested_by: string | null;
+    claims: ClaimTopicName[];
+    jurisdiction: string | null;
+    attested_at: number | null;
+    programmable?: unknown;
+};
+export type StakeAllocation = {
+    master: string;
+    validator: string;
+    active_amount: bigint;
+    unbonding: {
+        amount: bigint;
+        unlock_at_height: number;
+    } | null;
+    created_at: number;
+    updated_at: number;
+};
+/** One asset in `rpc.assets(address)`. `transfer_eligible`/`eligibility_reason` describe the sending side. */
+export type AccountAssetBalance = {
+    ref: string;
+    asset_id: string;
+    symbol: string;
+    name: string;
+    issuer: string;
+    issuer_attested: boolean;
+    compliance_required: boolean;
+    frozen: boolean;
+    holder_frozen: boolean;
+    frozen_amount: bigint;
+    transfer_eligible: boolean;
+    eligibility_reason: string;
+    decimals: number;
+    balance: bigint;
+};
+export type Asset = {
+    ref: string;
+    asset_ref: string;
+    asset_id: string;
+    issuer: string;
+    issuer_attested: boolean;
+    holders: number;
+    compliance_required: boolean;
+    asset_class: string;
+    decimals: number;
+    required_claims: ClaimTopicName[];
+    allowed_jurisdictions: string[] | null;
+    max_supply: bigint | null;
+    total_supply: bigint;
+    frozen: boolean;
+    metadata_uri: string | null;
+    registered_at: number;
+    symbol: string;
+    name: string;
+    issuance_locked: boolean;
+    max_holders: number | null;
+    max_balance_per_holder: bigint | null;
+    max_attestation_age: number | null;
+    holder_count: number;
+    snapshot: {
+        height: number;
+        total: bigint;
+        holders: [string, number | bigint][];
+    } | null;
+    private_claims: boolean;
+    controls: IssuerControls;
+};
+export type AssetHolder = {
+    address: string;
+    balance: bigint;
+    frozen: boolean;
+    frozen_amount: bigint;
+    attested_at: number | null;
+};
+export type Attestor = {
+    attestor: string;
+    name: string;
+    registered_at: number;
+    owners: string[];
+    threshold: number;
+    blocked: boolean;
+    self_blocked: boolean;
+    removal_pending: boolean;
+};
+export type ValidatorStatus = "Active" | "Pending" | "Tombstoned" | {
+    Jailed: {
+        until_epoch: number;
+    };
+} | {
+    Leaving: {
+        from_epoch: number;
+    };
+};
+export type Validator = {
+    address: string;
+    status: ValidatorStatus;
+    voting_power: number;
+    bls_registered: boolean;
+    operator: string | null;
+};
+export type ActionFeeInfo = {
+    action_fee: bigint;
+    weight_fee: bigint;
+    max_block_weight: number;
+    token_create_fee: bigint;
+};
+export type { AssetClass };
+/**
+ * `JSON.parse` that never rounds an integer: the node writes u128 amounts as bare JSON numbers, and anything above 2^53
+ * (about 9M ARX in IUM) loses digits in a plain parse. Amount keys become `bigint`; other integers stay `number` unless unsafe.
+ */
+export declare function parseJson(text: string): unknown;
+/** `JSON.stringify` replacer for `bigint` values (as decimal strings). */
+export declare const bigintReplacer: (_key: string, value: unknown) => unknown;
 export declare class ArxiumRpc {
     readonly rpc: string;
     private readonly token?;
     private readonly requestFetch;
+    /** One in-flight `sendAction` per sender: the node's account nonce doesn't count the mempool, so two concurrent sends would sign the same nonce. */
+    private readonly senders;
     constructor(options: RpcOptions);
     private request;
     private genesis?;
     /** This chain's genesis hash, fetched once per client; every signature binds it. */
     genesisHash(): Promise<Uint8Array>;
-    status<T = Record<string, unknown>>(): Promise<T>;
-    account<T = Record<string, unknown>>(address: string): Promise<T>;
-    stake<T = Record<string, unknown>>(address: string): Promise<T>;
-    stakes<T = Record<string, unknown>[]>(address: string): Promise<T>;
+    status<T = NodeStatus>(): Promise<T>;
+    account<T = Account>(address: string): Promise<T>;
+    /** The account's asset balances, each with `transfer_eligible` and `eligibility_reason` for the sending side. Includes rows that went to zero. */
+    assets<T = AccountAssetBalance[]>(address: string): Promise<T>;
+    /** One asset balance. 404 (`RpcError`) when the asset was never registered; a registered asset held at zero is `balance: 0n`. */
+    assetBalance<T = AccountAssetBalance>(address: string, assetRef: string): Promise<T>;
+    stake<T = StakeAllocation>(address: string): Promise<T>;
+    stakes<T = StakeAllocation[]>(address: string): Promise<T>;
+    /** A stake `master` placed on `validator`'s behalf (`stake(address)` is the self-stake case). */
+    delegatedStake<T = StakeAllocation>(master: string, validator: string): Promise<T>;
     blsKey<T = Record<string, unknown>>(address: string): Promise<T>;
+    /** Every registered asset, or one issuer's. */
+    listAssets<T = Asset[]>(issuer?: string): Promise<T>;
+    asset<T = Asset>(assetRef: string): Promise<T>;
+    /** The asset `issuer` registered as `assetId`, or `null` when that id is still free for them. */
+    assetByAlias<T = Asset>(issuer: string, assetId: string): Promise<T | null>;
+    /** The cap table: every address with a non-zero balance, with its freeze state. */
+    assetHolders<T = AssetHolder[]>(assetRef: string): Promise<T>;
+    attestors<T = Attestor[]>(): Promise<T>;
+    attestor<T = Attestor>(address: string): Promise<T>;
     submit(action: SignedAction): Promise<unknown>;
     action(signature: string): Promise<ActionStatus>;
     blocks<T = unknown>(from: number, to: number): Promise<T>;
     block<T = unknown>(height: number): Promise<T>;
     blockByHash<T = unknown>(hash: string): Promise<T>;
-    validators<T = unknown>(): Promise<T>;
+    /** State changes a block made (balances, assets, stake), for indexers. */
+    blockEffects<T = unknown>(height: number): Promise<T>;
+    effects<T = unknown>(from: number, to: number): Promise<T>;
+    /** Sorted validator addresses, at the tip or at `height`. */
+    validators<T = string[]>(height?: number): Promise<T>;
+    validator<T = Validator>(address: string): Promise<T>;
+    /** Voting power by validator address, at the tip or at `height`. */
+    validatorPower<T = Record<string, number>>(height?: number): Promise<T>;
+    operatorValidators<T = string[]>(operator: string): Promise<T>;
     finality<T = unknown>(): Promise<T>;
+    /** Ids of stored equivocation/fault evidence; `evidence(id)` returns one. */
+    evidenceList<T = string[]>(): Promise<T>;
+    evidence<T = unknown>(id: string): Promise<T>;
+    /** Merkle proofs against a finalized state root, for light clients. */
+    accountProof<T = unknown>(address: string): Promise<T>;
+    assetBalanceProof<T = unknown>(address: string, assetRef: string): Promise<T>;
+    validatorProof<T = unknown>(address: string): Promise<T>;
     search<T = unknown>(query: string): Promise<T>;
     minStake<T = unknown>(): Promise<T>;
-    actionFee<T = unknown>(): Promise<T>;
+    actionFee<T = ActionFeeInfo>(): Promise<T>;
+    /** The chain's current fee parameters, for `actionFee(params, …)`. */
+    feeParams(): Promise<FeeParams>;
+    /** Signs at the sender's current nonce, submits and polls until confirmed (or finalized). Calls for one sender run one after another. */
     sendAction(options: SendActionOptions): Promise<{
         action: SignedAction;
         status: ActionStatus;
     }>;
+    private sendNow;
 }
 /** Stateful witnesses require the policy at the action's pre-state, not today's
  * policy. This checks cryptography; circuit execution proves limits and scope. */

package/dist/rpc.js

@@ -9,21 +9,73 @@ export class RpcError extends Error {
         this.status = status;
     }
 }
+/** The chain refused the action. `reason` is the node's exact text, e.g. `compliance check failed: arx1… is not KYC'd/allowlisted`. */
+export class ActionDroppedError extends Error {
+    reason;
+    action;
+    constructor(reason, action) {
+        super(`action dropped: ${reason}`);
+        this.reason = reason;
+        this.action = action;
+    }
+}
+/** Keys whose integer values are token amounts (u128 on the node): always `bigint`, so callers never see a rounded balance. */
+const AMOUNT_KEYS = new Set(["balance", "amount", "stake", "active_amount", "frozen_amount", "total_supply", "max_supply", "max_balance_per_holder", "total", "action_fee", "weight_fee", "token_create_fee", "min_stake"]);
+const MARK = "\u0000int:";
+/**
+ * `JSON.parse` that never rounds an integer: the node writes u128 amounts as bare JSON numbers, and anything above 2^53
+ * (about 9M ARX in IUM) loses digits in a plain parse. Amount keys become `bigint`; other integers stay `number` unless unsafe.
+ */
+export function parseJson(text) {
+    const marked = text.replace(/"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g, (token) => token[0] === '"' || /[.eE]/.test(token) ? token : `"\\u0000int:${token}"`);
+    return JSON.parse(marked, (key, value) => {
+        if (typeof value !== "string" || !value.startsWith(MARK))
+            return value;
+        const digits = value.slice(MARK.length), number = Number(digits);
+        return AMOUNT_KEYS.has(key) || !Number.isSafeInteger(number) ? BigInt(digits) : number;
+    });
+}
+/** `JSON.stringify` replacer for `bigint` values (as decimal strings). */
+export const bigintReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
 export class ArxiumRpc {
     rpc;
     token;
     requestFetch;
+    /** One in-flight `sendAction` per sender: the node's account nonce doesn't count the mempool, so two concurrent sends would sign the same nonce. */
+    senders = new Map();
     constructor(options) { this.rpc = options.rpc.replace(/\/+$/, ""); this.token = options.token; this.requestFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init)); } // browsers and Workers throw "Illegal invocation" if fetch is called with `this` = ArxiumRpc
     async request(path, init) { const response = await this.requestFetch(`${this.rpc}${path}`, { ...init, headers: { ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}), ...init?.headers } }); const text = await response.text(); if (!response.ok)
-        throw new RpcError(response.status, text || `${response.status} ${response.statusText}`); return text ? JSON.parse(text) : undefined; }
+        throw new RpcError(response.status, text || `${response.status} ${response.statusText}`); return text ? parseJson(text) : undefined; }
     genesis;
     /** This chain's genesis hash, fetched once per client; every signature binds it. */
     genesisHash() { return this.genesis ??= this.request("/genesis-hash").then((r) => fromHex(r.genesis_hash.replace(/^0x/, "")), (e) => { this.genesis = undefined; throw e; }); }
     status() { return this.request("/status"); }
     account(address) { return this.request(`/accounts/${encodeURIComponent(address)}`); }
+    /** The account's asset balances, each with `transfer_eligible` and `eligibility_reason` for the sending side. Includes rows that went to zero. */
+    assets(address) { return this.request(`/accounts/${encodeURIComponent(address)}/assets`); }
+    /** One asset balance. 404 (`RpcError`) when the asset was never registered; a registered asset held at zero is `balance: 0n`. */
+    assetBalance(address, assetRef) { return this.request(`/accounts/${encodeURIComponent(address)}/assets/${encodeURIComponent(assetRef)}`); }
     stake(address) { return this.request(`/accounts/${encodeURIComponent(address)}/stake`); }
     stakes(address) { return this.request(`/accounts/${encodeURIComponent(address)}/stakes`); }
+    /** A stake `master` placed on `validator`'s behalf (`stake(address)` is the self-stake case). */
+    delegatedStake(master, validator) { return this.request(`/stake/${encodeURIComponent(master)}/${encodeURIComponent(validator)}`); }
     blsKey(address) { return this.request(`/accounts/${encodeURIComponent(address)}/bls-key`); }
+    /** Every registered asset, or one issuer's. */
+    listAssets(issuer) { return this.request(issuer ? `/assets?issuer=${encodeURIComponent(issuer)}` : "/assets"); }
+    asset(assetRef) { return this.request(`/assets/${encodeURIComponent(assetRef)}`); }
+    /** The asset `issuer` registered as `assetId`, or `null` when that id is still free for them. */
+    async assetByAlias(issuer, assetId) { try {
+        return await this.request(`/assets/alias/${encodeURIComponent(issuer)}/${encodeURIComponent(assetId)}`);
+    }
+    catch (error) {
+        if (error instanceof RpcError && error.status === 404)
+            return null;
+        throw error;
+    } }
+    /** The cap table: every address with a non-zero balance, with its freeze state. */
+    assetHolders(assetRef) { return this.request(`/assets/${encodeURIComponent(assetRef)}/holders`); }
+    attestors() { return this.request("/attestors"); }
+    attestor(address) { return this.request(`/attestors/${encodeURIComponent(address)}`); }
     submit(action) { return this.request("/actions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(action) }); }
     async action(signature) { try {
         return await this.request(`/actions/${encodeURIComponent(signature)}`);
@@ -36,25 +88,63 @@ export class ArxiumRpc {
     blocks(from, to) { return this.request(`/blocks?from=${from}&to=${to}`); }
     block(height) { return this.request(`/blocks/${height}`); }
     blockByHash(hash) { return this.request(`/blocks/by-hash/${encodeURIComponent(hash)}`); }
-    validators() { return this.request("/validators"); }
+    /** State changes a block made (balances, assets, stake), for indexers. */
+    blockEffects(height) { return this.request(`/blocks/${height}/effects`); }
+    effects(from, to) { return this.request(`/effects?from=${from}&to=${to}`); }
+    /** Sorted validator addresses, at the tip or at `height`. */
+    validators(height) { return this.request(height === undefined ? "/validators" : `/validators?height=${height}`); }
+    validator(address) { return this.request(`/validators/${encodeURIComponent(address)}`); }
+    /** Voting power by validator address, at the tip or at `height`. */
+    validatorPower(height) { return this.request(height === undefined ? "/validators/power" : `/validators/power?height=${height}`); }
+    operatorValidators(operator) { return this.request(`/operators/${encodeURIComponent(operator)}/validators`); }
     finality() { return this.request("/finality"); }
+    /** Ids of stored equivocation/fault evidence; `evidence(id)` returns one. */
+    evidenceList() { return this.request("/evidence"); }
+    evidence(id) { return this.request(`/evidence/${encodeURIComponent(id)}`); }
+    /** Merkle proofs against a finalized state root, for light clients. */
+    accountProof(address) { return this.request(`/accounts/${encodeURIComponent(address)}/proof`); }
+    assetBalanceProof(address, assetRef) { return this.request(`/accounts/${encodeURIComponent(address)}/assets/${encodeURIComponent(assetRef)}/proof`); }
+    validatorProof(address) { return this.request(`/validators/${encodeURIComponent(address)}/proof`); }
     search(query) { return this.request(`/search?q=${encodeURIComponent(query)}`); }
     minStake() { return this.request("/min-stake"); }
     actionFee() { return this.request("/action-fee"); }
-    async sendAction(options) { const account = await this.account(options.sender).catch((error) => { if (error instanceof RpcError && error.status === 404)
-        return { nonce: 0 }; throw error; }); const signature = await signAction(options.privateKey, await this.genesisHash(), options.sender, account.nonce, options.payload); const action = submitBody(options.sender, account.nonce, signature, options.payload); await this.submit(action); const deadline = Date.now() + (options.timeoutMs ?? 120_000); while (Date.now() < deadline) {
-        const status = await this.action(signature);
-        if (status.status === "dropped")
-            throw new Error(`action dropped: ${status.reason}`);
-        if (status.status === "confirmed") {
-            if (!options.finalized)
-                return { action, status };
-            const block = await this.block(status.height);
-            if (block.finalized)
-                return { action, status };
+    /** The chain's current fee parameters, for `actionFee(params, …)`. */
+    async feeParams() { const fee = await this.actionFee(); return { actionFee: BigInt(fee.action_fee), weightFee: BigInt(fee.weight_fee) }; }
+    /** Signs at the sender's current nonce, submits and polls until confirmed (or finalized). Calls for one sender run one after another. */
+    sendAction(options) {
+        const previous = this.senders.get(options.sender) ?? Promise.resolve();
+        const run = previous.catch(() => undefined).then(() => this.sendNow(options));
+        const tail = run.catch(() => undefined);
+        this.senders.set(options.sender, tail);
+        void tail.then(() => { if (this.senders.get(options.sender) === tail)
+            this.senders.delete(options.sender); });
+        return run;
+    }
+    async sendNow(options) {
+        if (!options.privateKey === !options.sign)
+            throw new Error("sendAction needs exactly one of privateKey or sign");
+        const account = await this.account(options.sender).catch((error) => { if (error instanceof RpcError && error.status === 404)
+            return { nonce: 0 }; throw error; });
+        const genesis = await this.genesisHash(), nonce = account.nonce;
+        const signature = options.sign ? await options.sign(signingBytes(genesis, options.sender, nonce, options.payload), nonce) : await signAction(options.privateKey, genesis, options.sender, nonce, options.payload);
+        const action = submitBody(options.sender, nonce, signature, options.payload);
+        await this.submit(action);
+        const deadline = Date.now() + (options.timeoutMs ?? 120_000);
+        while (Date.now() < deadline) {
+            const status = await this.action(signature);
+            if (status.status === "dropped")
+                throw new ActionDroppedError(status.reason, action);
+            if (status.status === "confirmed") {
+                if (!options.finalized)
+                    return { action, status };
+                const block = await this.block(status.height);
+                if (block.finalized)
+                    return { action, status };
+            }
+            await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 1_000));
         }
-        await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 1_000));
-    } throw new Error("timed out waiting for action"); }
+        throw new Error("timed out waiting for action");
+    }
 }
 /** Stateful witnesses require the policy at the action's pre-state, not today's
  * policy. This checks cryptography; circuit execution proves limits and scope. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arxiumlabs/sdk",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "description": "Arxium TypeScript SDK and arx CLI",
   "type": "module",
   "private": false,