@carbonx3/cx3.js 0.1.1 → 0.3.0

package/src/provider.js

@@ -1,34 +1,118 @@
 "use strict";
 
 const { Cx3Error, Cx3HttpError, Cx3TxError } = require("./errors");
-const { readCallValue, sleep, normalizeAddress, walletApiKeyMode } = require("./utils");
+const { readCallValue, sleep, normalizeAddress, walletApiKeyMode, toJsonSafe } = require("./utils");
 const { Contract } = require("./contract");
+const { normalizeGenesisHash } = require("./digest");
 
 /**
  * Green Chain HTTP provider.
  *
- * Talks to `{baseUrl}/api/v1/...` — never CX3VM directly.
+ * Apps sign in to the CX3Api gateway with an OAuth2 client (`clientId` + `clientSecret`, created in
+ * CX3WebUI → Settings → API → Applications): the provider gets a one-hour access token at
+ * `POST /oauth/token`, sends it as `Authorization: Bearer`, and renews it before it expires. A wallet
+ * API key (`cx3wk_…`, `X-Api-Key`) still works during the move to applications. Without one of the
+ * two the provider refuses to start (CREDENTIALS_REQUIRED): no app development without credentials.
+ * Gateway routes: `/contracts/:address/call`, `/contracts/:address/send`, `/wallet/...`, …
+ * `devNode: true` talks to a development node that runs without auth (`/api/v1`). The SDK never sends
+ * HTTP Basic (the nodes' internal login). Never talks to CX3VM directly.
  */
+
+// node route → CX3Api route (the gateway forwards the same body to the node)
+function gatewayPath(path, body) {
+    const addr = body && (body.contractAddress || body.address);
+    if (path === "/contract/call" && addr) return `/contracts/${encodeURIComponent(addr)}/call`;
+    if (path === "/contract/send" && addr) return `/contracts/${encodeURIComponent(addr)}/send`;
+    if (path === "/deployContract") return "/contracts/deploy";
+    if (path === "/getBalanceAndNonce") return "/wallet/getBalanceAndNonce";
+    if (path === "/getNonce") return "/wallet/getNonce";
+    if (path === "/getContracts") return "/contracts/list";
+    const info = /^\/contract\/([^/]+)$/.exec(path);
+    if (info) return `/contracts/${info[1]}`;
+    return path;
+}
+
+function appendQuery(url, query) {
+    if (!query) return url;
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
+    }
+    const s = qs.toString();
+    return s ? url + (url.includes("?") ? "&" : "?") + s : url;
+}
+
+// a private token moves only between its owner and its authorized wallets (the templates' guards)
+const PRIVATE_GUARDED_METHODS = new Set(["transfer", "transferFrom", "mint"]);
+
+// a bool view answers true / false on CX3JS and "true" / "false" on CX3WASM
+function boolVerdict(v) {
+    if (v === true || v === 1 || v === "1" || v === "true") return true;
+    if (v === false || v === 0 || v === "0" || v === "false") return false;
+    return null;
+}
+
+// credentials come only from clientId / clientSecret or apiKey, never from an extra header
+function withoutCredentialHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers || {})) {
+        if (!/^(authorization|x-api-key)$/i.test(k)) out[k] = v;
+    }
+    return out;
+}
+
+const CLIENT_ID_RE = /^cx3app_[a-f0-9]{24}$/i;
+const CLIENT_SECRET_RE = /^cx3sec_[a-f0-9]{64}$/i;
+
 class Cx3Provider {
     /**
-     * @param {string} baseUrl  Green Chain node URL (`CX3_NODE_URL`)
+     * @param {string} baseUrl  CX3Api gateway URL (`CX3_NODE_URL`, e.g. https://cx3api.carbonx3.com), or a development node with `devNode`
      * @param {object} [options]
-     * @param {string} [options.apiPrefix="/api/v1"]
-     * @param {{ user: string, pass: string }} [options.auth] Basic auth (legacy node → Green Chain)
-     * @param {string} [options.apiKey] Wallet API key (`cx3wk_…`) for CX3Api `X-Api-Key`
-     * @param {Record<string,string>} [options.headers] Extra headers
+     * @param {string} [options.clientId]  OAuth2 client id (`cx3app_…`; env CX3_CLIENT_ID)
+     * @param {string} [options.clientSecret]  OAuth2 client secret (`cx3sec_…`; env CX3_CLIENT_SECRET)
+     * @param {string|string[]} [options.scope]  ask for fewer scopes than the app has ("read", "write", "deploy")
+     * @param {string} [options.apiKey]  wallet API key (`cx3wk_…`; env CX3_API_KEY), until apps move to OAuth2
+     * @param {boolean} [options.devNode]  a development node without auth (`/api/v1`), no credentials
+     * @param {string} [options.apiPrefix] ("" on the gateway, "/api/v1" on a development node)
+     * @param {Record<string,string>} [options.headers] Extra headers (Authorization / X-Api-Key are dropped)
      * @param {typeof fetch} [options.fetch] Custom fetch (tests)
      * @param {number} [options.timeoutMs]
      */
     constructor(baseUrl, options = {}) {
         if (!baseUrl) throw new Cx3Error("Cx3Provider requires baseUrl (CX3_NODE_URL)", "NO_BASE_URL");
         this.baseUrl = String(baseUrl).replace(/\/$/, "");
-        this.apiPrefix = options.apiPrefix != null ? options.apiPrefix : "/api/v1";
-        this.auth = options.auth || null;
-        this.apiKey = String(options.apiKey != null ? options.apiKey : (process.env.CX3_API_KEY || "")).trim();
-        this.extraHeaders = options.headers || {};
+        if (options.auth != null) {
+            throw new Cx3Error(
+                "HTTP Basic is the nodes' internal login and is not sent by the SDK: create an application in CX3WebUI (Settings → API) and pass clientId / clientSecret",
+                "BASIC_AUTH_UNSUPPORTED"
+            );
+        }
+        const env = (name) => (process.env[name] || "").trim();
+        this.clientId = String(options.clientId != null ? options.clientId : env("CX3_CLIENT_ID")).trim();
+        this._clientSecret = String(options.clientSecret != null ? options.clientSecret : env("CX3_CLIENT_SECRET")).trim();
+        this.scope = Array.isArray(options.scope) ? options.scope.join(" ") : String(options.scope || "").trim();
+        this.apiKey = String(options.apiKey != null ? options.apiKey : env("CX3_API_KEY")).trim();
+        this.devNode = options.devNode === true;
+        this.oauth = !!(this.clientId || this._clientSecret);
+        if (this.oauth && (!CLIENT_ID_RE.test(this.clientId) || !CLIENT_SECRET_RE.test(this._clientSecret))) {
+            throw new Cx3Error("clientId must be cx3app_… and clientSecret cx3sec_… (CX3WebUI → Settings → API → Applications)", "INVALID_CLIENT_CREDENTIALS");
+        }
+        const hasKey = walletApiKeyMode(this.apiKey) !== "public";
+        if (!this.oauth && !hasKey && !this.devNode) {
+            throw new Cx3Error(
+                "App credentials required: create an application in CX3WebUI (Settings → API → Applications) and pass clientId / clientSecret (or set CX3_CLIENT_ID / CX3_CLIENT_SECRET)",
+                "CREDENTIALS_REQUIRED"
+            );
+        }
+        this.gateway = !this.devNode;
+        this.apiPrefix = options.apiPrefix != null ? options.apiPrefix : (this.gateway ? "" : "/api/v1");
+        this.extraHeaders = withoutCredentialHeaders(options.headers);
         this.fetchImpl = options.fetch || globalThis.fetch;
         this.timeoutMs = options.timeoutMs || 60000;
+        this._token = null;          // { value, refreshAt, scope }
+        this._tokenPromise = null;
+        // token address → { private, owners } from its registry record (set at deploy)
+        this._tokenRecords = new Map();
         if (typeof this.fetchImpl !== "function") {
             throw new Cx3Error("fetch is not available — use Node 18+ or pass options.fetch", "NO_FETCH");
         }
@@ -38,24 +122,51 @@ class Cx3Provider {
         return walletApiKeyMode(this.apiKey);
     }
 
-    _headers() {
+    /** "oauth" | "apiKey" | "devNode" */
+    get authMode() {
+        if (this.devNode && !this.oauth && walletApiKeyMode(this.apiKey) === "public") return "devNode";
+        return this.oauth ? "oauth" : "apiKey";
+    }
+
+    /**
+     * The current access token (OAuth2 apps): fetched once, shared by concurrent calls, renewed a
+     * minute before it expires or when the gateway says it is no longer valid.
+     */
+    async getAccessToken(force = false) {
+        if (!this.oauth) return null;
+        if (!force && this._token && Date.now() < this._token.refreshAt) return this._token.value;
+        if (!this._tokenPromise) {
+            this._tokenPromise = this._fetchToken().finally(() => { this._tokenPromise = null; });
+        }
+        return this._tokenPromise;
+    }
+
+    async _fetchToken() {
+        const form = new URLSearchParams({ grant_type: "client_credentials", client_id: this.clientId, client_secret: this._clientSecret });
+        if (this.scope) form.set("scope", this.scope);
+        const { res, json } = await this._fetchJson(`${this.baseUrl}/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+            body: form.toString()
+        });
+        if (!res.ok || !json || !json.access_token) {
+            const code = (json && json.error) || "OAUTH_TOKEN_FAILED";
+            throw new Cx3HttpError((json && json.error_description) || code, res.status, { ...(json || {}), error: code });
+        }
+        const ttl = Number(json.expires_in) > 0 ? Number(json.expires_in) : 3600;
+        this._token = { value: json.access_token, refreshAt: Date.now() + Math.max(30, ttl - 60) * 1000, scope: json.scope || "" };
+        return this._token.value;
+    }
+
+    async _headers(forceToken = false) {
         const headers = {
             "Content-Type": "application/json",
             ...this.extraHeaders
         };
-        if (/^cx3wk_[a-f0-9]{48}$/i.test(this.apiKey)) {
+        if (this.oauth) {
+            headers.Authorization = `Bearer ${await this.getAccessToken(forceToken)}`;
+        } else if (/^cx3wk_[a-f0-9]{48}$/i.test(this.apiKey)) {
             headers["X-Api-Key"] = this.apiKey;
-            return headers;
-        }
-        if (this.auth && this.auth.user && this.auth.pass) {
-            const token = Buffer.from(`${this.auth.user}:${this.auth.pass}`).toString("base64");
-            headers.Authorization = `Basic ${token}`;
-        } else {
-            const user = process.env.CX3_INTERNAL_AUTH_USER;
-            const pass = process.env.CX3_INTERNAL_AUTH_PASS;
-            if (user && pass) {
-                headers.Authorization = `Basic ${Buffer.from(`${user}:${pass}`).toString("base64")}`;
-            }
         }
         return headers;
     }
@@ -81,56 +192,218 @@ class Cx3Provider {
      * @param {{ method?: string, body?: object, query?: Record<string,string|number> }} [opts]
      */
     async request(path, opts = {}) {
-        if (this.apiKeyMode === "invalid") {
+        if (!this.oauth && this.apiKeyMode === "invalid") {
             throw new Cx3Error("api_key_required", "api_key_required");
         }
         const method = opts.method || "GET";
-        let url = `${this.baseUrl}${this.apiPrefix}${path.startsWith("/") ? path : `/${path}`}`;
-        if (opts.query) {
-            const qs = new URLSearchParams();
-            for (const [k, v] of Object.entries(opts.query)) {
-                if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
-            }
-            const s = qs.toString();
-            if (s) url += (url.includes("?") ? "&" : "?") + s;
+        let route = path.startsWith("/") ? path : `/${path}`;
+        if (this.gateway) route = gatewayPath(route, opts.body);
+        const url = appendQuery(`${this.baseUrl}${this.apiPrefix}${route}`, opts.query);
+        const body = opts.body !== undefined ? JSON.stringify(opts.body) : undefined;
+        let { res, json } = await this._fetchJson(url, { method, headers: await this._headers(), body });
+        // the token expired early or the gateway restarted with a new key: one fresh token, one retry
+        if (this.oauth && res.status === 401 && json && json.error === "invalid_token") {
+            ({ res, json } = await this._fetchJson(url, { method, headers: await this._headers(true), body }));
         }
+        if (!res.ok) {
+            throw new Cx3HttpError(
+                json.error || json.message || `HTTP ${res.status}`,
+                res.status,
+                json
+            );
+        }
+        return json;
+    }
 
+    /** fetch with the provider timeout; the body is parsed as JSON ({} when it is not). */
+    async _fetchJson(url, init) {
         const controller = typeof AbortController !== "undefined" ? new AbortController() : null;
         const timer = controller
             ? setTimeout(() => controller.abort(), this.timeoutMs)
             : null;
-
         try {
-            const res = await this.fetchImpl(url, {
-                method,
-                headers: this._headers(),
-                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-                signal: controller ? controller.signal : undefined
-            });
+            const res = await this.fetchImpl(url, { ...init, signal: controller ? controller.signal : undefined });
             const json = await res.json().catch(() => ({}));
-            if (!res.ok) {
-                throw new Cx3HttpError(
-                    json.error || json.message || `HTTP ${res.status}`,
-                    res.status,
-                    json
-                );
-            }
-            return json;
+            return { res, json };
         } finally {
             if (timer) clearTimeout(timer);
         }
     }
 
+    /**
+     * GET on the gateway's public read group (`/dapp/v1{route}`: wallet tokens, activity, CarbonFi
+     * pools, WIT). These are public chain data, read without credentials; a development node has no
+     * such group (DAPP_ONLY).
+     */
+    async _dappRead(route, query) {
+        if (!this.gateway) {
+            throw new Cx3Error(`${route} is served by the CX3Api gateway; a node does not serve it`, "DAPP_ONLY");
+        }
+        const headers = { "Content-Type": "application/json", ...this.extraHeaders };
+        const { res, json } = await this._fetchJson(appendQuery(`${this.baseUrl}/dapp/v1${route}`, query), { method: "GET", headers });
+        if (!res.ok) {
+            throw new Cx3HttpError(json.error || json.message || `HTTP ${res.status}`, res.status, json);
+        }
+        return json;
+    }
+
+    /**
+     * Every registry token with this wallet's balance in one read (`/dapp/v1/accounts/:address/tokens`):
+     * `{ tokens: [{ address, name, symbol, decimals, standard, balance, mine, private?, authorized? }], total, unread }`.
+     * A private token is listed only for its owner, its authorized wallets and its holders.
+     */
+    async getTokens(address) {
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        return this._dappRead(`/accounts/${encodeURIComponent(addr)}/tokens`);
+    }
+
+    /**
+     * Wallet history, newest first, without block rewards (`/dapp/v1/accounts/:address/activity`).
+     * Next page: `{ before: previousPage.nextBefore }`; `nextBefore` is null on the last page.
+     */
+    async getActivity(address, opts = {}) {
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        return this._dappRead(`/accounts/${encodeURIComponent(addr)}/activity`, { limit: opts.limit, before: opts.before });
+    }
+
+    /** CarbonFi pools (`/dapp/v1/dex/pairs`): `{ pairs }`. */
+    async getDexPairs() {
+        return this._dappRead("/dex/pairs");
+    }
+
+    /** A wallet's LP token balance in one CarbonFi pool: `{ balance, totalSupply, lpContractAddress, onChain }`. */
+    async getLpBalance(pairId, address) {
+        const id = String(pairId || "").replace(/^0x/i, "");
+        if (!/^[0-9a-f]{40}$/i.test(id)) throw new Cx3Error("pair id must be 40 hex characters", "INVALID_PAIR_ID");
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        return this._dappRead(`/dex/pairs/${id.toLowerCase()}/lp/${encodeURIComponent(addr)}`);
+    }
+
     async getContractInfo(address) {
         const addr = encodeURIComponent(address);
         return this.request(`/contract/${addr}`);
     }
 
+    /**
+     * Is this a private token (CX3WebUI "Private" deploy, or `Cx3TokenFactory` with
+     * `visibility: "private"`)? Read from its registry record (`metadata.visibility`), which the
+     * deploy sets for good, so the answer is kept per address.
+     */
+    async isPrivateToken(address) {
+        return (await this._tokenRecord(address)).private;
+    }
+
+    async _tokenRecord(address) {
+        const key = normalizeAddress(address);
+        if (this._tokenRecords.has(key)) return this._tokenRecords.get(key);
+        const info = await this.getContractInfo(address);
+        const c = info && info.contract;
+        if (!c || typeof c !== "object") throw new Cx3Error("contract record not available", "CONTRACT_NOT_FOUND");
+        const rec = {
+            private: !!(c.metadata && typeof c.metadata === "object" && c.metadata.visibility === "private"),
+            owners: [c.owner, c.deployer].map(normalizeAddress).filter((a) => /^0x[0-9a-f]{40}$/.test(a))
+        };
+        this._tokenRecords.set(key, rec);
+        return rec;
+    }
+
+    /**
+     * May this wallet hold and move the token? The owner always may (the templates' guards say
+     * `owner || whitelist[a]`); any other wallet when the token's `isWhitelisted` view says so (the
+     * authorized list of a private token, the whitelist of a public one). Meaningful for a token with
+     * such a list: the node answers false for a token without one.
+     * @returns {Promise<boolean|null>} null = the node did not answer
+     */
+    async isTokenAuthorized(token, wallet) {
+        const a = normalizeAddress(wallet);
+        if (!/^0x[0-9a-f]{40}$/.test(a)) throw new Cx3Error("wallet address required", "NO_ADDRESS");
+        try {
+            if ((await this._tokenRecord(token)).owners.includes(a)) return true;
+        } catch (_) {
+            // no registry record: the view decides
+        }
+        try {
+            // the templates name the parameter addr or account; the node takes the one its ABI has
+            const r = await this.call(token, "isWhitelisted", { addr: a, account: a, address: a });
+            if (!r || r.success === false) return null;
+            return boolVerdict(r.value);
+        } catch (_) {
+            return null;
+        }
+    }
+
+    /**
+     * Before a signed transfer / transferFrom / mint of a private token: both ends must be the owner or
+     * authorized wallets, otherwise the block refuses it. Throws PRIVATE_TOKEN_SENDER or
+     * PRIVATE_TOKEN_RECIPIENT; an unreadable record or view gives no verdict (the contract decides).
+     */
+    async checkPrivateTokenSend(contractAddress, method, params, from) {
+        if (!PRIVATE_GUARDED_METHODS.has(method)) return;
+        let priv = false;
+        try {
+            priv = await this.isPrivateToken(contractAddress);
+        } catch (_) {
+            return;
+        }
+        if (!priv) return;
+        const p = params && typeof params === "object" ? params : {};
+        const sender = method === "transferFrom" ? p.from : from;
+        const recipient = p.to != null ? p.to : p.recipient;
+        if (sender && (await this.isTokenAuthorized(contractAddress, sender)) === false) {
+            throw new Cx3Error("The sender is not an authorized wallet of this private token", "PRIVATE_TOKEN_SENDER",
+                { token: contractAddress, wallet: normalizeAddress(sender) });
+        }
+        if (recipient && (await this.isTokenAuthorized(contractAddress, recipient)) === false) {
+            throw new Cx3Error("The recipient is not an authorized wallet of this private token", "PRIVATE_TOKEN_RECIPIENT",
+                { token: contractAddress, wallet: normalizeAddress(recipient) });
+        }
+    }
+
     async getAbi(address) {
         const addr = encodeURIComponent(address);
         return this.request(`/contracts/${addr}/abi`);
     }
 
+    /**
+     * WIT interface of a CX3WASM contract: `{ target, wit }`.
+     * On the gateway: `/dapp/v1/contracts/:address/wit` (404 WIT_NOT_AVAILABLE for CX3JS; the
+     * source itself is never served to apps); a development node: `witCode` of the source record.
+     */
+    async getWit(address) {
+        const addr = encodeURIComponent(address);
+        if (this.gateway) return this._dappRead(`/contracts/${addr}/wit`);
+        const src = await this.request(`/contracts/${addr}/source`);
+        return { success: src.success !== false, address, target: src.target || null, wit: src.witCode || "" };
+    }
+
+    /** Chain head `{ height, hash, timestamp, chainId? }` (chainId from the gateway). */
+    async getStatus() {
+        if (this.gateway) return this._rejectEnvelope(await this._dappRead("/status"));
+        const blk = this._rejectEnvelope(await this.request("/getLastBlock"));
+        return { success: true, height: blk.index != null ? blk.index : blk.height, hash: blk.hash || null, timestamp: blk.timestamp || null };
+    }
+
+    /**
+     * `{ chainId, genesisHash }`: the network identity a native transfer signs over (the gateway's
+     * /status, a development node's /chain/identity). Throws NO_CHAIN_IDENTITY when either is missing.
+     */
+    async getChainIdentity() {
+        // changes only with a new genesis: kept for a minute (one request per signature otherwise)
+        const hit = this._chainIdentity;
+        if (hit && Date.now() - hit.at < 60000) return { ...hit.value };
+        const r = this.gateway
+            ? this._rejectEnvelope(await this._dappRead("/status"))
+            : this._rejectEnvelope(await this.request("/chain/identity"));
+        const chainId = typeof r.chainId === "string" ? r.chainId.trim() : "";
+        const genesisHash = normalizeGenesisHash(r.genesisHash);
+        if (!chainId || !genesisHash) throw new Cx3Error("network identity unavailable", "NO_CHAIN_IDENTITY");
+        this._chainIdentity = { at: Date.now(), value: { chainId, genesisHash } };
+        return { chainId, genesisHash };
+    }
+
     async getEvents(address, typeOrOpts = "", opts = {}) {
         const extra = (typeOrOpts && typeof typeOrOpts === "object")
             ? typeOrOpts
@@ -223,21 +496,23 @@ class Cx3Provider {
     }
 
     /**
-     * Bind / verify the presented cx3wk_ API key against a wallet address.
-     * Empty key → public (any wallet), `{ ok: true, public: true }` — same as dApp whoami.
-     * Valid cx3wk_ → private: GET `/whoami` then CX3Api `/wallet/api-key/bind` on 404.
+     * Check that this wallet is the one the credentials belong to (an app and a wallet API key are
+     * both bound to one wallet): `{ ok: true }`, or `wallet_mismatch`.
+     * OAuth2 app → GET `/wallet/api-key/bind`; cx3wk_ key → GET `/whoami`, then `/wallet/api-key/bind` on 404.
+     * A development node has no credentials: `{ ok: true, devNode: true }`.
      */
     async bindApiKey(address) {
         const addr = normalizeAddress(address);
         if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        const query = { address: addr };
+        if (this.oauth) return this._rejectEnvelope(await this.request("/wallet/api-key/bind", { query }));
         const mode = this.apiKeyMode;
         if (mode === "invalid") {
             throw new Cx3Error("api_key_required", "api_key_required");
         }
         if (mode === "public") {
-            return { ok: true, public: true };
+            return { ok: true, devNode: true };
         }
-        const query = { address: addr };
         try {
             const json = await this.request("/whoami", { query });
             return this._rejectEnvelope(json);
@@ -250,8 +525,18 @@ class Cx3Provider {
         }
     }
 
-    async listContracts({ limit = 50, offset = 0 } = {}) {
-        return this.request("/getContracts", { query: { limit, offset } });
+    /**
+     * Registry list. The gateway shows a private token only when the app's wallet is its owner or an
+     * authorized wallet; `owner`, `standard`, `type` filter and `live` adds supply / paused.
+     */
+    async listContracts({ limit = 50, offset = 0, viewer, owner, standard, type, live } = {}) {
+        const query = { limit, offset };
+        if (viewer) query.viewer = normalizeAddress(viewer);
+        if (owner) query.owner = normalizeAddress(owner);
+        if (standard) query.standard = standard;
+        if (type) query.type = type;
+        if (live) query.live = 1;
+        return this.request("/getContracts", { query });
     }
 
     /**
@@ -261,7 +546,7 @@ class Cx3Provider {
         const body = {
             contractAddress,
             method,
-            params: params || {}
+            params: toJsonSafe(params || {})
         };
         if (sender) body.fromAddress = normalizeAddress(sender);
         const json = await this.request("/contract/call", { method: "POST", body });
@@ -279,7 +564,7 @@ class Cx3Provider {
         const body = {
             contractAddress,
             method,
-            params: params || {},
+            params: toJsonSafe(params || {}),
             fromAddress: normalizeAddress(extras.fromAddress || extras.sender || ""),
             ...extras
         };
@@ -297,9 +582,9 @@ class Cx3Provider {
         try {
             return await this.request(`/tx/${hash}/status`);
         } catch (e) {
-            if (e.status === 404) {
+            if (e.status === 404 && !this.gateway) {
                 const url = `${this.baseUrl}/tx/${hash}/status`;
-                const res = await this.fetchImpl(url, { headers: this._headers() });
+                const res = await this.fetchImpl(url, { headers: await this._headers() });
                 const json = await res.json().catch(() => ({}));
                 if (!res.ok) throw new Cx3HttpError(json.error || `HTTP ${res.status}`, res.status, json);
                 return json;

package/src/utils.js

@@ -48,6 +48,24 @@ function isPlainObject(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
 }
 
+/**
+ * BigInt → decimal string, recursively, so uint256 amounts can be passed as
+ * BigInt. Runs BEFORE signing: the node rebuilds the digest from the JSON it
+ * receives, so the signed params and the sent params must be the same values.
+ */
+function toJsonSafe(value) {
+    if (typeof value === "bigint") return value.toString();
+    if (Array.isArray(value)) return value.map(toJsonSafe);
+    // only literal objects: Date / Buffer keep their own toJSON
+    const proto = value !== null && typeof value === "object" ? Object.getPrototypeOf(value) : undefined;
+    if (proto === Object.prototype || proto === null) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) out[k] = toJsonSafe(v);
+        return out;
+    }
+    return value;
+}
+
 /**
  * Same rules as AppSmokeTest `cx3_dapp_key_mode`:
  * empty → public (any wallet); valid cx3wk_ → private (that wallet); else invalid.
@@ -66,5 +84,6 @@ module.exports = {
     normalizeAddress,
     sleep,
     isPlainObject,
+    toJsonSafe,
     walletApiKeyMode
 };