@arxiumlabs/sdk 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @arxiumlabs/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK and `arx` CLI for the Arxium network. It has zero runtime dependencies and requires Node 20 or later. The SDK uses WebCrypto Ed25519 and also runs in browsers and Workers.
+
+Builder docs (endpoints, API keys, faucet, quickstart, RWA walkthrough): https://arxium.network/docs
+
+## Install
+
+```sh
+npm install @arxiumlabs/sdk      # library
+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.
+
+```sh
+cd Arxium && cargo test -p arxd-runtime writes_typescript_signed_action_fixtures && git diff --exit-code sdk/ts/fixtures
+cd sdk/ts && npm test
+```
+
+## SDK quickstart
+
+```ts
+import { ArxiumRpc, encodeTransfer, arxToIum } from "@arxiumlabs/sdk";
+
+const rpc = new ArxiumRpc({ rpc: "https://node.example", token: process.env.ARX_TOKEN });
+const payload = encodeTransfer("arx1...", arxToIum("1.5"));
+```
+
+All token amounts are `bigint`: `1 ARX = 1_000_000_000 IUM`.
+
+### Chain binding
+
+Every action signature covers the chain's 32-byte genesis hash (`GET /genesis-hash`, `rpc.genesisHash()`) ahead of sender, nonce and payload, so an action signed for one chain is rejected on any other (devnet vs. mainnet, or after a reset). `signingBytes`, `signAction` and `verifySignedAction` take it as an argument; `rpc.sendAction` fetches it for you.
+
+### Multisig senders
+
+An M-of-N address (up to 16 members) is derived from its policy. Each member signs the action exactly as a single-key sender would. You then combine exactly `threshold` of those signatures:
+
+```ts
+const sender = await multisigAddress(2, [pkA, pkB, pkC]);          // member order doesn't matter
+const genesis = await rpc.genesisHash();                           // every signature binds the chain's genesis hash
+const sigA = await signAction(keyA, genesis, sender, nonce, payload); // on A's machine
+const sigC = await signAction(keyC, genesis, sender, nonce, payload); // on C's machine
+const signature = multisigSignature(2, [pkA, pkB, pkC], [[pkA, sigA], [pkC, sigC]]);
+await rpc.submit(submitBody(sender, nonce, signature, payload));
+```
+
+A co-signer should see what they're signing before they sign it. `decodePayload(bytes)` returns `{ name, input }` for every action the SDK can encode. It re-encodes the result and throws unless the bytes match exactly.
+
+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.
+
+## Key files
+
+`arx` reads and writes Console's encrypted export JSON unchanged:
+
+```json
+{
+  "address": "arx1...",
+  "publicKey": "...",
+  "version": 1,
+  "kdf": "PBKDF2-SHA256",
+  "iterations": 600000,
+  "salt": "...",
+  "iv": "...",
+  "ciphertext": "...",
+  "network": "arx-devnet"
+}
+```
+
+`network` is a display label. It is not a signing domain. The CLI verifies that a decrypted private key matches `address` and `publicKey`.
+
+Set `ARX_PASSPHRASE` for non-interactive use. Otherwise `arx` prompts on a terminal. A non-terminal invocation without it exits with status 2.
+
+## CLI
+
+Global configuration: `--rpc`, `--token`, `--key`, and `--json` have `ARX_RPC`, `ARX_TOKEN`, and `ARX_KEY` environment equivalents.
+
+```sh
+arx keys new
+arx keys import --file arxium-devnet-key-abc.json
+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 submit signed-action.json
+arx send transfer arx1recipient 1500000000 --key key.json
+
+arx query status
+arx query account arx1address
+arx query block 42
+arx query block 0xblockhash
+arx query action signature
+arx query validators
+arx query finality
+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).
+
+```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 issue-asset arxasset1... 1000
+arx send transfer-asset arxasset1... arx1recipient 100
+```
+
+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.

package/dist/actions.d.ts

@@ -0,0 +1,161 @@
+import { POLICY_VARIANT } from "./policy.js";
+/** These indices are ActionPayload's positional bincode discriminants. Never derive them. */
+export declare const ACTION_VARIANT: {
+    readonly transfer: 0;
+    readonly joinValidator: 1;
+    readonly leaveValidator: 2;
+    readonly stake: 3;
+    readonly unstake: 4;
+    readonly registerBlsKey: 6;
+    readonly authorizeOperator: 8;
+    readonly revokeOperator: 9;
+    readonly grantAttestation: 10;
+    readonly revokeAttestation: 11;
+    readonly registerAsset: 12;
+    readonly issueAsset: 13;
+    readonly transferAsset: 14;
+    readonly freezeAsset: 16;
+    readonly unfreezeAsset: 17;
+    readonly burnAsset: 18;
+    readonly setHolderFrozen: 19;
+    readonly lockHolderAmount: 20;
+    readonly unlockHolderAmount: 21;
+    readonly issuerForcedTransfer: 22;
+    readonly recoverHolder: 23;
+    readonly issueAssetTo: 24;
+    readonly setAssetLimits: 28;
+    readonly verifyClaimProof: 37;
+    readonly setPrivateClaims: 38;
+    readonly submitProposal: 30;
+    readonly voteProposal: 31;
+    readonly executeProposal: 32;
+    readonly applyAttestor: 41;
+    readonly blockAttestor: 42;
+};
+/** `ActionPayload::Token(TokenAction)` is variant 39; these are `TokenAction`'s own discriminants, written after it. */
+export declare const TOKEN_ACTION = 39;
+export declare const TOKEN_VARIANT: {
+    readonly createToken: 0;
+    readonly mintToken: 1;
+    readonly transferToken: 2;
+    readonly burnToken: 3;
+    readonly renounceMint: 4;
+};
+declare const CLASS: {
+    readonly other: 0;
+    readonly real_estate: 1;
+    readonly equity: 2;
+    readonly bond: 3;
+    readonly stablecoin: 4;
+    readonly commodity: 5;
+    readonly token: 6;
+};
+declare const TOPIC: {
+    readonly kyc: 0;
+    readonly aml: 1;
+    readonly accredited: 2;
+    readonly jurisdiction: 3;
+};
+export type AssetClass = keyof typeof CLASS;
+export type ClaimTopic = keyof typeof TOPIC;
+export type AssetMetadata = {
+    asset_class: AssetClass;
+    decimals: number;
+    required_claims: ClaimTopic[];
+    allowed_jurisdictions: string[] | null;
+    max_supply: string | bigint | null;
+    metadata_uri: string | null;
+    symbol: string;
+    name: string;
+};
+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;
+export declare function encodeLeaveValidator(validator: string): Uint8Array;
+export declare function encodeStake(validator: string, amount: bigint): Uint8Array;
+export declare function encodeUnstake(validator: string, amount: bigint): Uint8Array;
+export declare function encodeRegisterBlsKey(validator: string, pubkey: Uint8Array, pop: Uint8Array): Uint8Array;
+export declare function encodeAuthorizeOperator(operator: string): Uint8Array;
+export declare function encodeRevokeOperator(): Uint8Array;
+export declare function encodeGrantAttestation(subject: string, hash: string, topics: ClaimTopic[], jurisdiction: string | null): Uint8Array;
+export declare function encodeRevokeAttestation(subject: string): Uint8Array;
+export declare function encodeRegisterAsset(assetId: string, complianceRequired: boolean, metadata: AssetMetadata): Uint8Array;
+export declare function encodeIssueAsset(asset: string, amount: bigint): Uint8Array;
+export declare function encodeTransferAsset(asset: string, to: string, amount: bigint): Uint8Array;
+export declare function encodeFreezeAsset(asset: string, frozen: boolean, reason: string): Uint8Array;
+export declare function encodeBurnAsset(asset: string, amount: bigint): Uint8Array;
+export declare function encodeSetHolderFrozen(asset: string, holder: string, frozen: boolean): Uint8Array;
+export declare function encodeLockHolderAmount(asset: string, holder: string, amount: bigint, lock: boolean): Uint8Array;
+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;
+/** 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;
+/** Issuer opt-in: whether holders may clear `asset`'s gate with a claim proof instead of clear-text claims. */
+export declare function encodeSetPrivateClaims(asset: string, enabled: boolean): Uint8Array;
+/** Permissionless token (`circuits/token`); its ref is `deriveAssetRef(sender, symbol.toLowerCase())`. `mintable: false` fixes supply at creation. Costs `token_create_fee` on top of the action fee. */
+export declare function encodeCreateToken(symbol: string, name: string, decimals: number, initialSupply: bigint, maxSupply: bigint | null, mintable: boolean): Uint8Array;
+export declare function encodeMintToken(tokenRef: string, to: string, amount: bigint): Uint8Array;
+export declare function encodeTransferToken(tokenRef: string, to: string, amount: bigint): Uint8Array;
+export declare function encodeBurnToken(tokenRef: string, amount: bigint): Uint8Array;
+export declare function encodeRenounceMint(tokenRef: string): Uint8Array;
+/** Applies to become an attestor. The sender is the attestor: its address must be the `threshold`-of-`owners` multisig (threshold >= 2). Pays the application bond and opens a validator vote. */
+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;
+/** `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;
+    readonly removeAttestor: 5;
+    readonly unblockAttestor: 6;
+};
+export type GovernanceProposal = {
+    kind: "addAttestor";
+    attestor: string;
+    name: string;
+    owners: string[];
+    threshold: number;
+    evidenceHash: string;
+    evidenceUri: string;
+} | {
+    kind: "removeAttestor" | "unblockAttestor";
+    attestor: string;
+};
+/** 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. */
+export declare function encodeSubmitProposal(proposal: GovernanceProposal, description: string): Uint8Array;
+/** Stake-weighted vote. One per validator per proposal. */
+export declare function encodeVoteProposal(proposal: number | bigint, approve: boolean): Uint8Array;
+/** Anyone may close a proposal once its window has ended; this applies it if it passed and always lifts a removal block. */
+export declare function encodeExecuteProposal(proposal: number | bigint): Uint8Array;
+export declare function encodeSetAssetLimits(asset: string, maxHolders: number | null, maxBalancePerHolder?: bigint | null, maxAttestationAge?: bigint | null): Uint8Array;
+/** `{ name, input }` names and shapes match `fixtures/signed-actions.json`: amounts are decimal strings, byte fields are number arrays. */
+export type ActionName = keyof typeof ACTION_VARIANT | keyof typeof TOKEN_VARIANT | keyof typeof POLICY_VARIANT;
+export type DecodedPayload = {
+    name: ActionName;
+    input: Record<string, any>;
+};
+export declare function encodePayload({ name, input }: DecodedPayload): Uint8Array;
+/**
+ * Decodes a payload the SDK can encode, then re-encodes it and throws unless the bytes match, so what
+ * a co-signer is shown is exactly what they sign. Unknown variants throw rather than display partially.
+ */
+export declare function decodePayload(payload: Uint8Array): DecodedPayload;
+/** Mirrors `Action::signing_bytes`: the chain's 32-byte genesis hash (`GET /genesis-hash`) binds the signature to one chain, so an action signed for chain A is rejected on chain B. */
+export declare function signingBytes(genesis: Uint8Array, sender: string, nonce: number | bigint, payload: Uint8Array): Uint8Array;
+export declare function signAction(privateKey: CryptoKey, genesis: Uint8Array, sender: string, nonce: number, payload: Uint8Array): Promise<string>;
+export type SignedAction = {
+    sender: string;
+    nonce: number;
+    signature: string;
+    payload: number[];
+};
+export declare function submitBody(sender: string, nonce: number, signature: string, payload: Uint8Array): SignedAction;
+/** M-of-N sender, mirrors `xc_primitives::multisig_address`. Every member signs with plain `signAction(key, genesis, multisigAddress, nonce, payload)`; `multisigSignature` combines exactly `threshold` of them into the action's `signature` field. */
+export declare const MAX_MULTISIG_MEMBERS = 16;
+export declare function multisigAddress(threshold: number, members: Uint8Array[]): Promise<string>;
+/** `signatures`: [member public key, that member's hex signature]. */
+export declare function multisigSignature(threshold: number, members: Uint8Array[], signatures: [Uint8Array, string][]): string;
+/** Same checks as `Action::verify_signature` for a multisig sender. */
+export declare function verifyMultisig(sender: string, signature: string, message: Uint8Array): Promise<boolean>;
+export {};

package/dist/actions.js

@@ -0,0 +1,207 @@
+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";
+/** 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,
+    authorizeOperator: 8, revokeOperator: 9, grantAttestation: 10, revokeAttestation: 11,
+    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,
+    submitProposal: 30, voteProposal: 31, executeProposal: 32,
+    applyAttestor: 41, blockAttestor: 42,
+};
+/** `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 };
+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(); }
+export function encodeLeaveValidator(validator) { return new Writer().varint(ACTION_VARIANT.leaveValidator).string(validator).bytes(); }
+export function encodeStake(validator, amount) { return new Writer().varint(ACTION_VARIANT.stake).string(validator).varint(amount).bytes(); }
+export function encodeUnstake(validator, amount) { return new Writer().varint(ACTION_VARIANT.unstake).string(validator).varint(amount).bytes(); }
+export function encodeRegisterBlsKey(validator, pubkey, pop) { return new Writer().varint(ACTION_VARIANT.registerBlsKey).string(validator).vec(Array.from(pubkey), (w, b) => w.u8(b)).vec(Array.from(pop), (w, b) => w.u8(b)).bytes(); }
+export function encodeAuthorizeOperator(operator) { return new Writer().varint(ACTION_VARIANT.authorizeOperator).string(operator).bytes(); }
+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 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(); }
+export function encodeBurnAsset(asset, amount) { return new Writer().varint(ACTION_VARIANT.burnAsset).string(asset).varint(amount).bytes(); }
+export function encodeSetHolderFrozen(asset, holder, frozen) { return new Writer().varint(ACTION_VARIANT.setHolderFrozen).string(asset).string(holder).bool(frozen).bytes(); }
+export function encodeLockHolderAmount(asset, holder, amount, lock) { return new Writer().varint(lock ? ACTION_VARIANT.lockHolderAmount : ACTION_VARIANT.unlockHolderAmount).string(asset).string(holder).varint(amount).bytes(); }
+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(); }
+/** 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)
+    throw new Error("sub must be 32 bytes"); return new Writer().varint(ACTION_VARIANT.verifyClaimProof).string(asset).raw(sub).varint(todayDays).vec(Array.from(proof), (w, b) => w.u8(b)).bytes(); }
+/** Issuer opt-in: whether holders may clear `asset`'s gate with a claim proof instead of clear-text claims. */
+export function encodeSetPrivateClaims(asset, enabled) { return new Writer().varint(ACTION_VARIANT.setPrivateClaims).string(asset).bool(enabled).bytes(); }
+const token = (name) => new Writer().varint(TOKEN_ACTION).varint(TOKEN_VARIANT[name]);
+/** Permissionless token (`circuits/token`); its ref is `deriveAssetRef(sender, symbol.toLowerCase())`. `mintable: false` fixes supply at creation. Costs `token_create_fee` on top of the action fee. */
+export function encodeCreateToken(symbol, name, decimals, initialSupply, maxSupply, mintable) { return token("createToken").string(symbol).string(name).u8(decimals).varint(initialSupply).option(maxSupply, (w, cap) => w.varint(cap)).bool(mintable).bytes(); }
+export function encodeMintToken(tokenRef, to, amount) { return token("mintToken").string(tokenRef).string(to).varint(amount).bytes(); }
+export function encodeTransferToken(tokenRef, to, amount) { return token("transferToken").string(tokenRef).string(to).varint(amount).bytes(); }
+export function encodeBurnToken(tokenRef, amount) { return token("burnToken").string(tokenRef).varint(amount).bytes(); }
+export function encodeRenounceMint(tokenRef) { return token("renounceMint").string(tokenRef).bytes(); }
+/** Applies to become an attestor. The sender is the attestor: its address must be the `threshold`-of-`owners` multisig (threshold >= 2). Pays the application bond and opens a validator vote. */
+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(); }
+/** `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. */
+export function encodeSubmitProposal(proposal, description) {
+    const w = new Writer().varint(ACTION_VARIANT.submitProposal).varint(GOVERNANCE_ACTION[proposal.kind]).string(proposal.attestor);
+    if (proposal.kind === "addAttestor")
+        w.string(proposal.name).vec(proposal.owners, (x, o) => x.string(o)).u8(proposal.threshold).string(proposal.evidenceHash).string(proposal.evidenceUri);
+    return w.string(description).bytes();
+}
+/** Stake-weighted vote. One per validator per proposal. */
+export function encodeVoteProposal(proposal, approve) { return new Writer().varint(ACTION_VARIANT.voteProposal).varint(BigInt(proposal)).bool(approve).bytes(); }
+/** Anyone may close a proposal once its window has ended; this applies it if it passed and always lifts a removal block. */
+export function encodeExecuteProposal(proposal) { return new Writer().varint(ACTION_VARIANT.executeProposal).varint(BigInt(proposal)).bytes(); }
+export function encodeSetAssetLimits(asset, maxHolders, maxBalancePerHolder = null, maxAttestationAge = null) { return new Writer().varint(ACTION_VARIANT.setAssetLimits).string(asset).option(maxHolders, (w, value) => w.varint(value)).option(maxBalancePerHolder, (w, value) => w.varint(value)).option(maxAttestationAge, (w, value) => w.varint(value)).bytes(); }
+const nullableBig = (value) => value == null ? null : BigInt(value);
+export function encodePayload({ name, input }) {
+    if (name in POLICY_VARIANT)
+        return encodeAccountPolicy(name, input);
+    switch (name) {
+        case "transfer": return encodeTransfer(input.to, BigInt(input.amount));
+        case "joinValidator": return encodeJoinValidator(input.validator, BigInt(input.stake), Uint8Array.from(input.blsPubkey), Uint8Array.from(input.blsPop));
+        case "leaveValidator": return encodeLeaveValidator(input.validator);
+        case "stake": return encodeStake(input.validator, BigInt(input.amount));
+        case "unstake": return encodeUnstake(input.validator, BigInt(input.amount));
+        case "registerBlsKey": return encodeRegisterBlsKey(input.validator, Uint8Array.from(input.pubkey), Uint8Array.from(input.pop));
+        case "authorizeOperator": return encodeAuthorizeOperator(input.operator);
+        case "revokeOperator": return encodeRevokeOperator();
+        case "grantAttestation": return encodeGrantAttestation(input.subject, input.hash, input.topics, input.jurisdiction);
+        case "revokeAttestation": return encodeRevokeAttestation(input.subject);
+        case "registerAsset": return encodeRegisterAsset(input.assetId, input.complianceRequired, input.metadata);
+        case "issueAsset": return encodeIssueAsset(input.asset, BigInt(input.amount));
+        case "transferAsset": return encodeTransferAsset(input.asset, input.to, BigInt(input.amount));
+        case "freezeAsset":
+        case "unfreezeAsset": return encodeFreezeAsset(input.asset, input.frozen, input.reason);
+        case "burnAsset": return encodeBurnAsset(input.asset, BigInt(input.amount));
+        case "setHolderFrozen": return encodeSetHolderFrozen(input.asset, input.holder, input.frozen);
+        case "lockHolderAmount":
+        case "unlockHolderAmount": return encodeLockHolderAmount(input.asset, input.holder, BigInt(input.amount), input.lock);
+        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 "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);
+        case "submitProposal": return encodeSubmitProposal(input.action, input.description);
+        case "voteProposal": return encodeVoteProposal(BigInt(input.proposal), input.approve);
+        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 "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));
+        case "burnToken": return encodeBurnToken(input.token, BigInt(input.amount));
+        case "renounceMint": return encodeRenounceMint(input.token);
+        default: throw new Error(`unsupported action: ${name}`);
+    }
+}
+const invert = (table) => Object.fromEntries(Object.entries(table).map(([key, value]) => [value, key]));
+const VARIANT_NAME = invert(ACTION_VARIANT), TOKEN_NAME = invert(TOKEN_VARIANT), CLASS_NAME = invert(CLASS), TOPIC_NAME = invert(TOPIC), GOVERNANCE_NAME = invert(GOVERNANCE_ACTION);
+const known = (value, what) => { if (value === undefined)
+    throw new Error(`unknown ${what}`); return value; };
+/**
+ * Decodes a payload the SDK can encode, then re-encodes it and throws unless the bytes match, so what
+ * a co-signer is shown is exactly what they sign. Unknown variants throw rather than display partially.
+ */
+export function decodePayload(payload) {
+    const r = new Reader(payload), outer = Number(r.varint());
+    if (outer === ACCOUNT_POLICY_ACTION) {
+        const decoded = readAccountPolicy(r);
+        r.done();
+        if (toHex(encodePayload(decoded)) !== toHex(payload))
+            throw new Error("payload is not in canonical form");
+        return decoded;
+    }
+    const name = outer === TOKEN_ACTION ? known(TOKEN_NAME[Number(r.varint())], "token action") : known(VARIANT_NAME[outer], "action variant");
+    const str = () => r.string(), amount = () => r.varint().toString(), bytes = () => r.vec((rr) => rr.u8()), topics = () => r.vec((rr) => known(TOPIC_NAME[Number(rr.varint())], "claim topic"));
+    const read = {
+        transfer: () => ({ to: str(), amount: amount() }),
+        joinValidator: () => ({ validator: str(), stake: amount(), blsPubkey: bytes(), blsPop: bytes() }),
+        leaveValidator: () => ({ validator: str() }),
+        stake: () => ({ validator: str(), amount: amount() }),
+        unstake: () => ({ validator: str(), amount: amount() }),
+        registerBlsKey: () => ({ validator: str(), pubkey: bytes(), pop: bytes() }),
+        authorizeOperator: () => ({ operator: str() }),
+        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() } }),
+        issueAsset: () => ({ asset: str(), amount: amount() }),
+        transferAsset: () => ({ asset: str(), to: str(), amount: amount() }),
+        freezeAsset: () => ({ asset: str(), frozen: true, reason: str() }),
+        unfreezeAsset: () => ({ asset: str(), frozen: false, reason: str() }),
+        burnAsset: () => ({ asset: str(), amount: amount() }),
+        setHolderFrozen: () => ({ asset: str(), holder: str(), frozen: r.bool() }),
+        lockHolderAmount: () => ({ asset: str(), holder: str(), amount: amount(), lock: true }),
+        unlockHolderAmount: () => ({ asset: str(), holder: str(), amount: amount(), lock: false }),
+        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() }),
+        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() }),
+        submitProposal: () => { const kind = known(GOVERNANCE_NAME[Number(r.varint())], "governance action"), attestor = str(); const action = kind === "addAttestor" ? { kind, attestor, name: str(), owners: r.vec((rr) => rr.string()), threshold: r.u8(), evidenceHash: str(), evidenceUri: str() } : { kind, attestor }; return { action, description: str() }; },
+        voteProposal: () => ({ proposal: amount(), approve: r.bool() }),
+        executeProposal: () => ({ proposal: amount() }),
+        applyAttestor: () => ({ name: str(), owners: r.vec((rr) => rr.string()), threshold: r.u8(), evidenceHash: str(), evidenceUri: str() }),
+        blockAttestor: () => ({}),
+        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() }),
+        burnToken: () => ({ token: str(), amount: amount() }),
+        renounceMint: () => ({ token: str() }),
+    };
+    const decoded = { name, input: read[name]() };
+    r.done();
+    if (toHex(encodePayload(decoded)) !== toHex(payload))
+        throw new Error("payload is not in canonical form");
+    return decoded;
+}
+/** Mirrors `Action::signing_bytes`: the chain's 32-byte genesis hash (`GET /genesis-hash`) binds the signature to one chain, so an action signed for chain A is rejected on chain B. */
+export function signingBytes(genesis, sender, nonce, payload) { if (genesis.length !== 32)
+    throw new Error("genesis hash must be 32 bytes"); return new Writer().raw(genesis).string(sender).varint(nonce).raw(payload).bytes(); }
+export async function signAction(privateKey, genesis, sender, nonce, payload) { return toHex(new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, asBuffer(signingBytes(genesis, sender, nonce, payload))))); }
+export function submitBody(sender, nonce, signature, payload) { return { sender, nonce, signature, payload: Array.from(payload) }; }
+/** M-of-N sender, mirrors `xc_primitives::multisig_address`. Every member signs with plain `signAction(key, genesis, multisigAddress, nonce, payload)`; `multisigSignature` combines exactly `threshold` of them into the action's `signature` field. */
+export const MAX_MULTISIG_MEMBERS = 16;
+const compareBytes = (a, b) => { for (let i = 0; i < a.length; i++)
+    if (a[i] !== b[i])
+        return a[i] - b[i]; return 0; };
+function multisigPolicy(threshold, members) { const sorted = [...members].sort(compareBytes); if (!sorted.length || sorted.length > MAX_MULTISIG_MEMBERS)
+    throw new Error("member count must be 1..=16"); if (!Number.isInteger(threshold) || threshold < 1 || threshold > sorted.length)
+    throw new Error("threshold must be 1..=members"); if (sorted.some((m, i) => m.length !== 32 || (i > 0 && compareBytes(sorted[i - 1], m) >= 0)))
+    throw new Error("members must be unique 32-byte keys"); return sorted; }
+async function policyHash(threshold, sorted) { const domain = new TextEncoder().encode("arxium-multisig-v1"), input = new Uint8Array(domain.length + 2 + 32 * sorted.length); input.set(domain); input.set([threshold, sorted.length], domain.length); sorted.forEach((m, i) => input.set(m, domain.length + 2 + 32 * i)); return new Uint8Array(await crypto.subtle.digest("SHA-256", input)); }
+export async function multisigAddress(threshold, members) { const hash = await policyHash(threshold, multisigPolicy(threshold, members)); return encodeAddress(Uint8Array.from([MULTISIG_TAG, ...hash])); }
+/** `signatures`: [member public key, that member's hex signature]. */
+export function multisigSignature(threshold, members, signatures) { const sorted = multisigPolicy(threshold, members); const indexed = signatures.map(([key, sig]) => { const index = sorted.findIndex((m) => compareBytes(m, key) === 0); if (index < 0)
+    throw new Error("signer is not a member"); return [index, fromHex(sig)]; }).sort((a, b) => a[0] - b[0]); const out = new Writer().raw(Uint8Array.from([threshold, sorted.length])); sorted.forEach((m) => out.raw(m)); indexed.forEach(([index, sig]) => out.raw(Uint8Array.from([index])).raw(sig)); return toHex(out.bytes()); }
+/** Same checks as `Action::verify_signature` for a multisig sender. */
+export async function verifyMultisig(sender, signature, message) { const sent = decodeAddress(sender), witness = fromHex(signature), [threshold, n] = witness; if (sent.length !== 33 || witness.length !== 2 + 32 * n + 65 * threshold)
+    return false; const members = Array.from({ length: n }, (_, i) => witness.slice(2 + 32 * i, 34 + 32 * i)); const hash = await policyHash(threshold, multisigPolicy(threshold, members)); if (compareBytes(hash, sent.slice(1)) !== 0)
+    return false; let last = -1; for (let at = 2 + 32 * n; at < witness.length; at += 65) {
+    const index = witness[at];
+    if (index >= n || index <= last)
+        return false;
+    last = index;
+    const key = await crypto.subtle.importKey("raw", asBuffer(members[index]), "Ed25519", false, ["verify"]);
+    if (!await crypto.subtle.verify("Ed25519", key, asBuffer(witness.slice(at + 1, at + 65)), asBuffer(message)))
+        return false;
+} return true; }

package/dist/amounts.d.ts

@@ -0,0 +1,3 @@
+export declare const IUM_PER_ARX = 1000000000n;
+export declare function arxToIum(value: string): bigint;
+export declare function iumToArx(value: bigint): string;

package/dist/amounts.js

@@ -0,0 +1,5 @@
+export const IUM_PER_ARX = 1000000000n;
+export function arxToIum(value) { if (!/^(0|[1-9]\d*)(\.\d{1,9})?$/.test(value))
+    throw new Error("amount must be a non-negative decimal with at most 9 places"); const [whole, fraction = ""] = value.split("."); return BigInt(whole) * IUM_PER_ARX + BigInt((fraction + "000000000").slice(0, 9)); }
+export function iumToArx(value) { if (value < 0n)
+    throw new RangeError("amount cannot be negative"); const whole = value / IUM_PER_ARX, fraction = (value % IUM_PER_ARX).toString().padStart(9, "0").replace(/0+$/, ""); return fraction ? `${whole}.${fraction}` : whole.toString(); }

package/dist/bech32.d.ts

@@ -0,0 +1,9 @@
+export declare const HRP = "arx";
+export declare const ASSET_HRP = "arxasset";
+/** A plain address is a 32-byte ed25519 key; a multisig one is 0x01 ‖ sha256(policy), see multisig.ts. */
+export declare const MULTISIG_TAG = 1;
+export declare function encodeAddress(publicKey: Uint8Array): string;
+export declare function decodeAddress(address: string): Uint8Array;
+export declare function isMultisigAddress(address: string): boolean;
+export declare function decodeAssetRef(ref: string): Uint8Array;
+export declare function deriveAssetRef(issuer: string, assetId: string): Promise<string>;

package/dist/bech32.js

@@ -0,0 +1,39 @@
+const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const GENERATORS = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+export const HRP = "arx";
+export const ASSET_HRP = "arxasset";
+function polymod(values) { let chk = 1; for (const value of values) {
+    const top = chk >>> 25;
+    chk = ((chk & 0x1ffffff) << 5) ^ value;
+    for (let i = 0; i < 5; i++)
+        if ((top >>> i) & 1)
+            chk ^= GENERATORS[i];
+} return chk >>> 0; }
+function expand(hrp) { return [...hrp].map((char) => char.charCodeAt(0) >>> 5).concat(0, [...hrp].map((char) => char.charCodeAt(0) & 31)); }
+function convertBits(data, from, to, pad) { let acc = 0, bits = 0; const out = [], max = (1 << to) - 1; for (const byte of Array.from(data)) {
+    acc = (acc << from) | byte;
+    bits += from;
+    while (bits >= to) {
+        bits -= to;
+        out.push((acc >>> bits) & max);
+    }
+} if (pad && bits)
+    out.push((acc << (to - bits)) & max);
+else if (!pad && (bits >= from || ((acc << (to - bits)) & max)))
+    throw new Error("invalid padding"); return out; }
+function encode32(hrp, bytes) { const data = convertBits(bytes, 8, 5, true); const checksumValue = polymod([...expand(hrp), ...data, 0, 0, 0, 0, 0, 0]) ^ 1; const checksum = Array.from({ length: 6 }, (_, i) => (checksumValue >>> (5 * (5 - i))) & 31); return `${hrp}1${[...data, ...checksum].map((value) => CHARSET[value]).join("")}`; }
+function decode32(hrp, encoded, name) { if (encoded !== encoded.toLowerCase() || !encoded.startsWith(`${hrp}1`))
+    throw new Error(`invalid ${name}`); const values = [...encoded.slice(hrp.length + 1)].map((char) => { const value = CHARSET.indexOf(char); if (value < 0)
+    throw new Error(`invalid ${name}`); return value; }); if (polymod([...expand(hrp), ...values]) !== 1)
+    throw new Error("invalid checksum"); const bytes = Uint8Array.from(convertBits(values.slice(0, -6), 5, 8, false)); return bytes; }
+/** A plain address is a 32-byte ed25519 key; a multisig one is 0x01 ‖ sha256(policy), see multisig.ts. */
+export const MULTISIG_TAG = 0x01;
+function checkAddressBytes(bytes) { if (bytes.length !== 32 && !(bytes.length === 33 && bytes[0] === MULTISIG_TAG))
+    throw new Error("invalid address length"); return bytes; }
+function check32(bytes, name) { if (bytes.length !== 32)
+    throw new Error(`invalid ${name} length`); return bytes; }
+export function encodeAddress(publicKey) { return encode32(HRP, checkAddressBytes(publicKey)); }
+export function decodeAddress(address) { return checkAddressBytes(decode32(HRP, address, "address")); }
+export function isMultisigAddress(address) { return decodeAddress(address).length === 33; }
+export function decodeAssetRef(ref) { return check32(decode32(ASSET_HRP, ref, "asset ref"), "asset ref"); }
+export async function deriveAssetRef(issuer, assetId) { const pubkey = decodeAddress(issuer), id = new TextEncoder().encode(assetId), domain = new TextEncoder().encode("arxium/asset/v1"), input = new Uint8Array(domain.length + pubkey.length + 1 + id.length); input.set(domain); input.set(pubkey, domain.length); input.set(id, domain.length + pubkey.length + 1); return encode32(ASSET_HRP, new Uint8Array(await crypto.subtle.digest("SHA-256", input))); }

package/dist/bincode.d.ts

@@ -0,0 +1,31 @@
+/** Canonical bincode 2.x `config::standard()` writer for Arxium action payloads. */
+export declare class Writer {
+    private chunks;
+    bytes(): Uint8Array;
+    raw(bytes: Uint8Array | number[]): this;
+    u8(value: number): this;
+    bool(value: boolean): this;
+    varint(value: bigint | number): this;
+    private le;
+    string(value: string): this;
+    option<T>(value: T | null | undefined, write: (writer: Writer, value: T) => void): this;
+    vec<T>(values: readonly T[], write: (writer: Writer, value: T) => void): this;
+}
+/** A fresh ArrayBuffer holding exactly `bytes`. Not `bytes.slice().buffer`: Node's Buffer.slice() is a view, so `.buffer` would be the whole shared pool. */
+export declare const asBuffer: (bytes: Uint8Array) => ArrayBuffer;
+export declare function toHex(bytes: Uint8Array): string;
+export declare function fromHex(hex: string): Uint8Array;
+/** Reads what `Writer` writes. Pair every decode with a re-encode check (see `decodePayload`) rather than trusting it to reject non-canonical input. */
+export declare class Reader {
+    private readonly data;
+    private at;
+    constructor(data: Uint8Array);
+    u8(): number;
+    bool(): boolean;
+    varint(): bigint;
+    length(): number;
+    string(): string;
+    option<T>(read: (reader: Reader) => T): T | null;
+    vec<T>(read: (reader: Reader) => T): T[];
+    done(): void;
+}