@arxiumlabs/sdk 0.0.0-stage → 0.5.0

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;
+    }
+}

package/dist/rpc.d.ts

@@ -0,0 +1,65 @@
+import { type SignedAction } from "./actions.js";
+import { type AccountPolicy } from "./policy.js";
+export type RpcOptions = {
+    rpc: string;
+    token?: string;
+    fetch?: typeof globalThis.fetch;
+};
+export type ActionStatus = {
+    status: "pending";
+} | {
+    status: "confirmed";
+    height: number;
+    block_hash: string;
+    sender: string;
+    nonce: number;
+} | {
+    status: "dropped";
+    reason: string;
+} | {
+    status: "unknown";
+};
+export type SendActionOptions = {
+    privateKey: CryptoKey;
+    sender: string;
+    payload: Uint8Array;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    finalized?: boolean;
+};
+export declare class RpcError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class ArxiumRpc {
+    readonly rpc: string;
+    private readonly token?;
+    private readonly requestFetch;
+    constructor(options: RpcOptions);
+    private request;
+    private genesis?;
+    /** This chain's genesis hash, fetched once per client; every signature binds it. */
+    genesisHash(): Promise<Uint8Array>;
+    status<T = Record<string, unknown>>(): Promise<T>;
+    account<T = Record<string, unknown>>(address: string): Promise<T>;
+    stake<T = Record<string, unknown>>(address: string): Promise<T>;
+    stakes<T = Record<string, unknown>[]>(address: string): Promise<T>;
+    blsKey<T = Record<string, unknown>>(address: string): Promise<T>;
+    submit(action: SignedAction): Promise<unknown>;
+    action(signature: string): Promise<ActionStatus>;
+    blocks<T = unknown>(from: number, to: number): Promise<T>;
+    block<T = unknown>(height: number): Promise<T>;
+    blockByHash<T = unknown>(hash: string): Promise<T>;
+    validators<T = unknown>(): Promise<T>;
+    finality<T = unknown>(): Promise<T>;
+    search<T = unknown>(query: string): Promise<T>;
+    minStake<T = unknown>(): Promise<T>;
+    actionFee<T = unknown>(): Promise<T>;
+    sendAction(options: SendActionOptions): Promise<{
+        action: SignedAction;
+        status: ActionStatus;
+    }>;
+}
+/** Stateful witnesses require the policy at the action's pre-state, not today's
+ * policy. This checks cryptography; circuit execution proves limits and scope. */
+export declare function verifySignedAction(action: SignedAction, genesis: Uint8Array, preStatePolicy?: AccountPolicy): Promise<boolean>;

package/dist/rpc.js

@@ -0,0 +1,74 @@
+import { signAction, signingBytes, submitBody, verifyMultisig } from "./actions.js";
+import { decodeAddress, isMultisigAddress } from "./bech32.js";
+import { asBuffer, fromHex } from "./bincode.js";
+import { verifyPolicySignature } from "./policy.js";
+export class RpcError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class ArxiumRpc {
+    rpc;
+    token;
+    requestFetch;
+    constructor(options) { this.rpc = options.rpc.replace(/\/+$/, ""); this.token = options.token; this.requestFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init)); } // browsers and Workers throw "Illegal invocation" if fetch is called with `this` = ArxiumRpc
+    async request(path, init) { const response = await this.requestFetch(`${this.rpc}${path}`, { ...init, headers: { ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}), ...init?.headers } }); const text = await response.text(); if (!response.ok)
+        throw new RpcError(response.status, text || `${response.status} ${response.statusText}`); return text ? JSON.parse(text) : undefined; }
+    genesis;
+    /** This chain's genesis hash, fetched once per client; every signature binds it. */
+    genesisHash() { return this.genesis ??= this.request("/genesis-hash").then((r) => fromHex(r.genesis_hash.replace(/^0x/, "")), (e) => { this.genesis = undefined; throw e; }); }
+    status() { return this.request("/status"); }
+    account(address) { return this.request(`/accounts/${encodeURIComponent(address)}`); }
+    stake(address) { return this.request(`/accounts/${encodeURIComponent(address)}/stake`); }
+    stakes(address) { return this.request(`/accounts/${encodeURIComponent(address)}/stakes`); }
+    blsKey(address) { return this.request(`/accounts/${encodeURIComponent(address)}/bls-key`); }
+    submit(action) { return this.request("/actions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(action) }); }
+    async action(signature) { try {
+        return await this.request(`/actions/${encodeURIComponent(signature)}`);
+    }
+    catch (error) {
+        if (error instanceof RpcError && error.status === 404)
+            return { status: "unknown" };
+        throw error;
+    } }
+    blocks(from, to) { return this.request(`/blocks?from=${from}&to=${to}`); }
+    block(height) { return this.request(`/blocks/${height}`); }
+    blockByHash(hash) { return this.request(`/blocks/by-hash/${encodeURIComponent(hash)}`); }
+    validators() { return this.request("/validators"); }
+    finality() { return this.request("/finality"); }
+    search(query) { return this.request(`/search?q=${encodeURIComponent(query)}`); }
+    minStake() { return this.request("/min-stake"); }
+    actionFee() { return this.request("/action-fee"); }
+    async sendAction(options) { const account = await this.account(options.sender).catch((error) => { if (error instanceof RpcError && error.status === 404)
+        return { nonce: 0 }; throw error; }); const signature = await signAction(options.privateKey, await this.genesisHash(), options.sender, account.nonce, options.payload); const action = submitBody(options.sender, account.nonce, signature, options.payload); await this.submit(action); const deadline = Date.now() + (options.timeoutMs ?? 120_000); while (Date.now() < deadline) {
+        const status = await this.action(signature);
+        if (status.status === "dropped")
+            throw new Error(`action dropped: ${status.reason}`);
+        if (status.status === "confirmed") {
+            if (!options.finalized)
+                return { action, status };
+            const block = await this.block(status.height);
+            if (block.finalized)
+                return { action, status };
+        }
+        await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 1_000));
+    } throw new Error("timed out waiting for action"); }
+}
+/** Stateful witnesses require the policy at the action's pre-state, not today's
+ * policy. This checks cryptography; circuit execution proves limits and scope. */
+export async function verifySignedAction(action, genesis, preStatePolicy) {
+    try {
+        const message = signingBytes(genesis, action.sender, action.nonce, Uint8Array.from(action.payload));
+        if (action.signature.length > 128 && /^a7(00|01|02)/.test(action.signature))
+            return !!preStatePolicy && await verifyPolicySignature(preStatePolicy, action.signature, message) !== null;
+        if (isMultisigAddress(action.sender))
+            return await verifyMultisig(action.sender, action.signature, message);
+        const key = await crypto.subtle.importKey("raw", asBuffer(decodeAddress(action.sender)), "Ed25519", false, ["verify"]);
+        return crypto.subtle.verify("Ed25519", key, asBuffer(fromHex(action.signature)), asBuffer(message));
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@arxiumlabs/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Arxium TypeScript SDK and arx CLI",
+  "type": "module",
+  "private": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Arxium-Protocol/arxium.git",
+    "directory": "sdk/ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "arx": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/*.test.*",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check:package": "node scripts/release-check.mjs",
+    "test:release": "node --test scripts/release-check.test.mjs",
+    "test": "npm run build && node dist/codec.test.js && node dist/policy.test.js && node dist/cli.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}