suprafx-agent-sdk 0.3.1

package/dist/src/client.js

@@ -0,0 +1,282 @@
+/**
+ * Thin HTTP client over the SupraFX dApp's public endpoints.
+ *
+ * Wraps the read + write surfaces documented in
+ * `docs/INTEGRATING-AGENTS.md`. No auth required for reads; writes
+ * carry their own ed25519 signature inside the BCS envelope (see
+ * `./signer.ts`).
+ *
+ * Pure fetch — no global state, no caching beyond the chain-info
+ * lookup. Safe to use from the MCP server, from a cookbook script,
+ * or as a library inside a larger agent codebase.
+ */
+const DEFAULT_BASE = "https://suprafx.ai";
+/** An error carrying a stable category and the action that clears it. */
+export class SupraFxError extends Error {
+    code;
+    action;
+    status;
+    detail;
+    constructor(code, action, message, opts = {}) {
+        super(message);
+        this.name = "SupraFxError";
+        this.code = code;
+        this.action = action;
+        this.status = opts.status;
+        this.detail = opts.detail;
+    }
+    /** The JSON body an MCP handler returns on failure. */
+    toEnvelope() {
+        return {
+            error: this.code,
+            action: this.action,
+            message: this.message,
+            ...(this.status != null ? { status: this.status } : {}),
+            ...(this.detail !== undefined ? { detail: this.detail } : {}),
+        };
+    }
+}
+/** Map an HTTP status onto the stable category + its clearing action. */
+function classifyStatus(status) {
+    if (status === 401 || status === 403)
+        return { code: "auth", action: "authenticate" };
+    if (status === 404)
+        return { code: "not_found", action: "fix_input" };
+    if (status === 429)
+        return { code: "rate_limit", action: "backoff" };
+    if (status >= 400 && status < 500)
+        return { code: "validation", action: "fix_input" };
+    return { code: "api", action: "retry" };
+}
+export class SupraFxClient {
+    baseUrl;
+    timeoutMs;
+    cachedChainInfo = null;
+    cachedClockOffset = null;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+        this.timeoutMs = opts.timeoutMs ?? 15000;
+    }
+    // ─── Reads ─────────────────────────────────────────────────────
+    /**
+     * Fetch the canonical chain-id hash and validator threshold.
+     * Cached for the lifetime of the client — these values are
+     * constant per chain genesis.
+     */
+    async getChainInfo() {
+        if (this.cachedChainInfo)
+            return this.cachedChainInfo;
+        const j = await this.get("/api/council/chain-info");
+        if (!j.chainIdHashHex) {
+            throw new Error("getChainInfo: response missing chainIdHashHex");
+        }
+        this.cachedChainInfo = j;
+        return j;
+    }
+    /**
+     * Difference between the venue's HTTP clock and the local clock.
+     * Best-effort only: expiry calculation must remain available when the
+     * header or endpoint is unavailable.
+     */
+    async getVenueClockOffsetMs() {
+        const now = Date.now();
+        if (this.cachedClockOffset && now < this.cachedClockOffset.expiresAtMs) {
+            return this.cachedClockOffset.offsetMs;
+        }
+        let offsetMs = 0;
+        try {
+            const ctrl = new AbortController();
+            const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+            try {
+                const r = await fetch(this.baseUrl + "/api/council/chain-info", {
+                    signal: ctrl.signal,
+                    headers: { accept: "application/json" },
+                });
+                const serverDateMs = Date.parse(r.headers.get("date") ?? "");
+                if (Number.isFinite(serverDateMs)) {
+                    offsetMs = serverDateMs - Date.now();
+                }
+            }
+            finally {
+                clearTimeout(t);
+            }
+        }
+        catch {
+            // Clock alignment is advisory; never prevent a trade on failure.
+        }
+        this.cachedClockOffset = {
+            offsetMs,
+            expiresAtMs: Date.now() + 5 * 60_000,
+        };
+        return offsetMs;
+    }
+    /** Current committed batch height. Useful for `expires_at_batch` math. */
+    async getCurrentBatch() {
+        const j = await this.get("/api/council/current-batch");
+        return j.current_batch;
+    }
+    /**
+     * Next strictly-monotonic sequence number this address must use
+     * for its next signed event. `0` for a brand-new account.
+     */
+    async getSequenceNumber(address) {
+        const a = address.startsWith("0x") ? address : "0x" + address;
+        const j = await this.get("/api/council/sequence-number?address=" + encodeURIComponent(a));
+        return j.next_sequence_number;
+    }
+    /** All supported assets with canonical chain id + decimals. */
+    async listAssets() {
+        const j = await this.get("/api/assets");
+        return j.assets ?? [];
+    }
+    /**
+     * Available + locked balances for `address` (a master Supra account).
+     * Returns an empty array if the address has no balance rows.
+     */
+    async getBalances(address) {
+        const a = address.startsWith("0x") ? address : "0x" + address;
+        const j = await this.get("/api/platform/balances?address=" + encodeURIComponent(a));
+        return j.balances ?? [];
+    }
+    /**
+     * Status of one deposit claim, keyed on the chain and the L1 transaction
+     * hash. Answers "still crediting, or failed?" — see `state`, `stale` and
+     * `next_step`. An unknown transaction is `found:false`, not an error: a
+     * deposit made without recording a claim still credits through the
+     * validator bridge, it is just not visible here.
+     */
+    async getDepositStatus(chain, txHash) {
+        return await this.get("/api/platform/deposit?chain=" + encodeURIComponent(chain) +
+            "&tx_hash=" + encodeURIComponent(txHash));
+    }
+    /** Every deposit claim recorded by `address` (a master account), newest first. */
+    async listDepositClaims(address, limit = 20) {
+        const a = address.startsWith("0x") ? address : "0x" + address;
+        const j = await this.get("/api/platform/deposit?address=" + encodeURIComponent(a) +
+            "&limit=" + encodeURIComponent(String(limit)));
+        return {
+            address: j.address ?? a,
+            claims: j.claims ?? [],
+            counts: j.counts
+                ?? { pending: 0, stale: 0, credited: 0, rejected: 0, expired: 0, reconciled_from_ledger: 0 },
+            truncated: j.truncated ?? false,
+        };
+    }
+    /** On-chain policy currently associated with a delegate address. */
+    async getDelegatePolicy(address) {
+        const a = address.startsWith("0x") ? address : "0x" + address;
+        const j = await this.get("/api/delegate-policy?delegate=" + encodeURIComponent(a));
+        return j.policy ?? null;
+    }
+    /**
+     * Public orderbook: open RFQs. Filters as documented in
+     * `INTEGRATING-AGENTS.md` §2.
+     */
+    async getOrderbook(filters = {}) {
+        const qs = new URLSearchParams({ scope: "platform" });
+        if (filters.pair)
+            qs.set("pair", filters.pair);
+        if (filters.status)
+            qs.set("status", filters.status);
+        if (filters.limit)
+            qs.set("limit", String(filters.limit));
+        // RESPONSE SHAPE. `/api/suprafx/rfqs` answers
+        // `{ success, data, count, hasMore, ... }` — the rows are under
+        // `data`, NOT `rfqs`. Reading only `rfqs` made this silently return
+        // an EMPTY array for every call (verified live 2026-09-14: the API
+        // returned 3 matched RFQs, this method returned 0). That blinded
+        // `get_orderbook` and made `place_quote` unable to find any parent
+        // RFQ. Accept `data` first, keep `rfqs` as a fallback so an older or
+        // proxied deployment still works.
+        const j = await this.get("/api/suprafx/rfqs?" + qs.toString());
+        return j.data ?? j.rfqs ?? [];
+    }
+    /**
+     * Venue oracle quote for `pair` (e.g. `"ETH/USDC"`), with the quote's
+     * age computed at read time. Quote against THIS, never an external
+     * price — and never against a stale one (see `ORACLE_STALE_MS`).
+     */
+    async getOracle(pair) {
+        const j = await this.get("/api/oracle?pair=" + encodeURIComponent(pair));
+        const updatedAt = typeof j.updatedAt === "number" ? j.updatedAt : null;
+        return {
+            pair: j.pair ?? pair,
+            conversionRate: typeof j.conversionRate === "number" ? j.conversionRate : null,
+            updatedAt,
+            ageMs: updatedAt != null ? Date.now() - updatedAt : null,
+        };
+    }
+    // ─── Writes ────────────────────────────────────────────────────
+    async submitEnvelope(endpoint, bodyFieldName, envelopeBcsHex) {
+        return await this.post("/api/council/" + endpoint, {
+            [bodyFieldName]: envelopeBcsHex,
+        });
+    }
+    // ─── Plumbing ──────────────────────────────────────────────────
+    async get(path) {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            let r;
+            try {
+                r = await fetch(this.baseUrl + path, {
+                    signal: ctrl.signal,
+                    headers: { accept: "application/json" },
+                });
+            }
+            catch (e) {
+                // An AbortError here is our own timeout firing, not a caller cancel.
+                if (ctrl.signal.aborted) {
+                    throw new SupraFxError("timeout", "retry", `GET ${path} timed out after ${this.timeoutMs}ms`);
+                }
+                throw new SupraFxError("network", "retry", `GET ${path} failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            if (!r.ok) {
+                const { code, action } = classifyStatus(r.status);
+                const body = await r.text().catch(() => "");
+                throw new SupraFxError(code, action, `GET ${path} → ${r.status} ${r.statusText}`, { status: r.status, detail: body.slice(0, 400) || undefined });
+            }
+            return (await r.json());
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    async post(path, body) {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            let r;
+            try {
+                r = await fetch(this.baseUrl + path, {
+                    method: "POST",
+                    signal: ctrl.signal,
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(body),
+                });
+            }
+            catch (e) {
+                if (ctrl.signal.aborted) {
+                    throw new SupraFxError("timeout", "report", `POST ${path} timed out after ${this.timeoutMs}ms — the write may ` +
+                        `or may not have reached the venue; READ STATE BACK before retrying`);
+                }
+                throw new SupraFxError("network", "report", `POST ${path} failed: ${e instanceof Error ? e.message : String(e)} — ` +
+                    `the write may or may not have landed; READ STATE BACK before retrying`);
+            }
+            if (r.status === 429) {
+                throw new SupraFxError("rate_limit", "backoff", `POST ${path} → 429`, {
+                    status: 429,
+                });
+            }
+            // Truth signal is body.ok per INTEGRATING-AGENTS §2 — Cloudflare
+            // may strip 5xx bodies, so we don't trust status alone. Parse
+            // both 2xx and 4xx bodies and let the caller inspect the code.
+            const j = (await r.json().catch(() => ({})));
+            return j;
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/src/derive-ids.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Asset + pair ID derivation for council `SubmitRfq` events.
+ *
+ * The chain treats asset_id and pair_id as opaque 32-byte values —
+ * it doesn't validate the derivation, just routes events by ID. So
+ * the only invariant is **consistency across calls**: SupraFX must
+ * derive the same ID for the same (chain, token) tuple every time,
+ * across all users + sessions, otherwise orderbook state diverges
+ * (two users referring to "ETH on Sepolia" via different IDs would
+ * fail to match).
+ *
+ * ## Convention (V2 — chain-canonical)
+ *
+ * `asset_id = BLAKE3-keyed(key=BLAKE3("SUPRAFX-ASSET-V1"),
+ *                          message=[chain_id_len_u8, ...chain_id_utf8,
+ *                                   ...token_address_bytes])`
+ * `pair_id  = BLAKE3("suprafx-pair-v1\n" + base_asset_hex
+ *                                        + "\n" + quote_asset_hex)`
+ *
+ * V2 mirrors `council_bridge::identity::asset_id_from_chain_and_token`
+ * byte-for-byte. Required because the bridge credits L1 deposits
+ * under THIS asset_id; if the dApp's RFQ uses a different derivation
+ * (V1), the chain says "no balance" and the validator gate rejects
+ * the trade. The migration is one-time — open RFQs from V1 days
+ * remain in the legacy table but are unmatchable on the new orderbook.
+ *
+ * ## Token address registry
+ *
+ * The chain stores asset_id under `(canonicalChainId, tokenBytes)`,
+ * where tokenBytes is:
+ *   - `[0u8; 20]` for the native EVM coin (`EVM_NATIVE_TOKEN_BYTES`)
+ *   - the 20-byte ERC-20 contract address otherwise
+ *   - `[0u8; 32]` for native Supra
+ * The dApp UI thinks in `(uiChain, symbol)` strings. The registry
+ * below bridges the two; new tokens MUST be added here AND in the
+ * validator's `bridge.eth_chains[*].asset_decimals` operator config
+ * before they can be deposited.
+ */
+/**
+ * Chain-canonical asset_id. Mirrors
+ * `council_bridge::identity::asset_id_from_chain_and_token`.
+ *
+ *   asset_id = blake3-keyed(
+ *     key = blake3("SUPRAFX-ASSET-V1"),
+ *     msg = [chain_id.len() as u8, ...chain_id_utf8, ...token_bytes],
+ *   )
+ *
+ * `chainId` is the canonical bridge chain identifier (`eth-sepolia`,
+ * `supra-testnet`, etc). `tokenBytes` is the L1 token address — 20
+ * bytes for EVM (zero for native), 32 bytes for Supra (zero for native).
+ */
+export declare function assetIdFromChainAndToken(chainId: string, tokenBytes: Uint8Array): Uint8Array;
+/**
+ * Bridge the SHORT chain ids the venue's `/api/assets` returns
+ * (`"ethereum"`, `"supra"`, `"sepolia"`) to the CANONICAL bridge chain
+ * ids the on-chain AssetId derivation is keyed on (`"eth-mainnet"`,
+ * `"supra-mainnet"`, `"eth-sepolia"`).
+ *
+ * WHY THIS EXISTS (verified against live `https://suprafx.ai/api/assets`
+ * on 2026-09-14). An agent that reads `list_assets` and passes the
+ * `chain_id` it got back straight into a trade — the obvious thing to do
+ * — used to derive the WRONG AssetId, two different ways, both silent:
+ *
+ *   - `"ethereum"` is in no registry key, so `deriveAssetId` fell through
+ *     to the legacy V1 hash and produced a phantom id the validator gate
+ *     rejects.
+ *   - `"supra"` WAS a registry key — pointing at `supra-testnet`. So a
+ *     mainnet SUPRA trade derived the TESTNET SUPRA asset: a well-formed
+ *     id for the wrong chain. Worse than a phantom, because nothing about
+ *     it looks wrong.
+ *
+ * Canonical ids map to themselves, so this is an identity for every
+ * caller that already passes the long form.
+ */
+export declare function canonicalChain(chain: string): string;
+/**
+ * Derive a 32-byte AssetId from a UI-friendly `(chain, symbol)` tuple.
+ *
+ * Resolves through TOKEN_REGISTRY to the canonical
+ * `(chainId, tokenBytes)` then hashes per
+ * [`assetIdFromChainAndToken`]. For tokens not in the registry
+ * (test/explorer use cases), falls back to the V1 hash so
+ * downstream code that doesn't actually trade these IDs keeps
+ * working — but the return value is NOT what the chain expects
+ * for the unregistered token, so RFQ submission against it WILL
+ * fail at the validator gate.
+ */
+export declare function deriveAssetId(chain: string, symbol: string): Uint8Array;
+/**
+ * Like `deriveAssetId`, but returns `null` for a `(chain, symbol)`
+ * NOT in `TOKEN_REGISTRY` — instead of silently falling through to
+ * the V1 hash.
+ *
+ * Callers that need the REAL chain-canonical AssetId — delegate
+ * `asset_caps` (Option B), deposit crediting — MUST use this and
+ * treat `null` as "not a tradeable asset yet". Embedding a V1 hash in
+ * a delegate's cap map authorizes a phantom id, and the moment the
+ * asset is later registered every old session's map goes stale.
+ */
+export declare function registeredAssetId(chain: string, symbol: string): Uint8Array | null;
+/**
+ * Derive a 32-byte PairId from base + quote AssetId values.
+ *
+ * Order matters: `(ETH, USDC)` produces a different pair than
+ * `(USDC, ETH)`. SubmitRfq's `base_asset` is what the user gives
+ * up; `quote_asset` is what they receive.
+ */
+export declare function derivePairId(baseAssetId: Uint8Array, quoteAssetId: Uint8Array): Uint8Array;
+/**
+ * Convenience: one-call `(chain, symbol)` × 2 → 32-byte PairId.
+ */
+export declare function derivePairIdFromTokens(baseChain: string, baseSymbol: string, quoteChain: string, quoteSymbol: string): Uint8Array;