@arxiumlabs/sdk 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,139 @@
-# 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.
+
+## 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

@@ -0,0 +1,185 @@
+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 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;
+    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;
+/** 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;
+/** 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,241 @@
+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,
+    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,
+};
+/** `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(); }
+/** 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)
+    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 "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);
+        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() }),
+        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() }),
+        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>;