@carbonx3/cx3.js 0.3.4 → 0.3.6

package/README.md

@@ -123,6 +123,7 @@ With the `read` scope:
 | `call(address, method, params)` | A read-only call; the result is in `value` |
 | `getEvents(address, { type, limit, offset })`, `getTransfers(address, { limit, offset })`, `getHolders(address, { limit, offset })` | Contract history |
 | `getAddressTransactions(address, limit)`, `getTxStatus(txHash)` | Transactions |
+| `getRequest(requestId, from)` | What became of a signed contract send (public; see [Waiting for a transaction](#waiting-for-a-transaction)) |
 
 ## Contracts
 
@@ -145,12 +146,27 @@ Supported ABI shapes:
 
 ## Transactions and fees
 
-Every transaction pays gas in CX3 to the validator that produces the block: gas used × gas price (devnet default 0.0001 CX3 per gas).
+Gas is paid in CX3 to the validator that produces the block: gas used × gas price (devnet default 0.0001 CX3 per gas).
 
-- A native transfer uses 21,000 gas: **2.1 CX3**.
-- A contract send or deploy is admitted only when the sender holds its gas limit × gas price (100,000 gas by default, so at least **10 CX3**) and is charged the gas it used.
+- A native transfer uses 21,000 gas: **2.1 CX3**. The sender needs the amount plus the fee.
+- A contract send or deploy through the gateway is relayed by the chain's own deploy account: the call still runs as your wallet (the chain checks your signature again), and your wallet pays no gas for it. The call's gas limit (100,000 by default) bounds the node's trial run when the call is sent (a call that needs more is refused); in the block the VM runs the call under its own per-call limit.
 
-Too little balance fails with `INSUFFICIENT_BALANCE`, and a gas price below the chain floor with `GAS_PRICE_TOO_LOW`. A send waits for its block by default; with `{ wait: 0 }` it returns at once, and `tx.wait()` polls the transaction status until it is confirmed or failed.
+Too little balance for a native transfer fails with `INSUFFICIENT_BALANCE`. A native transfer's gas limit and gas price are `0` (the chain's defaults: 21,000 and 0.0001) or 21,000–100,000 and at least the chain floor of 0.000001 (`GAS_LIMIT_TOO_LOW`, `GAS_LIMIT_TOO_HIGH`, `GAS_PRICE_TOO_LOW`), and its amount is greater than 0 with at most 6 decimal places, because CX3 has 6. `transferNative` checks the amount before signing (`INVALID_AMOUNT`, `INVALID_AMOUNT_PRECISION`).
+
+### Waiting for a transaction
+
+A contract send waits for its block by default (the node waits up to 25 seconds); with `{ wait: 0 }` it returns at once. `tx.wait()` polls the transaction status until it is confirmed or failed for good:
+
+- **Pending is not failed.** `tx.status` is `"pending"` for `{ wait: 0 }`, for a queued send (HTTP 202 `queued: true`, code `TX_TIMEOUT`: not in a block within the node's wait) and for a dropped send. `tx.success` stays `true`, and `tx.wait()` follows the transaction. A queued or dropped deploy is `status: "pending"` too: the token factory gives `result.contract` only after `result.wait()` sees it confirmed.
+- **Dropped sends.** A send the node trimmed from its block comes back as HTTP 202 with `tx.dropped === true` and `tx.finalAfter` (ms epoch, about 12 minutes after the signed timestamp). Until then another validator may still include it, so by default `tx.wait()` keeps waiting until `finalAfter` plus 30 seconds. After that the status says `failed`, and `tx.wait()` rejects with `TX_FAILED`.
+- **Only a final failure rejects with `TX_FAILED`.** `TX_TRACK_TIMEOUT` (your own `timeoutMs`, otherwise 60 seconds or until `finalAfter` for a dropped send) means the transaction is still pending: its `receipt` has `status: "pending"`, `dropped` and `finalAfter`. A network error, a 429 or a 5xx answer while polling does not end the wait.
+- **Never sign the same call again while it can still run.** A new signature is a second call. Every send answer carries `tx.requestId`, and `provider.getRequest(tx.requestId, wallet.address)` tells what became of it: `executed`, `pending`, `submitted` or `unknown`.
+
+```javascript
+const tx = await token.transfer(to, amount);
+if (tx.dropped) console.log("Not in a block yet; final after", new Date(tx.finalAfter));
+const receipt = await tx.wait();  // confirmed, or throws TX_FAILED / TX_TRACK_TIMEOUT
+```
 
 ## Deploying tokens
 
@@ -171,6 +187,8 @@ console.log(result.contractAddress);          // result.contract is a ready Cont
 | `deployCX3192` | Soulbound identity |
 | `deployCX337` … `deployCX341` | Green standards: CBAM proof, sustainability report, supply chain, materiality assessment, green claims |
 
+A deploy the node trimmed from its block answers HTTP 202 with `result.dropped === true`, `status: "pending"`, `finalAfter` and, when known, its `contractAddress` (otherwise `null`): it is not deployed yet, so `result.contract` is not set. `await result.wait()` follows it as `tx.wait()` follows a send: once it is confirmed, `status` becomes `"confirmed"` and the factory adds `result.contract` (and `result.authorized` for a private token); after `finalAfter` it rejects with `TX_FAILED`. Do not deploy the same contract again before then. `wallet.deployContract()` results have the same `dropped`, `finalAfter` and `wait()`.
+
 The helpers deploy to CX3WASM by default. The chain renders CX30 and CX337–CX341 from the fields; CX31, CX300, CX315 and CX3192 take their CX3Script source as `sourceCode` (otherwise the chain answers `STANDARD_NOT_WASM_DEPLOYABLE`).
 
 Token symbols are capital letters `A-Z` and digits `0-9` only. The SDK checks this before signing (`INVALID_TOKEN_SYMBOL`; see `isValidTokenSymbol`), and the chain keeps one contract per symbol (`409 DUPLICATE_TOKEN_SYMBOL`).
@@ -207,13 +225,13 @@ Digests are UTF-8 strings, hashed with SHA-256 and signed with secp256k1, byte-i
 - **Site message:** `0x19` + `"CX3 Signed Message:\n"` + UTF-8 length + message (`signPersonalMessage`), the way the CX3Wallet extension and app sign `cx3_sign_message`
 - **Native transfer:** `JSON.stringify({ type, fromAddress, toAddress, amount, nonce, timestamp, data, gasLimit, gasPrice, chainId, genesisHash })`, with 40-hex addresses and no `0x`; `chainId` and `genesisHash` (`0x` + 64 hex) are the network's, from `provider.getChainIdentity()`
 
-BigInt values in params are converted to decimal strings before signing, and exactly those params are sent. Signatures carry a timestamp and are accepted within ±5 minutes of the node's clock; a native transfer is taken only by a block within 10 minutes of its timestamp. The genesis hash ties a native transfer to one network and one genesis: after a chain reset, a transfer signed before it no longer verifies. An address is `0x` + the last 20 bytes of `sha256(uncompressedPublicKey)`.
+BigInt values in params are converted to decimal strings before signing, and exactly those params are sent. Deploy, contract-send and owner signatures carry a timestamp and are accepted within ±5 minutes of the gateway's clock. A native transfer is admitted only within 60 seconds after its timestamp (the pool drops it after 60 seconds), and a block takes it only within 10 minutes of its timestamp. The genesis hash ties a native transfer to one network and one genesis: after a chain reset, a transfer signed before it no longer verifies. An address is `0x` + the last 20 bytes of `sha256(uncompressedPublicKey)`.
 
 The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `buildOwnerActionDigest` (each takes the identity as its last argument), `buildTransferPayload`, `personalMessageBytes`, `signMessage` (signs a digest as given), `signPersonalMessage`, `privateKeyToAddress` and `createPrivateKey`.
 
 ## Error handling
 
-Every error is a `Cx3Error` with a `code`. `Cx3HttpError` adds the HTTP `status` and the response `body`; `Cx3TxError` adds the transaction `receipt`.
+Every error is a `Cx3Error` with a `code`. `Cx3HttpError` adds the HTTP `status` and the response `body` (with `requestId` for a contract send); `Cx3TxError` adds the transaction `receipt`. A send or native transfer that the node refuses with HTTP 200 returns `tx.success === false` with the code in `tx.error`, and `tx.wait()` rejects with a `Cx3TxError` of that code.
 
 ```javascript
 const { Cx3HttpError } = require("@carbonx3/cx3.js");
@@ -233,16 +251,26 @@ try {
 | `invalid_client` | The token endpoint refused the application (wrong secret, or revoked) |
 | `insufficient_scope`, `ROUTE_NOT_ALLOWED` | The route needs another scope, or is not open to applications (403) |
 | `RATE_LIMITED` | The application's rate limit was reached (429) |
-| `INSUFFICIENT_BALANCE`, `GAS_PRICE_TOO_LOW` | The sender cannot pay the gas, or the gas price is below the chain floor |
+| `INSUFFICIENT_BALANCE`, `GAS_PRICE_TOO_LOW` | A native transfer's sender cannot pay the amount plus gas, or the gas price is below the chain floor |
+| `INVALID_AMOUNT`, `INVALID_AMOUNT_PRECISION` | A native amount is not greater than 0, or has more than 6 decimal places (CX3 has 6); `transferNative` checks both before signing |
+| `GAS_LIMIT_TOO_LOW`, `GAS_LIMIT_TOO_HIGH` | A native transfer's gas limit is outside 21,000–100,000 |
+| `GAS_LIMIT_EXCEEDED` | A contract send's `gasLimit` is above the chain's maximum (400, `max` in the body) |
+| `INVALID_NONCE_ORDER` | A native transfer's nonce is not the next one (`expectedNonce` in the answer) |
+| `DATA_TOO_LARGE`, `DATA_TOO_DEEP` | A transaction's `data` is too large or nested too deeply |
 | `INVALID_TOKEN_SYMBOL`, `DUPLICATE_TOKEN_SYMBOL` | The symbol is not `A-Z` / `0-9`, or is already in use (409) |
 | `PRIVATE_TOKEN_SENDER`, `PRIVATE_TOKEN_RECIPIENT`, `PRIVATE_TOKEN` | Private token rules (see above) |
-| `TX_FAILED`, `TX_TRACK_TIMEOUT` | The transaction failed, or `tx.wait()` did not see it confirmed in time |
+| `TX_TIMEOUT` | The node's 25-second wait ended before a block: queued, not final. A send answer with this code is pending and `tx.wait()` follows it; without a tx hash the outcome is open (look up its `requestId`) |
+| `TX_FAILED` | The transaction failed for good (a dropped send only after its `finalAfter`) |
+| `TX_TRACK_TIMEOUT` | `tx.wait()` stopped while the transaction was still pending: not a failure, do not sign it again |
+| `REPLAYED_REQUEST` | This signed request was already received or already ran (409); the answer does not say how it ended. Look it up with `provider.getRequest(err.body.requestId, wallet.address)` and never sign it again |
+| `REQUEST_LOOKUP_UNAVAILABLE` | `getRequest` could not ask the chain (503): try again later, do not sign again |
+| `LEDGER_UNAVAILABLE`, `LEDGER_FULL` | The gateway's `/dapp/v1` send could not record the request (503): it was not sent, and the same signed body may be sent again later, without a new signature |
 | `BASIC_AUTH_UNSUPPORTED` | The `auth` option was used |
 | `NO_CHAIN_IDENTITY` | The network's chain id or genesis hash is unavailable; a native transfer is not signed without them |
 
 ## Browser applications
 
-This package is for Node.js servers. Web pages use the **CX3 IIFE** (`window.cx3`) together with the CX3Wallet extension: [`@carbonx3/cx3-iife`](https://www.npmjs.com/package/@carbonx3/cx3-iife) on npm and jsDelivr, or [download it](https://cx3script.com/download/cx3-0.2.7.min.js); see the [CX3 IIFE guide](https://cx3script.com/docs?doc=cx3iife). Keep the application's credentials on your server behind a same-origin proxy, and never put a client secret, an API key or a private key in browser JavaScript.
+This package is for Node.js servers. Web pages use the **CX3 IIFE** (`window.cx3`) together with the CX3Wallet extension: [`@carbonx3/cx3-iife`](https://www.npmjs.com/package/@carbonx3/cx3-iife) on npm and jsDelivr, or [download it](https://cx3script.com/download/cx3-0.2.8.min.js); see the [CX3 IIFE guide](https://cx3script.com/docs?doc=cx3iife). Keep the application's credentials on your server behind a same-origin proxy, and never put a client secret, an API key or a private key in browser JavaScript.
 
 ## Environment variables
 
@@ -258,7 +286,7 @@ Type declarations (`index.d.ts`) ship with the package.
 
 ## Upgrading from 0.2.x
 
-Version 0.3.0 signs native transfers for the network's new signing format (0.3.1 to 0.3.4 change only this README, the file headers and comments, not the code):
+Version 0.3.0 signs native transfers for the network's new signing format (0.3.1 to 0.3.4 change only this README, the file headers and comments, not the code). In 0.3.5, `bindApiKey` with a wallet API key asks the gateway's `/wallet/api-key/bind` (before, it asked `/whoami`, which the gateway refuses, so it always failed). In 0.3.6, `wait()` follows a send or deploy the gateway reports as not final (`dropped`) until its `finalAfter` instead of failing after 60 s, a `TX_TIMEOUT` answer with a hash is pending, `getRequest()` looks up a signed request, and `transferNative` refuses more than 6 decimals.
 
 - **The genesis hash is signed.** `transferNative` asks the network for its chain id and genesis hash (`provider.getChainIdentity()`) unless both are given as `opts.chainId` and `opts.genesisHash`. 0.2.x transfers no longer verify on the chain.
 - **No fallback chain id.** `buildTransferPayload` throws `NO_CHAIN_IDENTITY` without `chainId` and `genesisHash`; the `CX3_CHAIN_ID` variable and the `chainIdBind` option are gone.

package/index.d.ts

@@ -120,7 +120,10 @@ export class Cx3Provider {
   /** A wallet's LP token balance in one CarbonFi pool (pair id = 40 hex) */
   getLpBalance(pairId: string, address: string): Promise<{ success: boolean; balance: string; totalSupply: string; lpContractAddress: string | null; onChain: boolean }>;
   getTxStatus(txHash: string): Promise<any>;
-  waitForTransaction(txHash: string, opts?: object): Promise<any>;
+  /** A dropped tx is followed until its finalAfter (+30 s) unless timeoutMs is given; only a final failure rejects (TX_FAILED) */
+  waitForTransaction(txHash: string, opts?: { timeoutMs?: number; intervalMs?: number; finalAfter?: number; onPending?: (status: any) => void; onConfirmed?: (status: any) => void }): Promise<any>;
+  /** What became of a signed contract send, by its requestId (public /dapp/v1/requests/:requestId?from=); look it up instead of signing again */
+  getRequest(requestId: string, from: string): Promise<{ success: boolean; requestId: string; status: "executed" | "pending" | "submitted" | "unknown"; txHash?: string | null; blockHeight?: number; outcome?: string | null; expiresAt?: number; [k: string]: unknown }>;
   getContract(address: string, abi?: unknown, signer?: Cx3Wallet | null): Promise<Contract>;
 }
 
@@ -151,11 +154,12 @@ export class Cx3Wallet {
   signOwnerAction(action: string, address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
   /** A private token's transfer / transferFrom / mint is checked first (PRIVATE_TOKEN_SENDER / _RECIPIENT); `privateCheck: false` skips it */
   sendTransaction(contractAddress: string, method: string, params?: object, opts?: { wait?: number; async?: boolean; privateCheck?: boolean; [k: string]: unknown }): Promise<TransactionResponse>;
-  /** Throws Cx3Error INVALID_TOKEN_SYMBOL (before signing) for a symbol outside A-Z / 0-9; the chain answers DUPLICATE_TOKEN_SYMBOL (409) for a symbol in use. */
-  deployContract(fields: object): Promise<any>;
+  /** Throws Cx3Error INVALID_TOKEN_SYMBOL (before signing) for a symbol outside A-Z / 0-9; the chain answers DUPLICATE_TOKEN_SYMBOL (409) for a symbol in use. A dropped deploy is pending: result.wait() follows it. */
+  deployContract(fields: object): Promise<Cx3DeployResult>;
   pauseContract(address: string, owner?: string | null): Promise<any>;
   unpauseContract(address: string, owner?: string | null): Promise<any>;
   deleteContract(address: string, owner?: string | null): Promise<any>;
+  /** Throws Cx3Error INVALID_AMOUNT (not greater than 0) or INVALID_AMOUNT_PRECISION (more than 6 decimals) before signing */
   transferNative(to: string, amount: number | string, opts?: { nonce?: number; timestamp?: number; data?: unknown; gasLimit?: number; gasPrice?: number; chainId?: string; genesisHash?: string; wait?: number }): Promise<TransactionResponse>;
   bindApiKey(address?: string): Promise<any>;
 }
@@ -191,19 +195,40 @@ export interface Cx3TokenDeployFields {
   [k: string]: unknown;
 }
 
+/** A deploy answer: the gateway's fields plus dropped / finalAfter and wait() */
+export interface Cx3DeployResult {
+  success?: boolean;
+  contractAddress?: string | null;
+  txHash?: string;
+  blockHeight?: number;
+  /** "pending" for a dropped deploy; wait() sets "confirmed" or "failed" */
+  status?: string;
+  /** trimmed from a block: not deployed yet, another validator may still include it until finalAfter */
+  dropped: boolean;
+  /** ms epoch after which a dropped deploy is failed for good; null otherwise */
+  finalAfter: number | null;
+  /** factory only: set once the deploy is confirmed (for a dropped deploy: by wait()) */
+  contract?: Contract;
+  /** factory, private deploy with authorizedWallets: [{ wallet, success, txHash?, error? }] */
+  authorized?: Array<{ wallet: string; success: boolean; txHash?: string | null; error?: string }>;
+  /** follows a pending / dropped deploy (until finalAfter by default); rejects only on a final failure (TX_FAILED) */
+  wait(opts?: { timeoutMs?: number; intervalMs?: number; onPending?: (status: any) => void; onConfirmed?: (status: any) => void }): Promise<any>;
+  [k: string]: any;
+}
+
 export class Cx3TokenFactory {
   constructor(wallet: Cx3Wallet);
-  /** result.authorized: [{ wallet, success, txHash?, error? }] for a private deploy with authorizedWallets */
-  deployCX30(fields?: Cx3TokenDeployFields): Promise<any>;
-  deployCX31(fields?: Cx3TokenDeployFields): Promise<any>;
-  deployCX300(fields?: Cx3TokenDeployFields): Promise<any>;
-  deployCX315(fields?: Cx3TokenDeployFields): Promise<any>;
-  deployCX3192(fields?: Cx3TokenDeployFields): Promise<any>;
-  deployCX337(fields?: object): Promise<any>;
-  deployCX338(fields?: object): Promise<any>;
-  deployCX339(fields?: object): Promise<any>;
-  deployCX340(fields?: object): Promise<any>;
-  deployCX341(fields?: object): Promise<any>;
+  /** result.authorized: [{ wallet, success, txHash?, error? }] for a private deploy with authorizedWallets; a dropped deploy gets contract / authorized from result.wait() */
+  deployCX30(fields?: Cx3TokenDeployFields): Promise<Cx3DeployResult>;
+  deployCX31(fields?: Cx3TokenDeployFields): Promise<Cx3DeployResult>;
+  deployCX300(fields?: Cx3TokenDeployFields): Promise<Cx3DeployResult>;
+  deployCX315(fields?: Cx3TokenDeployFields): Promise<Cx3DeployResult>;
+  deployCX3192(fields?: Cx3TokenDeployFields): Promise<Cx3DeployResult>;
+  deployCX337(fields?: object): Promise<Cx3DeployResult>;
+  deployCX338(fields?: object): Promise<Cx3DeployResult>;
+  deployCX339(fields?: object): Promise<Cx3DeployResult>;
+  deployCX340(fields?: object): Promise<Cx3DeployResult>;
+  deployCX341(fields?: object): Promise<Cx3DeployResult>;
 }
 
 export class TransactionResponse {
@@ -214,8 +239,18 @@ export class TransactionResponse {
   blockHeight?: number;
   contractAddress: string | null;
   async: boolean;
+  /** "pending" for async, TX_TIMEOUT (queued) and dropped answers; "confirmed" / "failed" for sync ones */
   status: string;
-  wait(opts?: object): Promise<any>;
+  /** trimmed from a block: not final, another validator may still include it until finalAfter */
+  dropped: boolean;
+  /** ms epoch after which a dropped tx is failed for good; null otherwise */
+  finalAfter: number | null;
+  /** the signed request's id (lookup: provider.getRequest) */
+  requestId: string | null;
+  hint: string | null;
+  error: string | null;
+  /** follows pending / dropped answers (until finalAfter by default); rejects only on a final failure */
+  wait(opts?: { timeoutMs?: number; intervalMs?: number; onPending?: (status: any) => void; onConfirmed?: (status: any) => void }): Promise<any>;
 }
 
 export function getDefaultProvider(options?: Cx3ProviderOptions & { url?: string }): Cx3Provider;

package/index.js

@@ -33,7 +33,7 @@ const {
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.3.4";
+const VERSION = "0.3.6";
 
 /**
  * Convenience: provider from `options.url` or env `CX3_NODE_URL` — the CX3Api gateway

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonx3/cx3.js",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Official Node.js SDK (CX3js) for CarbonX3 Green Chain: OAuth2 app access, local secp256k1 signing, ABI-bound contracts and token deploys over REST + JSON",
   "homepage": "https://cx3script.com",
   "publishConfig": {

package/src/factory.js

@@ -63,8 +63,10 @@ class Cx3TokenFactory {
 
     /**
      * Deploy CX30 fungible token.
+     * A deploy not in a block yet (status "pending": dropped with `finalAfter`, or still queued) has no `contract` yet:
+     * `await result.wait()` follows it and adds `contract` (and `authorized`) once it is confirmed.
      * @param {object} fields  name, symbol, decimals, initialSupply, capabilities, target, …
-     * @returns {Promise<{ contractAddress, txHash, blockHeight, contract?: Contract }>}
+     * @returns {Promise<{ contractAddress, txHash, blockHeight, dropped, finalAfter, contract?: Contract, wait(opts?): Promise<object> }>}
      */
     async deployCX30(fields = {}) {
         return this._deployStandard("CX30", {
@@ -162,25 +164,43 @@ class Cx3TokenFactory {
             ...body,
             standard
         });
-        if (result && result.success !== false && result.contractAddress) {
-            try {
-                result.contract = await this.wallet.provider.getContract(
-                    result.contractAddress,
-                    null,
-                    this.wallet
-                );
-            } catch (_) {
-                result.contract = new Contract(
-                    result.contractAddress,
-                    { methods: {} },
-                    this.wallet
-                );
-            }
-            if (wallets.length) result.authorized = await this._authorize(result.contract, wallets);
+        if (result && (result.dropped || result.status === "pending") && typeof result.wait === "function") {
+            // trimmed from a block or still queued: not deployed yet. The contract handle (and the
+            // authorized wallets of a private token) come once result.wait() sees the deploy confirmed
+            const follow = result.wait;
+            let done = null;
+            const wait = async (opts) => {
+                const receipt = await follow(opts);
+                if (!done) done = this._finishDeploy(result, wallets);
+                await done;
+                return receipt;
+            };
+            Object.defineProperty(result, "wait", { value: wait, enumerable: false, configurable: true, writable: true });
+            return result;
         }
+        if (result && result.success !== false && result.contractAddress) await this._finishDeploy(result, wallets);
         return result;
     }
 
+    // a deployed contract: its handle from the chain's ABI, then one addToWhitelist per authorized wallet
+    async _finishDeploy(result, wallets) {
+        if (!result.contractAddress) return;
+        try {
+            result.contract = await this.wallet.provider.getContract(
+                result.contractAddress,
+                null,
+                this.wallet
+            );
+        } catch (_) {
+            result.contract = new Contract(
+                result.contractAddress,
+                { methods: {} },
+                this.wallet
+            );
+        }
+        if (wallets.length) result.authorized = await this._authorize(result.contract, wallets);
+    }
+
     _privateFields(standard, fields, list) {
         if (!PRIVATE_STANDARDS.has(standard)) {
             throw new Cx3Error(`${standard} has no private variant (CX30, CX31, CX300, CX315 and CX3192 do)`, "PRIVATE_NOT_SUPPORTED");

package/src/provider.js

@@ -68,6 +68,15 @@ function withoutCredentialHeaders(headers) {
 const CLIENT_ID_RE = /^cx3app_[a-f0-9]{24}$/i;
 const CLIENT_SECRET_RE = /^cx3sec_[a-f0-9]{64}$/i;
 
+// a dropped tx is failed for good after its finalAfter: wait this much past it (clock skew)
+const FINAL_MARGIN_MS = 30000;
+
+// no answer, a timeout, 429 or 5xx while polling: the tx may still be fine
+function isTransientError(e) {
+    if (e instanceof Cx3HttpError) return e.status === 429 || e.status >= 500;
+    return !!e && (e.name === "AbortError" || e.name === "TimeoutError" || e.name === "TypeError");
+}
+
 class Cx3Provider {
     /**
      * @param {string} baseUrl  CX3Api gateway URL (`CX3_NODE_URL`, e.g. https://cx3api.carbonx3.com), or a development node with `devNode`
@@ -502,7 +511,8 @@ class Cx3Provider {
     /**
      * 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.
+     * OAuth2 app and cx3wk_ key → GET `/wallet/api-key/bind` (the gateway route; it has no `/whoami`);
+     * a cx3wk_ key falls back to `/whoami` on 404 (a same-origin proxy that only forwards that).
      * A development node has no credentials: `{ ok: true, devNode: true }`.
      */
     async bindApiKey(address) {
@@ -518,11 +528,11 @@ class Cx3Provider {
             return { ok: true, devNode: true };
         }
         try {
-            const json = await this.request("/whoami", { query });
+            const json = await this.request("/wallet/api-key/bind", { query });
             return this._rejectEnvelope(json);
         } catch (e) {
             if (e && e.status === 404) {
-                const json = await this.request("/wallet/api-key/bind", { query });
+                const json = await this.request("/whoami", { query });
                 return this._rejectEnvelope(json);
             }
             throw e;
@@ -573,11 +583,34 @@ class Cx3Provider {
             ...extras
         };
         delete body.sender;
-        return this.request("/contract/send", {
-            method: "POST",
-            body,
-            query: extras.wait === 0 ? { wait: 0 } : undefined
-        });
+        try {
+            return await this.request("/contract/send", {
+                method: "POST",
+                body,
+                query: extras.wait === 0 ? { wait: 0 } : undefined
+            });
+        } catch (e) {
+            // TX_TIMEOUT as a 504 (a proxy, the /dapp/v1 group): queued, not final. Answered like the
+            // node's own 200 TX_TIMEOUT so tx.wait() follows the hash; without one it stays an error
+            if (e instanceof Cx3HttpError && e.code === "TX_TIMEOUT" && e.body && e.body.txHash) {
+                return { ...e.body, success: false, error: "TX_TIMEOUT" };
+            }
+            throw e;
+        }
+    }
+
+    /**
+     * What became of a signed contract send, by the `requestId` every send answer carries
+     * (`/dapp/v1/requests/:requestId?from=`, public): `{ status: "executed" | "pending" | "submitted" |
+     * "unknown", txHash?, blockHeight?, outcome?, expiresAt? }`. After a lost answer or REPLAYED_REQUEST,
+     * look the request up here instead of signing again; 503 REQUEST_LOOKUP_UNAVAILABLE = ask later.
+     */
+    async getRequest(requestId, from) {
+        const id = String(requestId || "").toLowerCase();
+        if (!/^[0-9a-f]{64}$/.test(id)) throw new Cx3Error("request id must be 64 hex characters", "INVALID_REQUEST_ID");
+        const addr = normalizeAddress(from);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        return this._dappRead(`/requests/${id}`, { from: addr });
     }
 
     async getTxStatus(txHash) {
@@ -599,15 +632,34 @@ class Cx3Provider {
 
     /**
      * Poll until confirmed / failed / timeout.
+     * A dropped tx (`dropped`, `finalAfter` in the send or status answer) is not final: another
+     * validator may still include it until finalAfter, so by default the wait lasts until then
+     * (+ FINAL_MARGIN_MS); `opts.timeoutMs` sets the caller's own limit. Only a final failure
+     * rejects with TX_FAILED; TX_TRACK_TIMEOUT means "still pending", not "failed".
+     * @param {{ timeoutMs?: number, intervalMs?: number, finalAfter?: number, onPending?: Function, onConfirmed?: Function }} [opts]
      * @returns {Promise<object>} terminal receipt
      */
     async waitForTransaction(txHash, opts = {}) {
-        const timeoutMs = opts.timeoutMs || 60000;
-        let interval = opts.intervalMs || 1000;
         const start = Date.now();
-        while (Date.now() - start < timeoutMs) {
+        let finalAfter = Number(opts.finalAfter) > 0 ? Number(opts.finalAfter) : null;
+        let dropped = finalAfter !== null;
+        const deadline = () => (opts.timeoutMs > 0
+            ? start + opts.timeoutMs
+            : Math.max(start + 60000, finalAfter !== null ? finalAfter + FINAL_MARGIN_MS : 0));
+        let interval = opts.intervalMs || 1000;
+        while (Date.now() < deadline()) {
             await sleep(interval);
-            const status = await this.getTxStatus(txHash);
+            let status;
+            try {
+                status = await this.getTxStatus(txHash);
+            } catch (e) {
+                // a network blip or a busy gateway says nothing about the tx: ask again
+                if (!isTransientError(e)) throw e;
+                interval = Math.min(5000, Math.round(interval * 1.5));
+                continue;
+            }
+            if (status.dropped === true) dropped = true;
+            if (Number(status.finalAfter) > 0) finalAfter = Number(status.finalAfter);
             if (typeof opts.onPending === "function" && status.status === "pending") {
                 try { opts.onPending(status); } catch (_) { /* ignore */ }
             }
@@ -622,7 +674,8 @@ class Cx3Provider {
             }
             interval = Math.min(5000, Math.round(interval * 1.5));
         }
-        const err = new Cx3TxError("TX_TRACK_TIMEOUT", "TX_TRACK_TIMEOUT", { txHash });
+        // not final: never a reason to sign the same call again
+        const err = new Cx3TxError("TX_TRACK_TIMEOUT", "TX_TRACK_TIMEOUT", { txHash, status: "pending", dropped, finalAfter });
         err.txHash = txHash;
         throw err;
     }

package/src/transaction.js

@@ -18,25 +18,34 @@ class TransactionResponse {
     constructor(result, provider = null, opts = {}) {
         this.raw = result || {};
         this.provider = provider;
-        this.success = this.raw.success !== false;
         this.txHash = this.raw.txHash || this.raw.hash || null;
         this.hash = this.txHash;
+        // TX_TIMEOUT with a hash: queued, not final within the node's sync wait (25 s), so pending:
+        // follow it with wait(), never sign the same call again
+        const queued = this.raw.success === false && this.raw.error === "TX_TIMEOUT" && !!this.txHash;
+        this.success = this.raw.success !== false || queued;
         this.blockHeight = this.raw.blockHeight;
         this.contractAddress = this.raw.contractAddress || null;
         this.async = !!this.raw.async || opts.wait === 0;
-        this.status = this.raw.status || (this.async ? "pending" : (this.success ? "confirmed" : "failed"));
-        this.error = this.raw.error || this.raw.message || null;
+        // trimmed from a block (202 dropped): not final, another validator may still include it until finalAfter
+        this.dropped = this.raw.dropped === true;
+        this.finalAfter = Number(this.raw.finalAfter) > 0 ? Number(this.raw.finalAfter) : null;
+        this.requestId = this.raw.requestId || null;
+        this.hint = this.raw.hint || null;
+        this.status = queued ? "pending" : (this.raw.status || (this.async ? "pending" : (this.success ? "confirmed" : "failed")));
+        this.error = queued ? null : (this.raw.error || this.raw.message || null);
     }
 
     /**
-     * Wait for confirmation when the node returned async / pending.
-     * Sync responses that already include blockHeight resolve immediately.
+     * Wait for confirmation when the node returned async / pending (also TX_TIMEOUT and dropped).
+     * Sync responses that already include blockHeight resolve immediately. A dropped tx is followed
+     * until its finalAfter by default; only a final failure rejects (TX_FAILED).
      */
     async wait(opts = {}) {
         if (!this.success) {
             throw new Cx3TxError(this.error || "TX_FAILED", this.error || "TX_FAILED", this.raw);
         }
-        if (!this.async && this.blockHeight != null) {
+        if (!this.async && !this.dropped && this.blockHeight != null) {
             return {
                 status: "confirmed",
                 txHash: this.txHash,
@@ -50,7 +59,7 @@ class TransactionResponse {
         if (!this.provider) {
             throw new Cx3TxError("No provider to wait on transaction", "NO_PROVIDER", this.raw);
         }
-        return this.provider.waitForTransaction(this.txHash, opts);
+        return this.provider.waitForTransaction(this.txHash, this.finalAfter ? { finalAfter: this.finalAfter, ...opts } : opts);
     }
 }
 

package/src/wallet.js

@@ -23,6 +23,39 @@ function isValidTokenSymbol(symbol) {
     return TOKEN_SYMBOL_RE.test(String(symbol == null ? "" : symbol));
 }
 
+/**
+ * A deploy result keeps the gateway's fields and gets `dropped`, `finalAfter` and `wait()`. A deploy
+ * the node trimmed from its block (202 dropped, status "pending") is not deployed yet: another
+ * validator may still include it until finalAfter. One still queued after the node's 25 s wait (202
+ * `queued`, or an older gateway's 200 TX_TIMEOUT with a hash) is pending too, status "pending".
+ * wait() follows it like TransactionResponse.wait() (TX_FAILED only when final) and sets `status`
+ * (and blockHeight / contractAddress) from the answer.
+ */
+function withDeployWait(result, provider) {
+    if (!result || typeof result !== "object") return result;
+    const tx = new TransactionResponse(result, provider);
+    result.dropped = tx.dropped;
+    result.finalAfter = tx.finalAfter;
+    if (tx.status === "pending" && result.status === undefined) result.status = "pending";
+    if (tx.status === "pending" && result.contractAddress === undefined) result.contractAddress = null;
+    const wait = async (opts) => {
+        let receipt;
+        try {
+            receipt = await tx.wait(opts);
+        } catch (e) {
+            if (e && e.code === "TX_FAILED") result.status = "failed";
+            throw e;
+        }
+        result.status = "confirmed";
+        if (result.blockHeight == null && receipt && receipt.blockHeight != null) result.blockHeight = receipt.blockHeight;
+        if (!result.contractAddress && receipt && receipt.contractAddress) result.contractAddress = receipt.contractAddress;
+        return receipt;
+    };
+    // not enumerable: the result still serializes (and spreads) as the gateway's answer
+    Object.defineProperty(result, "wait", { value: wait, enumerable: false, configurable: true, writable: true });
+    return result;
+}
+
 /**
  * Local secp256k1 wallet for Green Chain digests.
  */
@@ -146,7 +179,8 @@ class Cx3Wallet {
     /**
      * Deploy via Green Chain `POST /deployContract`. A symbol outside A-Z / 0-9 is refused here,
      * before signing (INVALID_TOKEN_SYMBOL); the chain also refuses a symbol already in use
-     * (Cx3HttpError code DUPLICATE_TOKEN_SYMBOL, status 409).
+     * (Cx3HttpError code DUPLICATE_TOKEN_SYMBOL, status 409). A dropped deploy (202, `dropped`,
+     * `finalAfter`) is pending, not deployed: `result.wait()` follows it (withDeployWait).
      */
     async deployContract(fields) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
@@ -179,7 +213,7 @@ class Cx3Wallet {
             method: "POST",
             body
         });
-        return result;
+        return withDeployWait(result, this.provider);
     }
 
     async _ownerActionRequest(action, address, owner, method, path) {
@@ -229,6 +263,8 @@ class Cx3Wallet {
     /**
      * Native CX3 coin transfer (`POST /sendTransaction`).
      * Distinct from `sendTransaction()` which is a signed `/contract/send`.
+     * The amount is checked before signing: greater than 0 (INVALID_AMOUNT), at most 6 decimals
+     * (INVALID_AMOUNT_PRECISION).
      */
     async transferNative(to, amount, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
@@ -238,6 +274,10 @@ class Cx3Wallet {
         if (!Number.isFinite(amt) || amt <= 0) {
             throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
         }
+        // CX3 has 6 decimals: the chain refuses a finer amount (the node's fitsSubunits rule), so it is not signed
+        if (Number(amt.toFixed(6)) !== amt) {
+            throw new Cx3Error("CX3 amounts have at most 6 decimals", "INVALID_AMOUNT_PRECISION", { maxDecimals: 6 });
+        }
         let nonce = opts.nonce;
         if (nonce == null) {
             try {