@arxiumlabs/sdk 0.4.0 → 0.8.0

package/README.md

@@ -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,10 @@ 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.
 
+### 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:
@@ -100,26 +125,57 @@ 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).
+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`, 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 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`,
+`npm run test:release`, `npm test`, then `npm run check:package` locally.
+The package check installs the tarball in a temporary directory, imports its
+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
+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

@@ -23,7 +23,15 @@ export declare const ACTION_VARIANT: {
     readonly issuerForcedTransfer: 22;
     readonly recoverHolder: 23;
     readonly issueAssetTo: 24;
+    readonly lockIssuance: 25;
+    readonly transferIssuer: 26;
+    readonly setAssetMetadataUri: 27;
     readonly setAssetLimits: 28;
+    readonly lockHolderAmountUntil: 29;
+    readonly snapshotHolders: 33;
+    readonly distributeToHolders: 34;
+    readonly redeemHolders: 35;
+    readonly splitAsset: 36;
     readonly verifyClaimProof: 37;
     readonly setPrivateClaims: 38;
     readonly submitProposal: 30;
@@ -58,6 +66,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;
@@ -67,7 +82,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;
@@ -89,6 +106,22 @@ export declare function encodeLockHolderAmount(asset: string, holder: string, am
 export declare function encodeIssuerForcedTransfer(asset: string, from: string, to: string, amount: bigint, reason: string): Uint8Array;
 export declare function encodeRecoverHolder(asset: string, lost: string, replacement: string): Uint8Array;
 export declare function encodeIssueAssetTo(asset: string, to: string, amount: bigint): Uint8Array;
+/** One-way: the issuer gives up minting and `max_supply` is pinned to the current supply. */
+export declare function encodeLockIssuance(asset: string): Uint8Array;
+/** Hands every issuer right over `asset` to `newIssuer` (key rotation, compromise remedy). */
+export declare function encodeTransferIssuer(asset: string, newIssuer: string): Uint8Array;
+/** `null` clears the link. */
+export declare function encodeSetAssetMetadataUri(asset: string, metadataUri: string | null): Uint8Array;
+/** A holding period: the lock releases itself at `untilHeight`. */
+export declare function encodeLockHolderAmountUntil(asset: string, holder: string, amount: bigint, untilHeight: bigint): Uint8Array;
+/** Records the record-date cap table; the corporate actions below name it by its block height. */
+export declare function encodeSnapshotHolders(asset: string): Uint8Array;
+/** Dividend/coupon: pays `total` of `payoutAsset` pro rata to the snapshot at `snapshotHeight`. */
+export declare function encodeDistributeToHolders(asset: string, snapshotHeight: bigint, payoutAsset: string, total: bigint): Uint8Array;
+/** Forces every snapshot balance back to the issuer. Send the proceeds with `encodeDistributeToHolders` first. */
+export declare function encodeRedeemHolders(asset: string, snapshotHeight: bigint): Uint8Array;
+/** Each snapshot holding `b` becomes `b * numerator / denominator` (split if >1, consolidation if <1). */
+export declare function encodeSplitAsset(asset: string, snapshotHeight: bigint, numerator: bigint, denominator: bigint): Uint8Array;
 /** Sets issuer-controlled investor, concentration, and attestation-age limits. `null` clears each limit. */
 /** zk-KYC: a holder's private eligibility proof. `sub` is a fixed 32-byte array on the node, so it rides raw (no length prefix); `proof` is length-prefixed. */
 export declare function encodeVerifyClaimProof(asset: string, sub: Uint8Array, todayDays: number, proof: Uint8Array): Uint8Array;

package/dist/actions.js

@@ -8,7 +8,9 @@ export const ACTION_VARIANT = {
     registerAsset: 12, issueAsset: 13, transferAsset: 14, freezeAsset: 16, unfreezeAsset: 17,
     burnAsset: 18, setHolderFrozen: 19, lockHolderAmount: 20, unlockHolderAmount: 21,
     issuerForcedTransfer: 22, recoverHolder: 23, issueAssetTo: 24,
-    setAssetLimits: 28, verifyClaimProof: 37, setPrivateClaims: 38,
+    lockIssuance: 25, transferIssuer: 26, setAssetMetadataUri: 27, setAssetLimits: 28, lockHolderAmountUntil: 29,
+    snapshotHolders: 33, distributeToHolders: 34, redeemHolders: 35, splitAsset: 36,
+    verifyClaimProof: 37, setPrivateClaims: 38,
     submitProposal: 30, voteProposal: 31, executeProposal: 32,
     applyAttestor: 41, blockAttestor: 42,
 };
@@ -17,6 +19,11 @@ 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(); }
@@ -28,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(); }
@@ -38,6 +46,22 @@ export function encodeLockHolderAmount(asset, holder, amount, lock) { return new
 export function encodeIssuerForcedTransfer(asset, from, to, amount, reason) { return new Writer().varint(ACTION_VARIANT.issuerForcedTransfer).string(asset).string(from).string(to).varint(amount).string(reason).bytes(); }
 export function encodeRecoverHolder(asset, lost, replacement) { return new Writer().varint(ACTION_VARIANT.recoverHolder).string(asset).string(lost).string(replacement).bytes(); }
 export function encodeIssueAssetTo(asset, to, amount) { return new Writer().varint(ACTION_VARIANT.issueAssetTo).string(asset).string(to).varint(amount).bytes(); }
+/** One-way: the issuer gives up minting and `max_supply` is pinned to the current supply. */
+export function encodeLockIssuance(asset) { return new Writer().varint(ACTION_VARIANT.lockIssuance).string(asset).bytes(); }
+/** Hands every issuer right over `asset` to `newIssuer` (key rotation, compromise remedy). */
+export function encodeTransferIssuer(asset, newIssuer) { return new Writer().varint(ACTION_VARIANT.transferIssuer).string(asset).string(newIssuer).bytes(); }
+/** `null` clears the link. */
+export function encodeSetAssetMetadataUri(asset, metadataUri) { return new Writer().varint(ACTION_VARIANT.setAssetMetadataUri).string(asset).option(metadataUri, (w, uri) => w.string(uri)).bytes(); }
+/** A holding period: the lock releases itself at `untilHeight`. */
+export function encodeLockHolderAmountUntil(asset, holder, amount, untilHeight) { return new Writer().varint(ACTION_VARIANT.lockHolderAmountUntil).string(asset).string(holder).varint(amount).varint(untilHeight).bytes(); }
+/** Records the record-date cap table; the corporate actions below name it by its block height. */
+export function encodeSnapshotHolders(asset) { return new Writer().varint(ACTION_VARIANT.snapshotHolders).string(asset).bytes(); }
+/** Dividend/coupon: pays `total` of `payoutAsset` pro rata to the snapshot at `snapshotHeight`. */
+export function encodeDistributeToHolders(asset, snapshotHeight, payoutAsset, total) { return new Writer().varint(ACTION_VARIANT.distributeToHolders).string(asset).varint(snapshotHeight).string(payoutAsset).varint(total).bytes(); }
+/** Forces every snapshot balance back to the issuer. Send the proceeds with `encodeDistributeToHolders` first. */
+export function encodeRedeemHolders(asset, snapshotHeight) { return new Writer().varint(ACTION_VARIANT.redeemHolders).string(asset).varint(snapshotHeight).bytes(); }
+/** Each snapshot holding `b` becomes `b * numerator / denominator` (split if >1, consolidation if <1). */
+export function encodeSplitAsset(asset, snapshotHeight, numerator, denominator) { return new Writer().varint(ACTION_VARIANT.splitAsset).string(asset).varint(snapshotHeight).varint(numerator).varint(denominator).bytes(); }
 /** Sets issuer-controlled investor, concentration, and attestation-age limits. `null` clears each limit. */
 /** zk-KYC: a holder's private eligibility proof. `sub` is a fixed 32-byte array on the node, so it rides raw (no length prefix); `proof` is length-prefixed. */
 export function encodeVerifyClaimProof(asset, sub, todayDays, proof) { if (sub.length !== 32)
@@ -96,6 +120,14 @@ export function encodePayload({ name, input }) {
         case "issuerForcedTransfer": return encodeIssuerForcedTransfer(input.asset, input.from, input.to, BigInt(input.amount), input.reason);
         case "recoverHolder": return encodeRecoverHolder(input.asset, input.lost, input.replacement);
         case "issueAssetTo": return encodeIssueAssetTo(input.asset, input.to, BigInt(input.amount));
+        case "lockIssuance": return encodeLockIssuance(input.asset);
+        case "transferIssuer": return encodeTransferIssuer(input.asset, input.newIssuer);
+        case "setAssetMetadataUri": return encodeSetAssetMetadataUri(input.asset, input.metadataUri);
+        case "lockHolderAmountUntil": return encodeLockHolderAmountUntil(input.asset, input.holder, BigInt(input.amount), BigInt(input.untilHeight));
+        case "snapshotHolders": return encodeSnapshotHolders(input.asset);
+        case "distributeToHolders": return encodeDistributeToHolders(input.asset, BigInt(input.snapshotHeight), input.payoutAsset, BigInt(input.total));
+        case "redeemHolders": return encodeRedeemHolders(input.asset, BigInt(input.snapshotHeight));
+        case "splitAsset": return encodeSplitAsset(input.asset, BigInt(input.snapshotHeight), BigInt(input.numerator), BigInt(input.denominator));
         case "setAssetLimits": return encodeSetAssetLimits(input.asset, input.maxHolders, nullableBig(input.maxBalancePerHolder), nullableBig(input.maxAttestationAge));
         case "verifyClaimProof": return encodeVerifyClaimProof(input.asset, Uint8Array.from(input.sub), input.todayDays, Uint8Array.from(input.proof));
         case "setPrivateClaims": return encodeSetPrivateClaims(input.asset, input.enabled);
@@ -142,7 +174,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() }),
@@ -154,6 +186,14 @@ export function decodePayload(payload) {
         issuerForcedTransfer: () => ({ asset: str(), from: str(), to: str(), amount: amount(), reason: str() }),
         recoverHolder: () => ({ asset: str(), lost: str(), replacement: str() }),
         issueAssetTo: () => ({ asset: str(), to: str(), amount: amount() }),
+        lockIssuance: () => ({ asset: str() }),
+        transferIssuer: () => ({ asset: str(), newIssuer: str() }),
+        setAssetMetadataUri: () => ({ asset: str(), metadataUri: r.option(str) }),
+        lockHolderAmountUntil: () => ({ asset: str(), holder: str(), amount: amount(), untilHeight: amount() }),
+        snapshotHolders: () => ({ asset: str() }),
+        distributeToHolders: () => ({ asset: str(), snapshotHeight: amount(), payoutAsset: str(), total: amount() }),
+        redeemHolders: () => ({ asset: str(), snapshotHeight: amount() }),
+        splitAsset: () => ({ asset: str(), snapshotHeight: amount(), numerator: amount(), denominator: amount() }),
         setAssetLimits: () => ({ asset: str(), maxHolders: r.option((rr) => Number(rr.varint())), maxBalancePerHolder: r.option(amount), maxAttestationAge: r.option(amount) }),
         verifyClaimProof: () => ({ asset: str(), sub: Array.from({ length: 32 }, () => r.u8()), todayDays: Number(r.varint()), proof: bytes() }),
         setPrivateClaims: () => ({ asset: str(), enabled: r.bool() }),

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, } 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,77 @@ 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>",
+};
+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));
+        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() {
@@ -255,7 +319,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,62 @@
+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.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/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.4.0",
+  "version": "0.8.0",
   "description": "Arxium TypeScript SDK and arx CLI",
   "type": "module",
   "private": false,
@@ -32,6 +32,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "check:package": "node scripts/release-check.mjs",
+    "test:release": "node --test scripts/release-check.test.mjs",
     "test": "npm run build && node dist/codec.test.js && node dist/policy.test.js && node dist/cli.test.js"
   },
   "devDependencies": {