@arxiumlabs/sdk 0.9.0 → 0.13.1

package/dist/cli.js

@@ -3,7 +3,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { stdin as input, stderr, stdout } from "node:process";
 import { createPrivateKey, createPublicKey } from "node:crypto";
-import { ArxiumRpc, RpcError, encodeApplyAttestor, encodeBlockAttestor, encodeExecuteProposal, encodeSubmitProposal, encodeVoteProposal, encodeAuthorizeOperator, encodeGrantAttestation, encodeIssueAsset, encodeRegisterAsset, encodeFreezeAsset, encodeSetHolderFrozen, encodeSetAssetLimits, encodeTransferAsset, encodeJoinValidator, encodeLeaveValidator, encodeRegisterBlsKey, encodeRevokeAttestation, encodeRevokeOperator, encodeStake, encodeTransfer, encodeUnstake, generateKey, isKeyFile, signAction, submitBody, unlockKey, verifyKeyFile, verifySignedAction, wrapPkcs8, encodeAddress, toHex, toKeyFile, PKCS8_ED25519_PREFIX, assemblePolicySignature, decodePayload, encodePayload, fromHex, multisigAddress, multisigSignature, signingBytes, asBuffer, ALL_ISSUER_CONTROLS, ISSUER_CONTROLS, bigintReplacer, encodeBurnAsset, encodeIssuerForcedTransfer, encodeRecoverHolder, encodeIssueAssetTo, encodeLockHolderAmount, encodeLockHolderAmountUntil, encodeLockIssuance, encodeTransferIssuer, encodeSetAssetMetadataUri, encodeSetPrivateClaims, encodeSnapshotHolders, encodeDistributeToHolders, encodeRedeemHolders, encodeSplitAsset, encodeCreateToken, encodeMintToken, encodeTransferToken, encodeBurnToken, encodeRenounceMint, encodeSettleDvp, signDvpConsent, } from "./index.js";
+import { ArxiumRpc, RpcError, encodeApplyAttestor, encodeBlockAttestor, encodeExecuteProposal, encodeSubmitProposal, encodeVoteProposal, encodeAuthorizeOperator, encodeGrantAttestation, encodeIssueAsset, encodeRegisterAsset, encodeFreezeAsset, encodeSetHolderFrozen, encodeSetAssetLimits, encodeTransferAsset, encodeJoinValidator, encodeLeaveValidator, encodeRegisterBlsKey, encodeRevokeAttestation, encodeRevokeOperator, encodeStake, encodeTransfer, encodeUnstake, generateKey, isKeyFile, signAction, submitBody, unlockKey, verifyKeyFile, verifySignedAction, wrapPkcs8, encodeAddress, toHex, toKeyFile, PKCS8_ED25519_PREFIX, assemblePolicySignature, decodePayload, encodePayload, fromHex, multisigAddress, multisigSignature, signingBytes, asBuffer, ALL_ISSUER_CONTROLS, ISSUER_CONTROLS, bigintReplacer, encodeBurnAsset, encodeIssuerForcedTransfer, encodeRecoverHolder, encodeIssueAssetTo, encodeLockHolderAmount, encodeLockHolderAmountUntil, encodeLockIssuance, encodeTransferIssuer, encodeSetAssetMetadataUri, encodeSetPrivateClaims, encodeSnapshotHolders, encodeDistributeToHolders, encodeRedeemHolders, encodeSplitAsset, encodeCreateToken, encodeMintToken, encodeTransferToken, encodeBurnToken, encodeRenounceMint, encodeSettleDvp, signDvpConsent, encodeDeployModule, encodeCallModule, encodeSettleVenue, encodeCancelVenueOrder, signVenueOrder, MAX_ORDER_LIFETIME, } from "./index.js";
 class UsageError extends Error {
 }
 function output(value, json) { stdout.write(!json && typeof value === "string" ? `${value}\n` : `${JSON.stringify(value, bigintReplacer, 2)}\n`); }
@@ -124,6 +124,8 @@ const USAGE = {
     "create-token": "<symbol> <name> <decimals> <initial-supply> <max-supply|-> mintable|fixed", "mint-token": "<token-ref> <to> <amount>",
     "transfer-token": "<token-ref> <to> <amount>", "burn-token": "<token-ref> <amount>", "renounce-mint": "<token-ref>",
     "settle-dvp": "<give-asset-ref|native> <give-amount> <counterparty> <take-asset-ref|native> <take-amount> <expires-at-height> <counterparty-signature>",
+    "venue-settle": "<trades.json>", "venue-cancel": "<order-id> <expires-at-height>",
+    "module-deploy": "<module.wasm> [salt]", "module-call": "<module-address> <gas-limit> [input-hex]",
 };
 const spendArg = (value) => value === "native" ? "native" : { asset: value };
 function morePayload(action, args) {
@@ -161,6 +163,14 @@ function morePayload(action, args) {
         case "transfer-token": return encodeTransferToken(arg(0), arg(1), int(2));
         case "burn-token": return encodeBurnToken(arg(0), int(1));
         case "settle-dvp": return encodeSettleDvp({ give: spendArg(arg(0)), giveAmount: int(1), counterparty: arg(2), take: spendArg(arg(3)), takeAmount: int(4), expiresAt: int(5) }, arg(6));
+        case "venue-settle": {
+            const raw = JSON.parse(arg(0));
+            const order = (o) => ({ owner: o.owner, orderId: BigInt(o.orderId), terms: { venue: o.terms.venue, give: o.terms.give, giveAmount: BigInt(o.terms.giveAmount), take: o.terms.take, takeAmount: BigInt(o.terms.takeAmount), expiresAt: BigInt(o.terms.expiresAt) }, signature: o.signature });
+            return encodeSettleVenue(raw.map((t) => ({ maker: order(t.maker), taker: order(t.taker) })));
+        }
+        case "venue-cancel": return encodeCancelVenueOrder(int(0), int(1));
+        case "module-deploy": return encodeDeployModule(hexArg(arg(0)), args[1] === undefined ? 0n : int(1));
+        case "module-call": return encodeCallModule(arg(0), args[2] === undefined ? new Uint8Array() : hexArg(args[2]), int(1));
         default: return encodeRenounceMint(arg(0));
     }
 }
@@ -180,7 +190,7 @@ async function main() {
         return;
     }
     if (!command)
-        throwUsage("use: arx keys|sign|submit|send|dvp-consent|query|verify");
+        throwUsage("use: arx keys|sign|submit|send|dvp-consent|venue-order|query|verify");
     if (command === "keys") {
         const [operation, ...keyArgs] = rest;
         if (operation === "new") {
@@ -300,8 +310,31 @@ async function main() {
         output({ counterparty: file.address, counterpartyNonce: nonce, signature, send: ["settle-dvp", give, giveAmount, file.address, take, takeAmount, expiresAt, signature] }, true);
         return;
     }
+    // One party's order for a venue: sign it with a fresh random id. The venue pairs two of these into `arx send venue-settle`.
+    if (command === "venue-order") {
+        const use = "venue-order needs <venue> <give-asset-ref|native> <give-amount> <take-asset-ref|native> <take-amount> <expires-at-height> [--order-id n]";
+        const idFlag = rest.indexOf("--order-id"), idText = idFlag >= 0 ? rest.splice(idFlag, 2)[1] : undefined;
+        if (idFlag >= 0 && !/^\d+$/.test(idText ?? ""))
+            throwUsage(use);
+        const orderId = idText !== undefined ? BigInt(idText) : new DataView(crypto.getRandomValues(new Uint8Array(8)).buffer).getBigUint64(0);
+        const [venueAddress, give, giveAmount, take, takeAmount, expiresAt] = rest;
+        if (!venueAddress || !give || !take || !/^\d+$/.test(giveAmount ?? "") || !/^\d+$/.test(takeAmount ?? "") || !/^\d+$/.test(expiresAt ?? ""))
+            throwUsage(use);
+        const tip = BigInt((await rpc.status()).tip_height);
+        if (BigInt(expiresAt) > tip + MAX_ORDER_LIFETIME)
+            throwUsage(`expires-at must be within ${MAX_ORDER_LIFETIME} blocks of the tip (${tip})`);
+        const { file, privateKey } = await loadKey(globals.key), genesis = await rpc.genesisHash();
+        const terms = { venue: venueAddress, give: spendArg(give), giveAmount: BigInt(giveAmount), take: spendArg(take), takeAmount: BigInt(takeAmount), expiresAt: BigInt(expiresAt) };
+        output({ owner: file.address, orderId, terms, signature: await signVenueOrder(privateKey, genesis, file.address, orderId, terms) }, true);
+        return;
+    }
     if (command === "sign" || command === "send") {
-        const action = rest[0] ?? throwUsage(`${command} needs an action`), { file, privateKey } = await loadKey(globals.key), encoded = payload(action, rest.slice(1));
+        const action = rest[0] ?? throwUsage(`${command} needs an action`), { file, privateKey } = await loadKey(globals.key), actionArgs = rest.slice(1);
+        if (action === "venue-settle")
+            actionArgs[0] = await readFile(actionArgs[0] ?? throwUsage("venue-settle needs <trades.json>"), "utf8");
+        if (action === "module-deploy")
+            actionArgs[0] = toHex(new Uint8Array(await readFile(actionArgs[0] ?? throwUsage("module-deploy needs <module.wasm>"))));
+        const encoded = payload(action, actionArgs);
         if (command === "sign") {
             const nonce = globals.nonce ?? await rpc.account(file.address).then((account) => account.nonce, (error) => { if (error instanceof RpcError && error.status === 404)
                 return 0; throw error; });
@@ -344,11 +377,22 @@ async function main() {
                                 : operation === "attestor" ? await rpc.attestor(value ?? throwUsage("attestor needs an address"))
                                     : operation === "validator" ? await rpc.validator(value ?? throwUsage("validator needs an address"))
                                         : operation === "stakes" ? await rpc.stakes(value ?? throwUsage("stakes needs an address"))
-                                            : operation === "fee" ? await rpc.actionFee()
-                                                : throwUsage("use: arx query status|account|block|action|validators|validator|finality|search|assets [address]|asset|holders|balance|attestors|attestor|stakes|fee");
+                                            : operation === "module" ? await rpc.module(value ?? throwUsage("module needs an address"))
+                                                : operation === "module-state" ? await rpc.moduleState(value ?? throwUsage("module-state needs <address> <key-hex>"), rest[2] ?? throwUsage("module-state needs <address> <key-hex>"))
+                                                    : operation === "fee" ? await rpc.actionFee()
+                                                        : throwUsage("use: arx query status|account|block|action|validators|validator|finality|search|assets [address]|asset|holders|balance|attestors|attestor|stakes|module|module-state|fee");
         output(result, globals.json);
         return;
     }
+    // Dry-runs a module call as the key's address; no passphrase needed, nothing is signed or sent.
+    if (command === "simulate") {
+        const [module, gas, inputHex] = rest;
+        const caller = (await readKeyFile(globals.key)).address;
+        if (!module || !gas || !/^\d+$/.test(gas))
+            throwUsage("simulate needs <module-address> <gas-limit> [input-hex] and --key");
+        output(await rpc.simulateModule(module, { caller, input: inputHex === undefined ? new Uint8Array() : hexArg(inputHex), gasLimit: BigInt(gas) }), globals.json);
+        return;
+    }
     throwUsage(`unknown command: ${command}`);
 }
 main().catch((error) => { const usage = error instanceof UsageError; stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = usage ? 2 : 1; });

package/dist/fees.d.ts

@@ -3,6 +3,10 @@ export type FeeParams = {
     actionFee: bigint;
     weightFee: bigint;
 };
+/** Fuel one weight unit pays for (`FUEL_PER_WEIGHT` in `arxd/runtime/src/module.rs`). */
+export declare const FUEL_PER_WEIGHT = 50;
+/** Dispute-artifact pricing for module actions (`BLOCK_PROOF_KEYS`, `PROOF_WEIGHT_PER_KEY`, `MODULE_BASE_KEYS`, `DEPLOY_WEIGHT_PER_CODE_BYTE`, `COST_READ` in metering.rs and `xc_wasm`). */
+export declare const BLOCK_PROOF_KEYS = 64, PROOF_WEIGHT_PER_KEY = 15000, MODULE_BASE_KEYS = 4, DEPLOY_WEIGHT_PER_CODE_BYTE = 7, COST_READ = 1000;
 /** `POLICY_AUTHORIZATION_WEIGHT`: added when a stateful account policy authorizes the action. */
 export declare const POLICY_AUTHORIZATION_WEIGHT = 5000;
 /** A single-key ed25519 signature: 64 bytes as hex. */

package/dist/fees.js

@@ -1,7 +1,7 @@
-import { ACTION_VARIANT, TOKEN_ACTION, TOKEN_VARIANT } from "./actions.js";
+import { ACTION_VARIANT, COLLATERAL_ACTION, COLLATERAL_VARIANT, TOKEN_ACTION, TOKEN_VARIANT, VENUE_ACTION, VENUE_VARIANT } from "./actions.js";
 import { Reader } from "./bincode.js";
 import { ACCOUNT_POLICY_ACTION } from "./policy.js";
-/** `base_weight` in metering.rs, by `ActionPayload` discriminant. Token and account-policy actions are handled below. */
+/** `base_weight` in metering.rs, by `ActionPayload` discriminant. Token, collateral, venue and account-policy actions are handled below. */
 const BASE_WEIGHT = {
     [ACTION_VARIANT.transfer]: 50,
     [ACTION_VARIANT.stake]: 100, [ACTION_VARIANT.unstake]: 100,
@@ -25,6 +25,10 @@ const BASE_WEIGHT = {
     5 /* SubmitEquivocationEvidence */: 2_000,
     15 /* SubmitExecutionFault */: 500_000,
 };
+/** Fuel one weight unit pays for (`FUEL_PER_WEIGHT` in `arxd/runtime/src/module.rs`). */
+export const FUEL_PER_WEIGHT = 50;
+/** Dispute-artifact pricing for module actions (`BLOCK_PROOF_KEYS`, `PROOF_WEIGHT_PER_KEY`, `MODULE_BASE_KEYS`, `DEPLOY_WEIGHT_PER_CODE_BYTE`, `COST_READ` in metering.rs and `xc_wasm`). */
+export const BLOCK_PROOF_KEYS = 64, PROOF_WEIGHT_PER_KEY = 15_000, MODULE_BASE_KEYS = 4, DEPLOY_WEIGHT_PER_CODE_BYTE = 7, COST_READ = 1_000;
 /** `POLICY_AUTHORIZATION_WEIGHT`: added when a stateful account policy authorizes the action. */
 export const POLICY_AUTHORIZATION_WEIGHT = 5_000;
 /** A single-key ed25519 signature: 64 bytes as hex. */
@@ -37,6 +41,28 @@ function baseWeight(payload) {
         return Number(r.varint()) === TOKEN_VARIANT.createToken ? 150 : 100;
     if (variant === ACCOUNT_POLICY_ACTION)
         return 1_000;
+    if (variant === COLLATERAL_ACTION) {
+        const action = Number(r.varint());
+        return action === COLLATERAL_VARIANT.pledge || action === COLLATERAL_VARIANT.substitutePledge ? 350 : action === COLLATERAL_VARIANT.seizePledge ? 250 : 150;
+    }
+    if (variant === VENUE_ACTION) {
+        // `VENUE_SETTLE_BASE + trades × VENUE_TRADE_WEIGHT` in metering.rs; a cancel is flat.
+        return Number(r.varint()) === VENUE_VARIANT.settleVenue ? 100 + Number(r.varint()) * 800 : 100;
+    }
+    // `2_000 + 7 × code length` in metering.rs: the code rides in a dispute artifact about six times.
+    if (variant === ACTION_VARIANT.deployModule)
+        return 2_000 + r.vec((rr) => rr.u8()).length * DEPLOY_WEIGHT_PER_CODE_BYTE;
+    // The larger of `100 + ceil(gas_limit / FUEL_PER_WEIGHT)` and the proof bytes it could add (rows it could
+    // touch × PROOF_WEIGHT_PER_KEY) in metering.rs: priced by the limit, not by use. A tight limit is cheap.
+    if (variant === ACTION_VARIANT.callModule) {
+        r.string();
+        r.vec((rr) => rr.u8());
+        const gas = r.varint(), ceilDiv = (a, b) => (a + BigInt(b) - 1n) / BigInt(b);
+        const execution = 100n + ceilDiv(gas, FUEL_PER_WEIGHT);
+        const rows = ceilDiv(gas, COST_READ) + BigInt(MODULE_BASE_KEYS), keys = rows < BigInt(BLOCK_PROOF_KEYS) ? rows : BigInt(BLOCK_PROOF_KEYS);
+        const proofs = keys * BigInt(PROOF_WEIGHT_PER_KEY);
+        return Number(execution > proofs ? execution : proofs);
+    }
     const weight = BASE_WEIGHT[variant];
     if (weight === undefined)
         throw new Error(`unknown action variant: ${variant}`);

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/rpc.d.ts

@@ -164,6 +164,90 @@ export type Validator = {
     bls_registered: boolean;
     operator: string | null;
 };
+/**
+ * One snapshot holder's part in a corporate action (`DistributeToHolders`, `RedeemHolders`, `SplitAsset`). `amount` is in
+ * `payout_asset` for a distribution, else in `asset`; for `withheld` it is the share the issuer kept because the holder failed
+ * the payout asset's compliance. Floor-rounding dust never appears on a line.
+ */
+export type CorporateActionLine = {
+    action_index: number;
+    signature: string;
+    asset: string;
+    payout_asset: string | null;
+    holder: string;
+    amount: bigint;
+    outcome: "paid" | "withheld" | "minted" | "forced_back" | "redeemed";
+};
+/** `rpc.simulateModule`: hex strings throughout; `balances` are what the call leaves (`asset` is empty for the native token). */
+export type ModuleSimulation = {
+    ok: true;
+    gas_used: number;
+    return: string;
+    writes: {
+        key: string;
+        value: string | null;
+    }[];
+    events: {
+        topic: string;
+        data: string;
+    }[];
+    balances: {
+        asset: string;
+        holder: string;
+        balance: string;
+    }[];
+} | {
+    ok: false;
+    error: string;
+};
+/** `rpc.module(address)`: `code_hash` is hex, `code_size` in bytes. */
+export type ModuleInfo = {
+    address: string;
+    code_hash: string;
+    deployer: string;
+    deployed_at: number;
+    version: number;
+    code_size: number;
+};
+/** A collateral pledge as stored (`xc_primitives::Pledge`). `asset` is `"Native"` or `{ Asset: ref }`, the node's JSON for `SpendAsset`. */
+export type Pledge = {
+    pledgor: string;
+    beneficiary: string;
+    valuation_agent: string;
+    asset: "Native" | {
+        Asset: string;
+    };
+    amount: bigint;
+    haircut_bps: number;
+    exposure: bigint;
+    unit_price: bigint;
+    marked_at: number;
+    cure_period_blocks: number;
+    maturity: number | null;
+    margin_call: {
+        opened_at: number;
+        deadline: number;
+    } | null;
+};
+/** `rpc.pledge(id)`: the record plus what it means at the tip. `collateral_value` and `shortfall` are `null` when the valuation overflows. */
+export type PledgeStatus = Pledge & {
+    id: string;
+    collateral_value: bigint | null;
+    shortfall: bigint | null;
+    in_default: boolean;
+};
+/** A pledge a block opened or changed (`record` is its end-of-block state), or closed (`record: null`, released or seized). */
+export type PledgeEffect = {
+    pledge: string;
+    record: Pledge | null;
+};
+/** `rpc.blockEffects(height)`. `corporate_actions` and `pledges` are typed; the other fields mirror the node's `BlockEffects`. */
+export type BlockEffects = {
+    height: number;
+    corporate_actions: CorporateActionLine[];
+    pledges: PledgeEffect[];
+    [field: string]: unknown;
+};
 export type ActionFeeInfo = {
     action_fee: bigint;
     weight_fee: bigint;
@@ -186,6 +270,8 @@ export declare class ArxiumRpc {
     private readonly senders;
     constructor(options: RpcOptions);
     private request;
+    /** Follows `next_cursor` through a paged list route (`{ items, next_cursor }`); a node that predates paging answers with the whole bare array. */
+    private allPages;
     private genesis?;
     /** This chain's genesis hash, fetched once per client; every signature binds it. */
     genesisHash(): Promise<Uint8Array>;
@@ -214,9 +300,36 @@ export declare class ArxiumRpc {
     blocks<T = unknown>(from: number, to: number): Promise<T>;
     block<T = unknown>(height: number): Promise<T>;
     blockByHash<T = unknown>(hash: string): Promise<T>;
-    /** State changes a block made (balances, assets, stake), for indexers. */
-    blockEffects<T = unknown>(height: number): Promise<T>;
-    effects<T = unknown>(from: number, to: number): Promise<T>;
+    /** State changes a block made (balances, assets, stake, per-holder corporate-action lines), for indexers. */
+    blockEffects<T = BlockEffects>(height: number): Promise<T>;
+    effects<T = BlockEffects[]>(from: number, to: number): Promise<T>;
+    /** A deployed WASM module's record (`GET /modules/{address}`). */
+    module(address: string): Promise<ModuleInfo>;
+    /** The module's code as hex. */
+    moduleCode(address: string): Promise<{
+        code_hash: string;
+        code: string;
+    }>;
+    /** One row of a module's storage by hex key (at most 64 bytes); `value` is hex, or `null` when the row is absent. */
+    moduleState(address: string, keyHex: string): Promise<{
+        key: string;
+        value: string | null;
+    }>;
+    /**
+     * Dry-runs a module call at the tip and returns what it would do; nothing is written. A revert, trap,
+     * out-of-gas or refused rule comes back as `{ ok: false, error }`, not as an exception. It skips the action's own
+     * checks (signature, nonce, fee, account policy), so a simulation can succeed where the real action is refused.
+     * `caller` need not exist on chain. Runs at the next height with the wall clock as its time.
+     */
+    simulateModule(address: string, call: {
+        caller: string;
+        input?: Uint8Array;
+        gasLimit: number | bigint;
+    }): Promise<ModuleSimulation>;
+    /** One pledge by id (`pledgeId(pledgor, nonce)`). */
+    pledge(id: string): Promise<PledgeStatus>;
+    /** The pledges encumbering `address`'s balance of `asset`, oldest first. Native collateral is escrowed, so it is not listed. */
+    accountAssetPledges(address: string, asset: string): Promise<PledgeStatus[]>;
     /** Sorted validator addresses, at the tip or at `height`. */
     validators<T = string[]>(height?: number): Promise<T>;
     validator<T = Validator>(address: string): Promise<T>;

package/dist/rpc.js

@@ -1,6 +1,6 @@
 import { signAction, signingBytes, submitBody, verifyMultisig } from "./actions.js";
 import { decodeAddress, isMultisigAddress } from "./bech32.js";
-import { asBuffer, fromHex } from "./bincode.js";
+import { asBuffer, fromHex, toHex } from "./bincode.js";
 import { verifyPolicySignature } from "./policy.js";
 export class RpcError extends Error {
     status;
@@ -20,7 +20,7 @@ export class ActionDroppedError extends Error {
     }
 }
 /** Keys whose integer values are token amounts (u128 on the node): always `bigint`, so callers never see a rounded balance. */
-const AMOUNT_KEYS = new Set(["balance", "amount", "stake", "active_amount", "frozen_amount", "total_supply", "max_supply", "max_balance_per_holder", "total", "action_fee", "weight_fee", "token_create_fee", "min_stake"]);
+const AMOUNT_KEYS = new Set(["balance", "amount", "stake", "active_amount", "frozen_amount", "total_supply", "max_supply", "max_balance_per_holder", "total", "action_fee", "weight_fee", "token_create_fee", "min_stake", "exposure", "unit_price", "collateral_value", "shortfall"]);
 const MARK = "\u0000int:";
 /**
  * `JSON.parse` that never rounds an integer: the node writes u128 amounts as bare JSON numbers, and anything above 2^53
@@ -46,6 +46,18 @@ export class ArxiumRpc {
     constructor(options) { this.rpc = options.rpc.replace(/\/+$/, ""); this.token = options.token; this.requestFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init)); } // browsers and Workers throw "Illegal invocation" if fetch is called with `this` = ArxiumRpc
     async request(path, init) { const response = await this.requestFetch(`${this.rpc}${path}`, { ...init, headers: { ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}), ...init?.headers } }); const text = await response.text(); if (!response.ok)
         throw new RpcError(response.status, text || `${response.status} ${response.statusText}`); return text ? parseJson(text) : undefined; }
+    /** Follows `next_cursor` through a paged list route (`{ items, next_cursor }`); a node that predates paging answers with the whole bare array. */
+    async allPages(path) {
+        const items = [];
+        for (let cursor = 0; cursor !== null;) {
+            const page = await this.request(`${path}${path.includes("?") ? "&" : "?"}limit=100&cursor=${cursor}`);
+            if (Array.isArray(page))
+                return page;
+            items.push(...page.items);
+            cursor = page.next_cursor;
+        }
+        return items;
+    }
     genesis;
     /** This chain's genesis hash, fetched once per client; every signature binds it. */
     genesisHash() { return this.genesis ??= this.request("/genesis-hash").then((r) => fromHex(r.genesis_hash.replace(/^0x/, "")), (e) => { this.genesis = undefined; throw e; }); }
@@ -61,7 +73,7 @@ export class ArxiumRpc {
     delegatedStake(master, validator) { return this.request(`/stake/${encodeURIComponent(master)}/${encodeURIComponent(validator)}`); }
     blsKey(address) { return this.request(`/accounts/${encodeURIComponent(address)}/bls-key`); }
     /** Every registered asset, or one issuer's. */
-    listAssets(issuer) { return this.request(issuer ? `/assets?issuer=${encodeURIComponent(issuer)}` : "/assets"); }
+    listAssets(issuer) { return this.allPages(issuer ? `/assets?issuer=${encodeURIComponent(issuer)}` : "/assets"); }
     asset(assetRef) { return this.request(`/assets/${encodeURIComponent(assetRef)}`); }
     /** The asset `issuer` registered as `assetId`, or `null` when that id is still free for them. */
     async assetByAlias(issuer, assetId) { try {
@@ -73,8 +85,8 @@ export class ArxiumRpc {
         throw error;
     } }
     /** The cap table: every address with a non-zero balance, with its freeze state. */
-    assetHolders(assetRef) { return this.request(`/assets/${encodeURIComponent(assetRef)}/holders`); }
-    attestors() { return this.request("/attestors"); }
+    assetHolders(assetRef) { return this.allPages(`/assets/${encodeURIComponent(assetRef)}/holders`); }
+    attestors() { return this.allPages("/attestors"); }
     attestor(address) { return this.request(`/attestors/${encodeURIComponent(address)}`); }
     submit(action) { return this.request("/actions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(action) }); }
     async action(signature) { try {
@@ -88,9 +100,31 @@ export class ArxiumRpc {
     blocks(from, to) { return this.request(`/blocks?from=${from}&to=${to}`); }
     block(height) { return this.request(`/blocks/${height}`); }
     blockByHash(hash) { return this.request(`/blocks/by-hash/${encodeURIComponent(hash)}`); }
-    /** State changes a block made (balances, assets, stake), for indexers. */
+    /** State changes a block made (balances, assets, stake, per-holder corporate-action lines), for indexers. */
     blockEffects(height) { return this.request(`/blocks/${height}/effects`); }
     effects(from, to) { return this.request(`/effects?from=${from}&to=${to}`); }
+    /** A deployed WASM module's record (`GET /modules/{address}`). */
+    module(address) { return this.request(`/modules/${encodeURIComponent(address)}`); }
+    /** The module's code as hex. */
+    moduleCode(address) { return this.request(`/modules/${encodeURIComponent(address)}/code`); }
+    /** One row of a module's storage by hex key (at most 64 bytes); `value` is hex, or `null` when the row is absent. */
+    moduleState(address, keyHex) { return this.request(`/modules/${encodeURIComponent(address)}/state/${encodeURIComponent(keyHex)}`); }
+    /**
+     * Dry-runs a module call at the tip and returns what it would do; nothing is written. A revert, trap,
+     * out-of-gas or refused rule comes back as `{ ok: false, error }`, not as an exception. It skips the action's own
+     * checks (signature, nonce, fee, account policy), so a simulation can succeed where the real action is refused.
+     * `caller` need not exist on chain. Runs at the next height with the wall clock as its time.
+     */
+    simulateModule(address, call) {
+        const gas = Number(call.gasLimit);
+        if (!Number.isSafeInteger(gas) || gas < 0)
+            throw new RangeError("gasLimit must be a non-negative safe integer");
+        return this.request(`/modules/${encodeURIComponent(address)}/simulate`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ caller: call.caller, input: toHex(call.input ?? new Uint8Array()), gas_limit: gas }) });
+    }
+    /** One pledge by id (`pledgeId(pledgor, nonce)`). */
+    pledge(id) { return this.request(`/pledges/${encodeURIComponent(id)}`); }
+    /** The pledges encumbering `address`'s balance of `asset`, oldest first. Native collateral is escrowed, so it is not listed. */
+    accountAssetPledges(address, asset) { return this.request(`/accounts/${encodeURIComponent(address)}/assets/${encodeURIComponent(asset)}/pledges`); }
     /** Sorted validator addresses, at the tip or at `height`. */
     validators(height) { return this.request(height === undefined ? "/validators" : `/validators?height=${height}`); }
     validator(address) { return this.request(`/validators/${encodeURIComponent(address)}`); }
@@ -99,7 +133,7 @@ export class ArxiumRpc {
     operatorValidators(operator) { return this.request(`/operators/${encodeURIComponent(operator)}/validators`); }
     finality() { return this.request("/finality"); }
     /** Ids of stored equivocation/fault evidence; `evidence(id)` returns one. */
-    evidenceList() { return this.request("/evidence"); }
+    evidenceList() { return this.allPages("/evidence"); }
     evidence(id) { return this.request(`/evidence/${encodeURIComponent(id)}`); }
     /** Merkle proofs against a finalized state root, for light clients. */
     accountProof(address) { return this.request(`/accounts/${encodeURIComponent(address)}/proof`); }
@@ -112,12 +146,15 @@ export class ArxiumRpc {
     async feeParams() { const fee = await this.actionFee(); return { actionFee: BigInt(fee.action_fee), weightFee: BigInt(fee.weight_fee) }; }
     /** Signs at the sender's current nonce, submits and polls until confirmed (or finalized). Calls for one sender run one after another. */
     sendAction(options) {
+        // Capture at invocation, including time spent waiting in this sender's queue.
+        options = { ...options, payload: Uint8Array.from(options.payload) };
         const previous = this.senders.get(options.sender) ?? Promise.resolve();
-        const run = previous.catch(() => undefined).then(() => this.sendNow(options));
-        const tail = run.catch(() => undefined);
-        this.senders.set(options.sender, tail);
-        void tail.then(() => { if (this.senders.get(options.sender) === tail)
-            this.senders.delete(options.sender); });
+        // A failed/uncertain send rejects already queued requests instead of signing again.
+        const run = previous.then(() => this.sendNow(options));
+        this.senders.set(options.sender, run);
+        const cleanup = () => { if (this.senders.get(options.sender) === run)
+            this.senders.delete(options.sender); };
+        void run.then(cleanup, cleanup);
         return run;
     }
     async sendNow(options) {

package/dist/signer.d.ts

@@ -0,0 +1,63 @@
+import { type DvpOrder } from "./actions.js";
+/** Pure Ed25519 over the supplied message bytes, not Ed25519ph or a provider digest mode. */
+export interface Ed25519Signer {
+    readonly algorithm: "Ed25519";
+    /** Raw32-byte compressed Ed25519 public key, not DER, PEM or an address. */
+    readonly publicKey: Uint8Array;
+    /** One attempt. Return the raw64-byte signature; reject on refusal or an uncertain outcome. */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+}
+export declare class SignerVerificationError extends Error {
+    constructor(message: string);
+}
+/** Local developer adapter. Does not export private key material or perform a probe signature. */
+export declare function localEd25519Signer(privateKey: CryptoKey, publicKey: Uint8Array): Ed25519Signer;
+/** Sign exactly these bytes, verify against the caller-selected key, return lowercase signature hex. */
+export declare function signBytesWithSigner(signer: Ed25519Signer, expectedPublicKey: Uint8Array, message: Uint8Array): Promise<string>;
+/** Pins the key and callback at creation; plugs into existing ArxiumRpc.sendAction({ sign }). */
+export declare function verifiedSignerCallback(signer: Ed25519Signer, expectedPublicKey: Uint8Array): (message: Uint8Array) => Promise<string>;
+/** The expected key may be a member of a multisig/policy sender; authorization is a separate check. */
+export declare function signActionWithSigner(signer: Ed25519Signer, expectedPublicKey: Uint8Array, genesis: Uint8Array, sender: string, nonce: number | bigint, payload: Uint8Array): Promise<string>;
+export declare function signDvpConsentWithSigner(signer: Ed25519Signer, expectedPublicKey: Uint8Array, genesis: Uint8Array, initiator: string, order: DvpOrder, counterpartyNonce: number | bigint): Promise<string>;
+/**
+ * The two methods of `KMS` from `@aws-sdk/client-kms` (the aggregated client, not `KMSClient`) this adapter calls.
+ * The SDK ships no AWS dependency: pass your own configured client.
+ */
+export type AwsKmsClient = {
+    getPublicKey(input: {
+        KeyId: string;
+    }): Promise<{
+        PublicKey?: Uint8Array;
+        KeySpec?: string;
+    }>;
+    sign(input: {
+        KeyId: string;
+        Message: Uint8Array;
+        MessageType: "RAW";
+        SigningAlgorithm: "ED25519_SHA_512";
+    }): Promise<{
+        Signature?: Uint8Array;
+    }>;
+};
+/** AWS KMS caps a RAW message at 4096 bytes; pure Ed25519 cannot be prehashed, so a larger action cannot be KMS-signed. */
+export declare const AWS_KMS_MAX_MESSAGE = 4096;
+/** An `ECC_NIST_EDWARDS25519` key with `ED25519_SHA_512` (pure Ed25519, `MessageType: RAW`). Reads the key's public key once. */
+export declare function awsKmsEd25519Signer(kms: AwsKmsClient, keyId: string): Promise<Ed25519Signer>;
+/** The subset of a `pkcs11js` `PKCS11` instance this adapter calls. The SDK ships no native module: pass your own, logged in. */
+export type Pkcs11Module = {
+    C_SignInit(session: Buffer, mechanism: {
+        mechanism: number;
+    }, key: Buffer): void;
+    C_Sign(session: Buffer, data: Buffer, signature: Buffer): Buffer;
+    C_GetAttributeValue(session: Buffer, object: Buffer, template: {
+        type: number;
+    }[]): {
+        type: number;
+        value?: Buffer;
+    }[];
+};
+/**
+ * A `CKK_EC_EDWARDS` key pair on a PKCS#11 v3 token (YubiHSM 2, Luna 7.7+, SoftHSM 2.6+), signed with `CKM_EDDSA` and no
+ * parameters: pure Ed25519. The public key comes from the public object's `CKA_EC_POINT`.
+ */
+export declare function pkcs11Ed25519Signer(pkcs11: Pkcs11Module, session: Buffer, privateKey: Buffer, publicKeyObject: Buffer): Ed25519Signer;

package/dist/signer.js

@@ -0,0 +1,107 @@
+import { dvpConsentBytes, signingBytes } from "./actions.js";
+import { asBuffer, toHex } from "./bincode.js";
+export class SignerVerificationError extends Error {
+    constructor(message) { super(message); this.name = "SignerVerificationError"; }
+}
+function rawKey(value) {
+    if (!(value instanceof Uint8Array) || value.length !== 32)
+        throw new SignerVerificationError("expected a raw32-byte Ed25519 public key");
+    return Uint8Array.from(value);
+}
+function pinSigner(signer, expectedPublicKey) {
+    const expected = rawKey(expectedPublicKey), advertised = rawKey(signer.publicKey);
+    const sign = signer.sign;
+    if (signer.algorithm !== "Ed25519" || typeof sign !== "function")
+        throw new SignerVerificationError("signer must implement pure Ed25519");
+    if (!expected.every((byte, i) => byte === advertised[i]))
+        throw new SignerVerificationError("signer public key does not match the expected key");
+    return { publicKey: expected, sign: sign.bind(signer) };
+}
+async function verifiedSign(signer, message) {
+    // Keep the trusted message private. A provider may retain/mutate its own input buffer.
+    if (!(message instanceof Uint8Array))
+        throw new SignerVerificationError("message must be Uint8Array bytes");
+    const snapshot = Uint8Array.from(message);
+    const response = await signer.sign(Uint8Array.from(snapshot));
+    if (!(response instanceof Uint8Array) || response.length !== 64)
+        throw new SignerVerificationError("signer must return a raw64-byte Ed25519 signature");
+    const signature = Uint8Array.from(response);
+    const key = await crypto.subtle.importKey("raw", asBuffer(signer.publicKey), "Ed25519", false, ["verify"]);
+    if (!await crypto.subtle.verify("Ed25519", key, asBuffer(signature), asBuffer(snapshot)))
+        throw new SignerVerificationError("signature does not verify for the expected key and original message");
+    return toHex(signature);
+}
+/** Local developer adapter. Does not export private key material or perform a probe signature. */
+export function localEd25519Signer(privateKey, publicKey) {
+    const raw = rawKey(publicKey);
+    if (privateKey.type !== "private" || privateKey.algorithm.name !== "Ed25519" || !privateKey.usages.includes("sign"))
+        throw new SignerVerificationError("local signer needs an Ed25519 private signing key");
+    return Object.freeze({
+        algorithm: "Ed25519",
+        get publicKey() { return Uint8Array.from(raw); },
+        async sign(message) { return new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, asBuffer(message))); },
+    });
+}
+/** Sign exactly these bytes, verify against the caller-selected key, return lowercase signature hex. */
+export async function signBytesWithSigner(signer, expectedPublicKey, message) {
+    return verifiedSign(pinSigner(signer, expectedPublicKey), message);
+}
+/** Pins the key and callback at creation; plugs into existing ArxiumRpc.sendAction({ sign }). */
+export function verifiedSignerCallback(signer, expectedPublicKey) {
+    const pinned = pinSigner(signer, expectedPublicKey);
+    return (message) => verifiedSign(pinned, message);
+}
+/** The expected key may be a member of a multisig/policy sender; authorization is a separate check. */
+export async function signActionWithSigner(signer, expectedPublicKey, genesis, sender, nonce, payload) {
+    return signBytesWithSigner(signer, expectedPublicKey, signingBytes(genesis, sender, nonce, payload));
+}
+export async function signDvpConsentWithSigner(signer, expectedPublicKey, genesis, initiator, order, counterpartyNonce) {
+    return signBytesWithSigner(signer, expectedPublicKey, dvpConsentBytes(genesis, initiator, order, counterpartyNonce));
+}
+const SPKI_ED25519_PREFIX = "302a300506032b6570032100";
+/** Raw 32-byte key from an Ed25519 SubjectPublicKeyInfo (what AWS KMS GetPublicKey returns). */
+function spkiEd25519(der) {
+    if (!(der instanceof Uint8Array) || der.length !== 44 || toHex(der.subarray(0, 12)) !== SPKI_ED25519_PREFIX)
+        throw new SignerVerificationError("expected an Ed25519 SubjectPublicKeyInfo public key");
+    return der.slice(12);
+}
+/** AWS KMS caps a RAW message at 4096 bytes; pure Ed25519 cannot be prehashed, so a larger action cannot be KMS-signed. */
+export const AWS_KMS_MAX_MESSAGE = 4096;
+/** An `ECC_NIST_EDWARDS25519` key with `ED25519_SHA_512` (pure Ed25519, `MessageType: RAW`). Reads the key's public key once. */
+export async function awsKmsEd25519Signer(kms, keyId) {
+    const info = await kms.getPublicKey({ KeyId: keyId });
+    if (info.KeySpec !== "ECC_NIST_EDWARDS25519")
+        throw new SignerVerificationError(`KMS key ${keyId} is ${info.KeySpec}, not ECC_NIST_EDWARDS25519`);
+    const raw = spkiEd25519(info.PublicKey);
+    return Object.freeze({
+        algorithm: "Ed25519",
+        get publicKey() { return Uint8Array.from(raw); },
+        async sign(message) {
+            if (message.length > AWS_KMS_MAX_MESSAGE)
+                throw new SignerVerificationError(`message is ${message.length} bytes; AWS KMS signs at most ${AWS_KMS_MAX_MESSAGE}`);
+            const { Signature } = await kms.sign({ KeyId: keyId, Message: message, MessageType: "RAW", SigningAlgorithm: "ED25519_SHA_512" });
+            if (!(Signature instanceof Uint8Array))
+                throw new SignerVerificationError("KMS returned no signature");
+            return Signature;
+        },
+    });
+}
+const CKM_EDDSA = 0x1057, CKA_EC_POINT = 0x181;
+/**
+ * A `CKK_EC_EDWARDS` key pair on a PKCS#11 v3 token (YubiHSM 2, Luna 7.7+, SoftHSM 2.6+), signed with `CKM_EDDSA` and no
+ * parameters: pure Ed25519. The public key comes from the public object's `CKA_EC_POINT`.
+ */
+export function pkcs11Ed25519Signer(pkcs11, session, privateKey, publicKeyObject) {
+    const point = pkcs11.C_GetAttributeValue(session, publicKeyObject, [{ type: CKA_EC_POINT }])[0]?.value;
+    // PKCS#11 3.0 wraps the point in a DER OCTET STRING; some tokens return it bare.
+    const raw = rawKey(point?.length === 34 && point[0] === 0x04 && point[1] === 0x20 ? point.subarray(2) : point);
+    return Object.freeze({
+        algorithm: "Ed25519",
+        get publicKey() { return Uint8Array.from(raw); },
+        async sign(message) {
+            // ponytail: init+sign run synchronously back to back, so concurrent calls never interleave on one session.
+            pkcs11.C_SignInit(session, { mechanism: CKM_EDDSA }, privateKey);
+            return Uint8Array.from(pkcs11.C_Sign(session, Buffer.from(message), Buffer.alloc(64)));
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arxiumlabs/sdk",
-  "version": "0.9.0",
+  "version": "0.13.1",
   "description": "Arxium TypeScript SDK and arx CLI",
   "type": "module",
   "private": false,
@@ -25,7 +25,8 @@
   "files": [
     "dist",
     "!dist/*.test.*",
-    "README.md"
+    "README.md",
+    "SIGNERS.md"
   ],
   "engines": {
     "node": ">=20"
@@ -34,7 +35,7 @@
     "build": "tsc -p tsconfig.json",
     "check:package": "node scripts/release-check.mjs",
     "test:release": "node --test scripts/release-check.test.mjs",
-    "test": "npm run build && node dist/codec.test.js && node dist/policy.test.js && node dist/cli.test.js"
+    "test": "npm run build && node dist/signer.test.js && node dist/codec.test.js && node dist/policy.test.js && node dist/cli.test.js"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",