@arxiumlabs/sdk 0.0.0-stage → 0.4.0

package/dist/bincode.js

@@ -0,0 +1,77 @@
+const U8_MAX = 250n;
+const U16_MAX = 0xffffn;
+const U32_MAX = 0xffffffffn;
+const U64_MAX = 0xffffffffffffffffn;
+const U128_MAX = (1n << 128n) - 1n;
+/** Canonical bincode 2.x `config::standard()` writer for Arxium action payloads. */
+export class Writer {
+    chunks = [];
+    bytes() { return Uint8Array.from(this.chunks); }
+    raw(bytes) { for (const byte of bytes)
+        this.chunks.push(byte); return this; } // not push(...bytes): spreading overflows the call stack past ~100k bytes
+    u8(value) {
+        if (!Number.isInteger(value) || value < 0 || value > 255)
+            throw new RangeError(`u8 out of range: ${value}`);
+        this.chunks.push(value);
+        return this;
+    }
+    bool(value) { return this.u8(value ? 1 : 0); }
+    varint(value) {
+        const v = BigInt(value);
+        if (v < 0n || v > U128_MAX)
+            throw new RangeError(`varint out of range: ${v}`);
+        if (v <= U8_MAX)
+            return this.u8(Number(v));
+        if (v <= U16_MAX)
+            return this.u8(0xfb).le(v, 2);
+        if (v <= U32_MAX)
+            return this.u8(0xfc).le(v, 4);
+        if (v <= U64_MAX)
+            return this.u8(0xfd).le(v, 8);
+        return this.u8(0xfe).le(v, 16);
+    }
+    le(value, width) { for (let i = 0; i < width; i++) {
+        this.chunks.push(Number(value >> BigInt(i * 8) & 0xffn));
+    } return this; }
+    string(value) { const bytes = new TextEncoder().encode(value); return this.varint(bytes.length).raw(bytes); }
+    option(value, write) { if (value == null)
+        return this.u8(0); this.u8(1); write(this, value); return this; }
+    vec(values, write) { this.varint(values.length); for (const value of values)
+        write(this, value); return 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 const asBuffer = (bytes) => new Uint8Array(bytes).buffer;
+export function toHex(bytes) { return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); }
+export function fromHex(hex) { if (hex.length % 2 || !/^[0-9a-f]*$/i.test(hex))
+    throw new Error("invalid hex"); return Uint8Array.from(hex.match(/../g)?.map((byte) => Number.parseInt(byte, 16)) ?? []); }
+/** Reads what `Writer` writes. Pair every decode with a re-encode check (see `decodePayload`) rather than trusting it to reject non-canonical input. */
+export class Reader {
+    data;
+    at = 0;
+    constructor(data) {
+        this.data = data;
+    }
+    u8() { if (this.at >= this.data.length)
+        throw new RangeError("unexpected end of payload"); return this.data[this.at++]; }
+    bool() { const value = this.u8(); if (value > 1)
+        throw new RangeError(`invalid bool: ${value}`); return value === 1; }
+    varint() {
+        const tag = this.u8();
+        if (tag <= 250)
+            return BigInt(tag);
+        const width = { 0xfb: 2, 0xfc: 4, 0xfd: 8, 0xfe: 16 }[tag];
+        if (!width)
+            throw new RangeError(`invalid varint tag: ${tag}`);
+        let value = 0n;
+        for (let i = 0; i < width; i++)
+            value |= BigInt(this.u8()) << BigInt(i * 8);
+        return value;
+    }
+    length() { const len = this.varint(); if (len > BigInt(this.data.length - this.at))
+        throw new RangeError("length past end of payload"); return Number(len); }
+    string() { const len = this.length(), text = new TextDecoder("utf-8", { fatal: true }).decode(this.data.subarray(this.at, this.at + len)); this.at += len; return text; }
+    option(read) { return this.bool() ? read(this) : null; }
+    vec(read) { return Array.from({ length: this.length() }, () => read(this)); }
+    done() { if (this.at !== this.data.length)
+        throw new RangeError("trailing bytes after payload"); }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { stdin as input, stderr, stdout } from "node:process";
+import { createPrivateKey, createPublicKey } from "node:crypto";
+import { ArxiumRpc, RpcError, encodeApplyAttestor, encodeBlockAttestor, encodeExecuteProposal, encodeSubmitProposal, encodeVoteProposal, encodeAuthorizeOperator, encodeGrantAttestation, encodeIssueAsset, encodeRegisterAsset, encodeTransferAsset, encodeJoinValidator, encodeLeaveValidator, encodeRegisterBlsKey, encodeRevokeAttestation, encodeRevokeOperator, encodeStake, encodeTransfer, encodeUnstake, generateKey, isKeyFile, signAction, submitBody, unlockKey, verifyKeyFile, verifySignedAction, wrapPkcs8, encodeAddress, toHex, toKeyFile, PKCS8_ED25519_PREFIX, assemblePolicySignature, decodePayload, encodePayload, fromHex, multisigAddress, multisigSignature, signingBytes, asBuffer, } from "./index.js";
+class UsageError extends Error {
+}
+function output(value, json) { stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : typeof value === "string" ? `${value}\n` : `${JSON.stringify(value, null, 2)}\n`); }
+function parseGlobals(args) { let rpc = process.env.ARX_RPC ?? "http://127.0.0.1:8080", token = process.env.ARX_TOKEN, key = process.env.ARX_KEY, json = false, nonce; const rest = []; for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--rpc")
+        rpc = args[++i] ?? throwUsage("--rpc needs a value");
+    else if (arg === "--token")
+        token = args[++i] ?? throwUsage("--token needs a value");
+    else if (arg === "--key")
+        key = args[++i] ?? throwUsage("--key needs a value");
+    else if (arg === "--json")
+        json = true;
+    else if (arg === "--nonce") {
+        const value = args[++i] ?? "";
+        if (!/^\d+$/.test(value))
+            throwUsage("--nonce needs a non-negative integer");
+        nonce = Number(value);
+    }
+    else
+        rest.push(arg);
+} return { globals: { rpc, token, key, json, nonce }, args: rest }; }
+function throwUsage(message) { throw new UsageError(message); }
+// Only stdin must be a terminal: the prompt goes to stderr, so `arx send … | jq` still prompts.
+function prompt(label) { return new Promise((resolve) => { stderr.write(label); input.setRawMode(true); input.resume(); let value = ""; const onData = (chunk) => { for (const char of chunk.toString("utf8")) {
+    if (char === "\r" || char === "\n") {
+        input.off("data", onData);
+        input.setRawMode(false);
+        input.pause();
+        stderr.write("\n");
+        resolve(value);
+        return;
+    }
+    if (char === "\u0003")
+        process.exit(130);
+    if (char === "\u007f" || char === "\b")
+        value = value.slice(0, -1);
+    else
+        value += char;
+} }; input.on("data", onData); }); }
+async function passphrase(confirm = false) { if (process.env.ARX_PASSPHRASE)
+    return process.env.ARX_PASSPHRASE; if (!input.isTTY)
+    throw new UsageError("no passphrase: set ARX_PASSPHRASE or run interactively"); const value = await prompt("Passphrase: "); if (confirm && await prompt("Confirm passphrase: ") !== value)
+    throw new UsageError("passphrases do not match"); return value; }
+async function readKeyFile(path) { if (!path)
+    throw new UsageError("--key or ARX_KEY is required"); const parsed = JSON.parse(await readFile(path, "utf8")); if (!isKeyFile(parsed))
+    throw new UsageError("invalid key file (or its address does not match its publicKey)"); return parsed; }
+async function loadKey(path) { const file = await readKeyFile(path); try {
+    const privateKey = await unlockKey(file, await passphrase());
+    await verifyKeyFile(file, privateKey);
+    return { file, privateKey };
+}
+catch (error) {
+    if (error instanceof UsageError)
+        throw error;
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+} }
+async function readStdin() { const chunks = []; for await (const chunk of input)
+    chunks.push(Buffer.from(chunk)); return Buffer.concat(chunks).toString("utf8"); }
+function payload(action, args) { const topics = (list) => list ? list.split(",").map((topic) => ["kyc", "aml", "accredited", "jurisdiction"].includes(topic) ? topic : throwUsage(`unknown topic: ${topic} (kyc, aml, accredited, jurisdiction)`)) : []; const amount = (index) => { const value = args[index]; if (!value || !/^\d+$/.test(value))
+    throwUsage("amount must be an integer IUM value"); return BigInt(value); }; switch (action) {
+    case "apply-attestor": return encodeApplyAttestor(args[0] ?? throwUsage("apply-attestor needs <name> <owner,owner,...> <threshold> <evidence-hash> <evidence-uri>"), (args[1] ?? throwUsage("missing owners")).split(","), Number(args[2] ?? throwUsage("missing threshold")), args[3] ?? throwUsage("missing evidence hash"), args[4] ?? throwUsage("missing evidence uri"));
+    case "block-attestor": return encodeBlockAttestor();
+    case "propose-add-attestor": return encodeSubmitProposal({ kind: "addAttestor", attestor: args[0] ?? throwUsage("propose-add-attestor needs <attestor> <name> <owner,owner,...> <threshold> <evidence-hash> <evidence-uri> <description>"), name: args[1] ?? throwUsage("missing name"), owners: (args[2] ?? throwUsage("missing owners")).split(","), threshold: Number(args[3] ?? throwUsage("missing threshold")), evidenceHash: args[4] ?? throwUsage("missing evidence hash"), evidenceUri: args[5] ?? throwUsage("missing evidence uri") }, args[6] ?? throwUsage("missing description"));
+    case "propose-remove-attestor":
+    case "propose-unblock-attestor": return encodeSubmitProposal({ kind: action === "propose-remove-attestor" ? "removeAttestor" : "unblockAttestor", attestor: args[0] ?? throwUsage(`${action} needs <attestor> <description>`) }, args[1] ?? throwUsage("missing description"));
+    case "vote": {
+        const id = args[0], choice = args[1];
+        if (!id || !/^\d+$/.test(id) || (choice !== "yes" && choice !== "no"))
+            throwUsage("vote needs <proposal-id> yes|no");
+        return encodeVoteProposal(BigInt(id), choice === "yes");
+    }
+    case "execute-proposal": {
+        const id = args[0];
+        if (!id || !/^\d+$/.test(id))
+            throwUsage("execute-proposal needs <proposal-id>");
+        return encodeExecuteProposal(BigInt(id));
+    }
+    case "transfer": return encodeTransfer(args[0] ?? throwUsage("transfer needs <to> <ium>"), amount(1));
+    case "stake": return encodeStake(args[0] ?? throwUsage("stake needs <validator> <ium>"), amount(1));
+    case "unstake": return encodeUnstake(args[0] ?? throwUsage("unstake needs <validator> <ium>"), amount(1));
+    case "join-validator": return encodeJoinValidator(args[0] ?? throwUsage("join-validator needs <validator> <ium> <bls-pubkey-hex> <bls-pop-hex>"), amount(1), hexArg(args[2]), hexArg(args[3]));
+    case "leave-validator": return encodeLeaveValidator(args[0] ?? throwUsage("leave-validator needs <validator>"));
+    case "register-bls-key": return encodeRegisterBlsKey(args[0] ?? throwUsage("register-bls-key needs <validator> <pubkey-hex> <pop-hex>"), hexArg(args[1]), hexArg(args[2]));
+    case "authorize-operator": return encodeAuthorizeOperator(args[0] ?? throwUsage("authorize-operator needs <address>"));
+    case "revoke-operator": return encodeRevokeOperator();
+    case "grant-attestation": return encodeGrantAttestation(args[0] ?? throwUsage("grant-attestation needs <subject> <hash> [topics] [jurisdiction]"), args[1] ?? throwUsage("grant-attestation needs <subject> <hash>"), topics(args[2]), args[3] ?? null);
+    case "revoke-attestation": return encodeRevokeAttestation(args[0] ?? throwUsage("revoke-attestation needs <subject>"));
+    case "register-asset": {
+        const [assetId, symbol, name, decimals] = args;
+        if (!assetId || !symbol || !name || !/^\d+$/.test(decimals ?? ""))
+            throwUsage("register-asset needs <asset-id> <symbol> <name> <decimals> [topics] [jurisdictions]");
+        return encodeRegisterAsset(assetId, false, { asset_class: "other", decimals: Number(decimals), required_claims: topics(args[4]), allowed_jurisdictions: args[5] ? args[5].split(",") : null, max_supply: null, metadata_uri: null, symbol, name });
+    }
+    case "issue-asset": return encodeIssueAsset(args[0] ?? throwUsage("issue-asset needs <asset-ref> <amount>"), amount(1));
+    case "transfer-asset": return encodeTransferAsset(args[0] ?? throwUsage("transfer-asset needs <asset-ref> <to> <amount>"), args[1] ?? throwUsage("transfer-asset needs <asset-ref> <to> <amount>"), amount(2));
+    default: throwUsage(`unsupported action: ${action}`);
+} }
+function hexArg(value) { if (!value || !/^[0-9a-f]*$/i.test(value) || value.length % 2)
+    throwUsage("expected even-length hex"); return Uint8Array.from(value.match(/../g)?.map((byte) => Number.parseInt(byte, 16)) ?? []); }
+async function main() {
+    const { globals, args } = parseGlobals(process.argv.slice(2));
+    const [command, ...rest] = args;
+    if (command === "--version") {
+        const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+        output(`arx ${pkg.version}`, false);
+        return;
+    }
+    if (!command)
+        throwUsage("use: arx keys|sign|submit|send|query|verify");
+    if (command === "keys") {
+        const [operation, ...keyArgs] = rest;
+        if (operation === "new") {
+            const pass = await passphrase(true), generated = await generateKey(pass), file = toKeyFile(generated), destination = keyArgs[0] ?? `arxium-devnet-key-${generated.address.slice(4, 12)}.json`;
+            await writeFile(destination, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+            output({ path: destination, address: file.address, publicKey: file.publicKey, network: file.network }, globals.json);
+            return;
+        }
+        if (operation === "import" && keyArgs[0] === "--file") {
+            const source = keyArgs[1] ?? throwUsage("keys import --file needs a path"), parsed = await readKeyFile(source);
+            const destination = keyArgs[2] ?? basename(source);
+            await writeFile(destination, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+            output({ path: destination, address: parsed.address }, globals.json);
+            return;
+        }
+        if (operation === "import") {
+            if (input.isTTY)
+                throwUsage("pipe a 32-byte hex seed to `arx keys import`; seeds are never command arguments");
+            const seed = (await readStdin()).trim();
+            if (!/^[0-9a-f]{64}$/i.test(seed))
+                throwUsage("seed must be 32 bytes of hex");
+            const pkcs8 = Buffer.from(PKCS8_ED25519_PREFIX + seed, "hex"), publicJwk = createPublicKey(createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" })).export({ format: "jwk" });
+            if (!publicJwk.x)
+                throw new Error("could not derive public key from seed");
+            const publicKey = Buffer.from(publicJwk.x, "base64url"), address = encodeAddress(publicKey), file = toKeyFile({ address, publicKey: toHex(publicKey), blob: await wrapPkcs8(pkcs8, await passphrase(true)) }), destination = keyArgs[0] ?? `arxium-devnet-key-${address.slice(4, 12)}.json`;
+            await writeFile(destination, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+            output({ path: destination, address }, globals.json);
+            return;
+        }
+        if (operation === "show") {
+            const file = await readKeyFile(globals.key);
+            output({ address: file.address, publicKey: file.publicKey, network: file.network }, globals.json);
+            return;
+        }
+        throwUsage("use: arx keys new|import [destination]|import --file <file>|show");
+    }
+    const rpc = new ArxiumRpc(globals);
+    if (command === "multisig") {
+        const [operation, source, ...extra] = rest;
+        if (operation === "address") {
+            output(await multisigAddress(Number(source), extra.map(fromHex)), globals.json);
+            return;
+        }
+        if (!source)
+            throwUsage("multisig build|sign|combine|link needs a JSON file");
+        const value = JSON.parse(await readFile(source, "utf8"));
+        if (operation === "build") {
+            const members = value.members.map(m => m.toLowerCase()).sort();
+            const derived = await multisigAddress(value.threshold, members.map(fromHex));
+            const sender = value.sender ?? derived;
+            if (!value.mode && sender !== derived)
+                throwUsage("legacy policy does not derive sender");
+            if (value.mode && !["owner", "guardian"].includes(value.mode))
+                throwUsage("invalid policy mode");
+            const nonce = globals.nonce ?? value.nonce ?? await rpc.account(sender).then(a => a.nonce);
+            if (!Number.isSafeInteger(nonce) || nonce < 0)
+                throwUsage("nonce must be a safe non-negative integer");
+            output({ genesis: toHex(await rpc.genesisHash()), sender, nonce, threshold: value.threshold, members, payload: toHex(encodePayload(value.payload)), sigs: [], ...(value.mode ? { mode: value.mode } : {}) }, true);
+            return;
+        }
+        const r = value;
+        if (!Number.isSafeInteger(r.nonce) || r.nonce < 0 || (r.mode !== undefined && !["owner", "guardian"].includes(r.mode)))
+            throwUsage("invalid co-sign request");
+        const encoded = fromHex(r.payload), decoded = decodePayload(encoded), derived = await multisigAddress(r.threshold, r.members.map(fromHex));
+        if (r.mode) {
+            const current = await rpc.account(r.sender);
+            const p = r.mode === "owner" ? current.programmable?.policy.owners : current.programmable?.policy.recovery?.guardians;
+            if (!p || await multisigAddress(p.threshold, p.members.map(m => Uint8Array.from(m))) !== derived)
+                throwUsage("request is not authorized by the current account policy");
+        }
+        else if (r.sender !== derived)
+            throwUsage("policy does not derive sender");
+        const genesis = fromHex(r.genesis);
+        if (toHex(genesis) !== toHex(await rpc.genesisHash()))
+            throwUsage("request was built for a different chain than --rpc");
+        const message = signingBytes(genesis, r.sender, r.nonce, encoded);
+        const seen = new Set();
+        for (const [member, sig] of r.sigs) {
+            if (!r.members.includes(member) || seen.has(member))
+                throwUsage("duplicate or non-member signature");
+            seen.add(member);
+            const key = await crypto.subtle.importKey("raw", asBuffer(fromHex(member)), "Ed25519", false, ["verify"]);
+            if (!await crypto.subtle.verify("Ed25519", key, asBuffer(fromHex(sig)), asBuffer(message)))
+                throwUsage("invalid member signature");
+        }
+        if (operation === "sign") {
+            const { file, privateKey } = await loadKey(globals.key);
+            if (!r.members.includes(file.publicKey) || seen.has(file.publicKey))
+                throwUsage("key is not an unsigned member");
+            stderr.write(`Signing ${JSON.stringify(decoded)} for ${r.sender} at nonce ${r.nonce}\n`);
+            output({ ...r, sigs: [...r.sigs, [file.publicKey, await signAction(privateKey, genesis, r.sender, r.nonce, encoded)]] }, true);
+            return;
+        }
+        if (operation === "combine") {
+            if (r.sigs.length !== r.threshold)
+                throwUsage("need exactly threshold signatures");
+            const sig = r.mode ? assemblePolicySignature(r.mode, { threshold: r.threshold, members: r.members }, r.sigs) : multisigSignature(r.threshold, r.members.map(fromHex), r.sigs.map(([m, s]) => [fromHex(m), s]));
+            output(submitBody(r.sender, r.nonce, sig, encoded), true);
+            return;
+        }
+        if (operation === "link") {
+            output(`${extra[0] ?? throwUsage("link needs the Console co-sign page URL")}#${Buffer.from(JSON.stringify(r)).toString("base64url")}`, globals.json);
+            return;
+        }
+        throwUsage("use: arx multisig address|build|sign|combine|link");
+    }
+    if (command === "sign" || command === "send") {
+        const action = rest[0] ?? throwUsage(`${command} needs an action`), { file, privateKey } = await loadKey(globals.key), encoded = payload(action, rest.slice(1));
+        if (command === "sign") {
+            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; });
+            output(submitBody(file.address, nonce, await signAction(privateKey, await rpc.genesisHash(), file.address, nonce, encoded), encoded), true);
+            return;
+        }
+        output(await rpc.sendAction({ privateKey, sender: file.address, payload: encoded, finalized: true }), globals.json);
+        return;
+    }
+    if (command === "submit") {
+        const source = rest[0] ?? throwUsage("submit needs <file|->"), body = JSON.parse(source === "-" ? await readStdin() : await readFile(source, "utf8"));
+        output(await rpc.submit(body) ?? { submitted: body.signature }, globals.json);
+        return;
+    }
+    if (command === "verify") {
+        const signature = rest[0] ?? throwUsage("verify needs <signature>"), status = await rpc.action(signature);
+        if (status.status !== "confirmed")
+            throw new Error(`action is ${status.status}`);
+        const block = await rpc.block(status.height);
+        const action = block.actions?.find((item) => item.signature === signature);
+        let preStatePolicy;
+        if (signature.length > 128 && /^a7(00|01|02)/.test(signature)) {
+            if (rest[1] !== "--policy" || !rest[2])
+                throwUsage("stateful verification needs --policy <JSON file> containing the proven pre-action policy");
+            preStatePolicy = JSON.parse(await readFile(rest[2], "utf8"));
+        }
+        if (!block.finalized || !action || !await verifySignedAction(action, await rpc.genesisHash(), preStatePolicy))
+            throw new Error("action is not finalized with a valid signature");
+        output({ signature, finalized: true, signatureValid: true, height: status.height }, globals.json);
+        return;
+    }
+    if (command === "query") {
+        const [operation, value] = rest;
+        const result = operation === "status" ? await rpc.status() : operation === "account" ? await rpc.account(value ?? throwUsage("account needs an address")) : operation === "block" ? (/^\d+$/.test(value ?? "") ? await rpc.block(Number(value)) : await rpc.blockByHash(value ?? throwUsage("block needs a height or hash"))) : operation === "action" ? await rpc.action(value ?? throwUsage("action needs a signature")) : operation === "validators" ? await rpc.validators() : operation === "finality" ? await rpc.finality() : operation === "search" ? await rpc.search(value ?? throwUsage("search needs a query")) : throwUsage("use: arx query status|account|block|action|validators|finality|search");
+        output(result, 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/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./actions.js";
+export * from "./amounts.js";
+export * from "./bech32.js";
+export * from "./bincode.js";
+export * from "./keys.js";
+export * from "./rpc.js";
+export * from "./policy.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./actions.js";
+export * from "./amounts.js";
+export * from "./bech32.js";
+export * from "./bincode.js";
+export * from "./keys.js";
+export * from "./rpc.js";
+export * from "./policy.js";

package/dist/keys.d.ts

@@ -0,0 +1,37 @@
+export declare const PBKDF2_ITERATIONS = 600000;
+export declare const PKCS8_ED25519_PREFIX = "302e020100300506032b657004220420";
+export type KeyBlob = {
+    version: 1;
+    kdf: "PBKDF2-SHA256";
+    iterations: number;
+    salt: string;
+    iv: string;
+    ciphertext: string;
+};
+/** The exact JSON document emitted by Console's `exportKey`. `network` is display metadata, not a signing domain. */
+export type KeyFile = KeyBlob & {
+    address: string;
+    publicKey: string;
+    network: string;
+};
+export type GeneratedKey = {
+    address: string;
+    publicKey: string;
+    privateKey: CryptoKey;
+    blob: KeyBlob;
+};
+export declare function generateKey(passphrase: string): Promise<GeneratedKey>;
+export declare function wrapPkcs8(pkcs8: Uint8Array, passphrase: string): Promise<KeyBlob>;
+/** Also checks `address` is the bech32 of `publicKey`, so a tampered file is rejected before any passphrase is asked for. */
+export declare function isKeyFile(value: unknown): value is KeyFile;
+/** The Console "Export key" / `arx keys new` document. Field order matches Console's historical export. */
+export declare function toKeyFile(key: {
+    address: string;
+    publicKey: string;
+    blob: KeyBlob;
+}, network?: string): KeyFile;
+export declare function unlockKey(blob: KeyBlob, passphrase: string): Promise<CryptoKey>;
+export declare function rewrapKey(blob: KeyBlob, oldPassphrase: string, newPassphrase: string): Promise<KeyBlob>;
+/** Confirms the decrypted private key belongs to the public address declared by the export. */
+export declare function verifyKeyFile(file: KeyFile, privateKey: CryptoKey): Promise<void>;
+export declare function importSeed(seedHex: string): Promise<CryptoKey>;

package/dist/keys.js

@@ -0,0 +1,36 @@
+import { encodeAddress } from "./bech32.js";
+import { asBuffer, fromHex, toHex } from "./bincode.js";
+export const PBKDF2_ITERATIONS = 600_000;
+export const PKCS8_ED25519_PREFIX = "302e020100300506032b657004220420";
+const encodeBase64 = (bytes) => typeof btoa === "function" ? btoa(String.fromCharCode(...bytes)) : Buffer.from(bytes).toString("base64");
+const decodeBase64 = (value) => typeof atob === "function" ? Uint8Array.from(atob(value), (char) => char.charCodeAt(0)) : new Uint8Array(Buffer.from(value, "base64"));
+async function wrappingKey(passphrase, salt, iterations) { const material = await crypto.subtle.importKey("raw", asBuffer(new TextEncoder().encode(passphrase)), "PBKDF2", false, ["deriveKey"]); return crypto.subtle.deriveKey({ name: "PBKDF2", hash: "SHA-256", salt: asBuffer(salt), iterations }, material, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]); }
+export async function generateKey(passphrase) { const pair = await crypto.subtle.generateKey("Ed25519", true, ["sign", "verify"]), publicRaw = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey)), pkcs8 = new Uint8Array(await crypto.subtle.exportKey("pkcs8", pair.privateKey)), salt = crypto.getRandomValues(new Uint8Array(16)), iv = crypto.getRandomValues(new Uint8Array(12)); const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, await wrappingKey(passphrase, salt, PBKDF2_ITERATIONS), pkcs8)); const privateKey = await crypto.subtle.importKey("pkcs8", pkcs8, "Ed25519", false, ["sign"]); pkcs8.fill(0); return { address: encodeAddress(publicRaw), publicKey: toHex(publicRaw), privateKey, blob: { version: 1, kdf: "PBKDF2-SHA256", iterations: PBKDF2_ITERATIONS, salt: encodeBase64(salt), iv: encodeBase64(iv), ciphertext: encodeBase64(ciphertext) } }; }
+export async function wrapPkcs8(pkcs8, passphrase) { const salt = crypto.getRandomValues(new Uint8Array(16)), iv = crypto.getRandomValues(new Uint8Array(12)); const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, await wrappingKey(passphrase, salt, PBKDF2_ITERATIONS), asBuffer(pkcs8))); return { version: 1, kdf: "PBKDF2-SHA256", iterations: PBKDF2_ITERATIONS, salt: encodeBase64(salt), iv: encodeBase64(iv), ciphertext: encodeBase64(ciphertext) }; }
+/** Also checks `address` is the bech32 of `publicKey`, so a tampered file is rejected before any passphrase is asked for. */
+export function isKeyFile(value) { const key = value; return !!key && key.version === 1 && key.kdf === "PBKDF2-SHA256" && typeof key.address === "string" && typeof key.publicKey === "string" && /^[0-9a-f]{64}$/i.test(key.publicKey) && encodeAddress(fromHex(key.publicKey)) === key.address && typeof key.network === "string" && typeof key.iterations === "number" && Number.isInteger(key.iterations) && key.iterations >= PBKDF2_ITERATIONS && [key.salt, key.iv, key.ciphertext].every((field) => typeof field === "string" && field.length > 0); }
+/** The Console "Export key" / `arx keys new` document. Field order matches Console's historical export. */
+export function toKeyFile(key, network = "arx-devnet") { return { address: key.address, publicKey: key.publicKey, ...key.blob, network }; }
+export async function unlockKey(blob, passphrase) { try {
+    const pkcs8 = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: asBuffer(decodeBase64(blob.iv)) }, await wrappingKey(passphrase, decodeBase64(blob.salt), blob.iterations), asBuffer(decodeBase64(blob.ciphertext))));
+    const key = await crypto.subtle.importKey("pkcs8", asBuffer(pkcs8), "Ed25519", false, ["sign"]);
+    pkcs8.fill(0);
+    return key;
+}
+catch {
+    throw new Error("wrong passphrase");
+} }
+export async function rewrapKey(blob, oldPassphrase, newPassphrase) { try {
+    const pkcs8 = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: asBuffer(decodeBase64(blob.iv)) }, await wrappingKey(oldPassphrase, decodeBase64(blob.salt), blob.iterations), asBuffer(decodeBase64(blob.ciphertext))));
+    const wrapped = await wrapPkcs8(pkcs8, newPassphrase);
+    pkcs8.fill(0);
+    return wrapped;
+}
+catch {
+    throw new Error("wrong passphrase");
+} }
+/** Confirms the decrypted private key belongs to the public address declared by the export. */
+export async function verifyKeyFile(file, privateKey) { const message = new TextEncoder().encode("arxium key file verification"); const signature = await crypto.subtle.sign("Ed25519", privateKey, asBuffer(message)); const publicKey = await crypto.subtle.importKey("raw", asBuffer(fromHex(file.publicKey)), "Ed25519", false, ["verify"]); if (encodeAddress(fromHex(file.publicKey)) !== file.address || !await crypto.subtle.verify("Ed25519", publicKey, signature, asBuffer(message)))
+    throw new Error("key file address does not match decrypted key"); }
+export async function importSeed(seedHex) { if (!/^[0-9a-f]{64}$/i.test(seedHex))
+    throw new Error("seed must be 32 bytes of hex"); return crypto.subtle.importKey("pkcs8", asBuffer(fromHex(PKCS8_ED25519_PREFIX + seedHex)), "Ed25519", false, ["sign"]); }

package/dist/policy.d.ts

@@ -0,0 +1,53 @@
+import { Reader } from "./bincode.js";
+export declare const ACCOUNT_POLICY_ACTION = 40;
+export declare const POLICY_VARIANT: {
+    readonly setAccountPolicy: 0;
+    readonly rotateAccountMembers: 1;
+    readonly addSessionKey: 2;
+    readonly revokeSessionKey: 3;
+    readonly startAccountRecovery: 4;
+    readonly cancelAccountRecovery: 5;
+    readonly executeAccountRecovery: 6;
+};
+export type ThresholdPolicy = {
+    threshold: number;
+    members: string[];
+};
+export type SpendAsset = "native" | {
+    asset: string;
+};
+export type SpendingLimit = {
+    asset: SpendAsset;
+    periodBlocks: string;
+    amount: string;
+};
+export type SessionKey = {
+    publicKey: string;
+    expiresAt: string;
+    asset: SpendAsset;
+    allowance: string;
+    recipients: string[];
+};
+export type AccountPolicy = {
+    owners: ThresholdPolicy;
+    limits: SpendingLimit[];
+    recipients: string[] | null;
+    sessions: SessionKey[];
+    recovery: {
+        guardians: ThresholdPolicy;
+        delayBlocks: string;
+    } | null;
+};
+export type PolicyMode = "owner" | "session" | "guardian";
+export declare function encodeAccountPolicy(name: keyof typeof POLICY_VARIANT, input: Record<string, any>): Uint8Array;
+export declare function readAccountPolicy(r: Reader): {
+    name: keyof typeof POLICY_VARIANT;
+    input: Record<string, any>;
+};
+/** Sign the stable account's envelope, not the signer's personal address. */
+export declare function signPolicyMember(privateKey: CryptoKey, genesis: Uint8Array, sender: string, nonce: number, payload: Uint8Array): Promise<string>;
+export declare function assemblePolicySignature(mode: Exclude<PolicyMode, "session">, policy: ThresholdPolicy, signatures: [string, string][]): string;
+export declare function assembleSessionSignature(publicKey: string, signature: string): string;
+/** Cryptographic verification only; use proven policy at the action's pre-state.
+ * The runtime also checks capability scope, expiry, nonce and spend counters. */
+export declare function verifyPolicySignature(policy: AccountPolicy, signature: string, message: Uint8Array): Promise<PolicyMode | null>;

package/dist/policy.js

@@ -0,0 +1,116 @@
+import { Writer, asBuffer, fromHex, toHex } from "./bincode.js";
+import { multisigAddress, multisigSignature, signAction, verifyMultisig } from "./actions.js";
+export const ACCOUNT_POLICY_ACTION = 40;
+export const POLICY_VARIANT = { setAccountPolicy: 0, rotateAccountMembers: 1, addSessionKey: 2, revokeSessionKey: 3, startAccountRecovery: 4, cancelAccountRecovery: 5, executeAccountRecovery: 6 };
+const MODE = { owner: 0, session: 1, guardian: 2 };
+function key(hex) { const bytes = fromHex(hex); if (bytes.length !== 32)
+    throw new Error("public key must be 32 bytes"); return bytes; }
+function bounded(value, bits) { const n = BigInt(value); if (n < 0n || n >= 1n << BigInt(bits))
+    throw new Error(`value outside u${bits}`); return n; }
+function threshold(w, p) {
+    if (!Number.isInteger(p.threshold) || p.threshold < 1 || p.threshold > p.members.length || p.members.length > 16 || p.members.some((m, i) => i > 0 && p.members[i - 1] >= m))
+        throw new Error("threshold policy must have 1..16 sorted unique members");
+    w.u8(p.threshold).vec(p.members, (ww, m) => ww.raw(key(m)));
+}
+function asset(w, a) { if (a === "native")
+    w.varint(0);
+else
+    w.varint(1).string(a.asset); }
+function recipients(w, list) { if (list.length > 64 || list.some((a, i) => i > 0 && list[i - 1] >= a))
+    throw new Error("recipients must be bounded, unique and sorted"); w.vec(list, (ww, a) => ww.string(a)); }
+function session(w, s) { w.raw(key(s.publicKey)).varint(bounded(s.expiresAt, 64)); asset(w, s.asset); w.varint(bounded(s.allowance, 128)); recipients(w, s.recipients); }
+function policy(w, p) {
+    threshold(w, p.owners);
+    if (p.limits.length > 16 || p.sessions.length > 16)
+        throw new Error("policy exceeds bounded menu");
+    if (p.sessions.length && !p.limits.some(l => l.asset === "native"))
+        throw new Error("session keys require a native fee budget");
+    w.vec(p.limits, (ww, l) => { asset(ww, l.asset); if (BigInt(l.periodBlocks) === 0n)
+        throw new Error("period must be positive"); ww.varint(bounded(l.periodBlocks, 64)).varint(bounded(l.amount, 128)); });
+    w.option(p.recipients, recipients).vec(p.sessions, session).option(p.recovery, (ww, r) => { threshold(ww, r.guardians); if (BigInt(r.delayBlocks) === 0n)
+        throw new Error("recovery delay must be positive"); ww.varint(bounded(r.delayBlocks, 64)); });
+}
+export function encodeAccountPolicy(name, input) {
+    const w = new Writer().varint(ACCOUNT_POLICY_ACTION).varint(POLICY_VARIANT[name]);
+    switch (name) {
+        case "setAccountPolicy":
+            policy(w, input.policy);
+            break;
+        case "rotateAccountMembers":
+        case "startAccountRecovery":
+            threshold(w, input.owners);
+            break;
+        case "addSessionKey":
+            session(w, input.session);
+            break;
+        case "revokeSessionKey":
+            w.raw(key(input.publicKey));
+            break;
+        case "cancelAccountRecovery":
+        case "executeAccountRecovery": break;
+    }
+    return w.bytes();
+}
+function readKey(r) { return toHex(Uint8Array.from({ length: 32 }, () => r.u8())); }
+function readThreshold(r) { return { threshold: r.u8(), members: r.vec(readKey) }; }
+function readAsset(r) { const tag = r.varint(); if (tag === 0n)
+    return "native"; if (tag === 1n)
+    return { asset: r.string() }; throw new Error("unknown spend asset"); }
+function readSession(r) { return { publicKey: readKey(r), expiresAt: r.varint().toString(), asset: readAsset(r), allowance: r.varint().toString(), recipients: r.vec(rr => rr.string()) }; }
+export function readAccountPolicy(r) {
+    const variant = Number(r.varint()), name = Object.keys(POLICY_VARIANT).find(n => POLICY_VARIANT[n] === variant);
+    if (!name)
+        throw new Error("unknown account policy action");
+    let input;
+    switch (name) {
+        case "setAccountPolicy":
+            input = { policy: { owners: readThreshold(r), limits: r.vec(rr => ({ asset: readAsset(rr), periodBlocks: rr.varint().toString(), amount: rr.varint().toString() })), recipients: r.option(rr => rr.vec(v => v.string())), sessions: r.vec(readSession), recovery: r.option(rr => ({ guardians: readThreshold(rr), delayBlocks: rr.varint().toString() })) } };
+            break;
+        case "rotateAccountMembers":
+        case "startAccountRecovery":
+            input = { owners: readThreshold(r) };
+            break;
+        case "addSessionKey":
+            input = { session: readSession(r) };
+            break;
+        case "revokeSessionKey":
+            input = { publicKey: readKey(r) };
+            break;
+        default: input = {};
+    }
+    return { name, input };
+}
+/** Sign the stable account's envelope, not the signer's personal address. */
+export async function signPolicyMember(privateKey, genesis, sender, nonce, payload) { return signAction(privateKey, genesis, sender, nonce, payload); }
+export function assemblePolicySignature(mode, policy, signatures) {
+    if (signatures.length !== policy.threshold || new Set(signatures.map(([m]) => m)).size !== signatures.length || signatures.some(([, s]) => fromHex(s).length !== 64))
+        throw new Error("need exactly threshold distinct member signatures");
+    return `a7${MODE[mode].toString(16).padStart(2, "0")}${multisigSignature(policy.threshold, policy.members.map(key), signatures.map(([m, s]) => [key(m), s]))}`;
+}
+export function assembleSessionSignature(publicKey, signature) { if (fromHex(signature).length !== 64)
+    throw new Error("signature must be 64 bytes"); return `a701${toHex(key(publicKey))}${signature}`; }
+/** Cryptographic verification only; use proven policy at the action's pre-state.
+ * The runtime also checks capability scope, expiry, nonce and spend counters. */
+export async function verifyPolicySignature(policy, signature, message) {
+    try {
+        const bytes = fromHex(signature);
+        if (bytes[0] !== 0xa7)
+            return null;
+        if (bytes[1] === 1) {
+            if (bytes.length !== 98)
+                return null;
+            const pk = bytes.slice(2, 34);
+            if (!policy.sessions.some(s => s.publicKey === toHex(pk)))
+                return null;
+            const cryptoKey = await crypto.subtle.importKey("raw", asBuffer(pk), "Ed25519", false, ["verify"]);
+            return await crypto.subtle.verify("Ed25519", cryptoKey, asBuffer(bytes.slice(34)), asBuffer(message)) ? "session" : null;
+        }
+        const p = bytes[1] === 0 ? policy.owners : bytes[1] === 2 ? policy.recovery?.guardians : null;
+        if (!p)
+            return null;
+        return await verifyMultisig(await multisigAddress(p.threshold, p.members.map(key)), toHex(bytes.slice(2)), message) ? (bytes[1] === 0 ? "owner" : "guardian") : null;
+    }
+    catch {
+        return null;
+    }
+}