@arxiumlabs/sdk 0.0.0-stage → 0.4.0

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,41 @@
 {
   "name": "@arxiumlabs/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.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",
+    "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"
+  }
+}