@carbonx3/cx3.js 0.3.9 → 0.3.11

package/README.md

@@ -14,6 +14,8 @@ CX3js connects server-side applications to CarbonX3 Green Chain through the CX3A
 
 - **OAuth2 application access**: client credentials from CX3WebUI; the access token is requested, cached and renewed for you.
 - **Local signing**: private keys stay in your process, and every write carries the wallet's secp256k1 signature.
+- **Secrets stay out of logs**: a wallet, a provider or a result that is logged or sent as JSON never contains the private key, the client secret or the access token.
+- **Honest results**: a send or transfer the network refuses is reported as failed, and `"confirmed"` always comes with the block it is in.
 - **ABI-bound contracts**: `token.balanceOf(owner)` and `token.transfer(to, amount)`, with the ABI loaded from the chain.
 - **Token deploys**: CX30, CX31, CX300, CX315 and CX3192, plus the green standards CX337–CX341.
 - **Private tokens**: deploy them, and check authorized wallets before anything is signed.
@@ -66,10 +68,13 @@ async function main() {
 
   // Wallet-signed token transfer (BigInt or decimal string)
   const tx = await token.transfer("0xRecipient…", 10n ** 18n);
-  await tx.wait();
+  await tx.wait();                       // resolves when it is in a block, rejects when it failed
 
-  // Native CX3 transfer
-  await wallet.transferNative("0xRecipient…", 1.5);
+  // Native CX3 transfer: check the answer, then wait for the block
+  const pay = await wallet.transferNative("0xRecipient…", 1.5);
+  if (!pay.success) throw new Error(`Transfer refused: ${pay.error}`);  // for example INSUFFICIENT_BALANCE
+  const receipt = await pay.wait();
+  console.log(pay.txHash, receipt.blockHeight);
 }
 
 main().catch((err) => {
@@ -100,6 +105,21 @@ const provider = new Cx3Provider("https://cx3api.carbonx3.com", { apiKey: proces
 
 **No HTTP Basic.** HTTP Basic is the internal login between Green Chain nodes and CarbonX3 services, not an application credential, so the SDK never sends it: the `auth` option throws `BASIC_AUTH_UNSUPPORTED`, and `headers` cannot carry `Authorization` or `X-Api-Key`.
 
+## Keeping secrets out of logs
+
+A wallet's private key and a provider's client secret, API key and access token are private fields of their objects. Nothing that prints, serializes or copies an object can reach them:
+
+```javascript
+JSON.stringify(wallet);          // {"address":"0x…","publicKey":"02…"}
+console.log(provider);           // Cx3Provider {"baseUrl":"https://cx3api.carbonx3.com","authMode":"oauth","clientId":"cx3app_…"}
+res.json(await token.transfer(to, amount));   // the result's own fields; no provider, no wallet
+const copy = { ...wallet };      // address, publicKey and provider; no key
+
+const key = wallet.exportPrivateKey();   // the one way to read the key back (for example to store a new wallet)
+```
+
+`Cx3Wallet.createRandom()` makes a new key in memory only: call `exportPrivateKey()` and store it safely, or the wallet is gone when the process ends. `provider.clearAccessToken()` forgets the held access token, so the next request asks for a new one. Since 0.3.10 there is no `wallet._privateKey`, `provider.apiKey` or `provider._clientSecret` to read.
+
 ## Reading chain data
 
 Public chain data, served by the gateway to every application (a development node answers `DAPP_ONLY`):
@@ -153,14 +173,55 @@ Gas is paid in CX3 to the validator that produces the block: gas used × gas pri
 
 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.0001 (`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`).
 
+### The result of a send or transfer
+
+`token.transfer(…)`, `wallet.sendTransaction(…)` and `wallet.transferNative(…)` return a `TransactionResponse`:
+
+| Field | Meaning |
+|-------|---------|
+| `success` | `true` only when the answer says so or names the transaction (or the request it queued) and carries no error; `false` for a refused one |
+| `status` | `"confirmed"` (always together with `blockHeight`), `"pending"` (accepted, in no block yet; also queued and dropped sends) or `"failed"` |
+| `error` | The network's code for a refused send or transfer (for example `INSUFFICIENT_BALANCE`, `INVALID_NONCE_ORDER`); `null` otherwise |
+| `txHash` | The transaction hash, or `null` when the answer names none |
+| `blockHeight` | The block the transaction is in, once known |
+| `requestId`, `dropped`, `finalAfter`, `hint` | For contract sends: see below |
+| `raw` | The gateway's answer as it came |
+
+The network answers a refused native transfer with HTTP 200 and `{ error, state }`, so nothing is thrown at that point: read `tx.success`, or call `tx.wait()`, which rejects with the same code.
+
+```javascript
+const tx = await wallet.transferNative(to, 25);
+if (!tx.success) {
+  console.error("Refused:", tx.error);   // nothing was sent; fix the cause before signing again
+} else {
+  const receipt = await tx.wait();        // "pending" until it is in a block
+  console.log("Paid in block", receipt.blockHeight, tx.txHash);
+}
+```
+
+Record a payment as made only after `tx.wait()` resolved (or `tx.status === "confirmed"`), never on `success` alone.
+
 ### 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:
 
+- **A refused answer rejects.** `tx.wait()` of a result with `success: false` rejects with a `Cx3TxError` carrying `tx.error`. When the answer names no transaction at all, it rejects with `NO_TX_HASH`: there is nothing to follow.
 - **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`.
+- **When the answer is lost, the error still names the request.** A contract send that gets no answer (connection lost, timeout) rejects with `SEND_OUTCOME_UNKNOWN`. That error, like every other error of a send, carries `err.requestId` and `err.signedRequest`. Look the request up, or send the same signed request again with `wallet.resendTransaction(err.signedRequest)`: the gateway knows it by its id, so it cannot run twice. The signed request holds no key and can be stored.
+
+```javascript
+let tx;
+try {
+  tx = await wallet.sendTransaction(token, "transfer", { to, amount: "1000" });
+} catch (err) {
+  if (err.code !== "SEND_OUTCOME_UNKNOWN") throw err;
+  tx = await wallet.resendTransaction(err.signedRequest); // same signature, same call
+}
+await tx.wait();
+```
 
 ```javascript
 const tx = await token.transfer(to, amount);
@@ -231,7 +292,7 @@ The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `
 
 ## Error handling
 
-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.
+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 does not throw: it returns `tx.success === false`, `tx.status === "failed"` and the code in `tx.error`, and `tx.wait()` rejects with a `Cx3TxError` of that code. Errors and results can be logged as they are; they carry no key, secret or token.
 
 ```javascript
 const { Cx3HttpError } = require("@carbonx3/cx3.js");
@@ -252,7 +313,8 @@ try {
 | `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` | 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 |
+| `INVALID_AMOUNT`, `INVALID_AMOUNT_PRECISION` | A native amount is not greater than 0, is a text that is not plain decimal digits (`"0x10"`, `"1e3"`), or has more than 6 decimal places (CX3 has 6); `transferNative` checks before signing |
+| `INVALID_RECIPIENT` | `transferNative` was given a recipient that is not a full address (`0x` or `cx3:` and 40 hex digits); nothing is signed |
 | `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) |
@@ -261,22 +323,29 @@ try {
 | `PRIVATE_TOKEN_SENDER`, `PRIVATE_TOKEN_RECIPIENT`, `PRIVATE_TOKEN` | Private token rules (see above) |
 | `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_REFUSED` | `tx.error` of an answer that neither reports success nor names a transaction or a reason |
+| `NO_TX_HASH` | `tx.wait()` was called on an answer that names no transaction: there is nothing to follow |
+| `SEND_OUTCOME_UNKNOWN` | A contract send got no answer; the call may still run. Use `err.requestId` / `err.signedRequest` (look up or `resendTransaction`), never a new signature |
+| `INVALID_SIGNED_REQUEST` | `resendTransaction` was given something that is not this wallet's signed request |
+| `SIGN_REFUSED_TRANSACTION_PAYLOAD` | `wallet.signMessage` was given a text the chain accepts as a transaction or call; sign outside messages with `signPersonalMessage` |
 | `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 |
+| `CHAIN_IDENTITY_MISMATCH` | The provider was made for one network (`chainId` and `genesisHash` options) and the endpoint names another; nothing is signed (`err.details.expected`, `err.details.got`) |
+| `INSECURE_BASE_URL` | Credentials would travel over plain `http` to another machine; use `https` (or `allowInsecure: true` on a network you trust) |
 
 ## 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.9.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.11.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
 
 | Variable | Used for |
 |----------|----------|
-| `CX3_CLIENT_ID`, `CX3_CLIENT_SECRET` | Application credentials when the options are omitted |
+| `CX3_CLIENT_ID`, `CX3_CLIENT_SECRET` | Application credentials when the options are omitted (not read with `devNode: true`) |
 | `CX3_API_KEY` | Legacy wallet API key |
 | `CX3_NODE_URL` | Gateway URL for `getDefaultProvider()` |
 
@@ -286,12 +355,13 @@ 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). 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. 0.3.7 changes only this README: a native transfer's gas price floor is 0.0001 (the 0.3.6 README said 0.000001). 0.3.8 changes only this README too: the CX3 IIFE download link names `cx3-0.2.9.min.js`. In 0.3.9, `deployContract` signs `CX3_DEPLOY_V2`: the code and the constructor arguments of the request are under the signature (`Cx3Wallet.deployContentHash`, `signDeploy({ contentHash })`, `deployContentText`).
+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. 0.3.7 changes only this README: a native transfer's gas price floor is 0.0001 (the 0.3.6 README said 0.000001). 0.3.8 changes only this README too: the CX3 IIFE download link names `cx3-0.2.10.min.js`. In 0.3.9, `deployContract` signs `CX3_DEPLOY_V2`: the code and the constructor arguments of the request are under the signature (`Cx3Wallet.deployContentHash`, `signDeploy({ contentHash })`, `deployContentText`). In 0.3.10, a refused native transfer (HTTP 200 with `error`) is `success: false` / `status: "failed"` and `wait()` rejects (before, it was reported as confirmed); an accepted transfer without a block is `"pending"`; `wait()` rejects with `NO_TX_HASH` when the answer names no transaction; the private key, client secret, API key and access token are private fields (`wallet._privateKey`, `provider.apiKey` and `provider._clientSecret` are gone; use `wallet.exportPrivateKey()`), and results no longer carry the provider into JSON or logs. In 0.3.11, `transferNative` refuses a recipient that is not a full address (`INVALID_RECIPIENT`) and a text amount that is not plain decimal digits; `sendTransaction`, `deployContract` and the owner actions sign for `opts.chainId` and `opts.genesisHash` when both are given; a provider can be made for one network (`chainId` and `genesisHash` options, `CHAIN_IDENTITY_MISMATCH`); credentials are not sent over plain `http` to another machine (`INSECURE_BASE_URL`); with `devNode: true` the credentials of the environment are not read; and `@noble/secp256k1` is pinned to one exact version.
 
 - **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.
 - **Typed digests.** Contract sends, deploys and owner actions sign `CX3_CALL_V1` / `CX3_DEPLOY_V1` / `CX3_OWNER_V1` digests bound to the network (see Signing); the `|`-joined digests of 0.2.x are refused. `signSend`, `signDeploy` and `signOwnerAction` take an optional `{ chainId, genesisHash }`, else they ask the provider (kept for a minute). The `build*Digest` helpers need the identity as their last argument.
-- **Site messages.** `signPersonalMessage` signs the way the wallets sign `cx3_sign_message` (with the `0x19` prefix); `signMessage` still signs a digest as it is.
+- **Site messages.** `signPersonalMessage` signs the way the wallets sign `cx3_sign_message` (with the `0x19` prefix). Use it for any text that comes from outside (a login challenge, a user's message). `wallet.signMessage` signs a text as it is, without the prefix, and refuses a text the chain would accept as a transfer, contract call, deploy or owner action (`SIGN_REFUSED_TRANSACTION_PAYLOAD`), so a service that signs messages for its users cannot be made to sign a payment. The exported `signMessage(message, privateKey)` function is the low-level form without that check.
+- **Contract method names.** ABI methods are properties of a `Contract`, except the names JavaScript calls by itself (`then`, `catch`, `finally`, `toJSON`, `inspect`): a contract with such a method is reached with `contract.call(name, params)` or `contract.send(name, params)`.
 
 ## Upgrading from 0.1.x
 

package/index.d.ts

@@ -31,8 +31,13 @@ export interface Cx3ProviderOptions {
   scope?: string | Array<"read" | "write" | "deploy">;
   /** wallet API key (cx3wk_…), until apps move to OAuth2; env CX3_API_KEY */
   apiKey?: string;
-  /** a development node that runs without auth (/api/v1), no credentials */
+  /** a development node that runs without auth (/api/v1); the credentials of the environment are not read for it */
   devNode?: boolean;
+  /** The network this provider is for (both together): an endpoint on another network is refused with CHAIN_IDENTITY_MISMATCH and nothing is signed */
+  chainId?: string;
+  genesisHash?: string;
+  /** Credentials over plain http to another machine throw INSECURE_BASE_URL unless this is true (localhost is always allowed) */
+  allowInsecure?: boolean;
   /** "" on the gateway, "/api/v1" on a development node */
   apiPrefix?: string;
   /** Not supported: throws BASIC_AUTH_UNSUPPORTED (HTTP Basic is the nodes' internal login) */
@@ -77,6 +82,10 @@ export class Cx3Provider {
   authMode: "oauth" | "apiKey" | "devNode";
   /** Throws CREDENTIALS_REQUIRED without clientId / clientSecret, apiKey or devNode */
   constructor(baseUrl: string, options?: Cx3ProviderOptions);
+  /** Forget the held access token: the next request asks for a new one */
+  clearAccessToken(): void;
+  /** Where the provider points and how it signs in; never a credential (JSON.stringify and util.inspect use it) */
+  toJSON(): { baseUrl: string; authMode: "oauth" | "apiKey" | "devNode"; clientId?: string; scope?: string };
   /** The current OAuth2 access token (renewed a minute before it expires); null without an OAuth2 app */
   getAccessToken(force?: boolean): Promise<string | null>;
   request(path: string, opts?: { method?: string; body?: unknown; query?: Record<string, string | number> }): Promise<any>;
@@ -134,7 +143,12 @@ export class Cx3Wallet {
   constructor(privateKey: string | Uint8Array | Buffer, provider?: Cx3Provider | null);
   static createRandom(provider?: Cx3Provider | null): Cx3Wallet;
   connect(provider: Cx3Provider): Cx3Wallet;
+  /** The private key as given to the constructor; the wallet shows it nowhere else (not in JSON, logs or a spread) */
+  exportPrivateKey(): string | Uint8Array | Buffer;
+  /** Address and public key only (JSON.stringify and util.inspect use it) */
+  toJSON(): { address: string; publicKey: string };
   getAddress(): string;
+  /** Signs a text / bytes as given (no site-message prefix). Refuses a chain payload (typed digest, transaction JSON) with SIGN_REFUSED_TRANSACTION_PAYLOAD: use signPersonalMessage for a message from outside */
   signMessage(message: string | Uint8Array): Promise<{
     signature: string;
     r: string;
@@ -156,17 +170,32 @@ export class Cx3Wallet {
   signSend(contractAddress: string, method: string, params?: object, opts?: Cx3ChainIdentity): Promise<any>;
   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>;
+  sendTransaction(contractAddress: string, method: string, params?: object, opts?: { wait?: number; async?: boolean; privateCheck?: boolean; chainId?: string; genesisHash?: string; [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. 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 */
+  /** Sends an earlier send's signed request again, unchanged (no new signature): after SEND_OUTCOME_UNKNOWN or a lost answer */
+  resendTransaction(signedRequest: Cx3SignedRequest, opts?: { wait?: number; async?: boolean }): Promise<TransactionResponse>;
+  deployContract(fields: object, opts?: Cx3ChainIdentity): Promise<Cx3DeployResult>;
+  pauseContract(address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
+  unpauseContract(address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
+  deleteContract(address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
+  /** Before signing, throws Cx3Error INVALID_RECIPIENT (not 0x / cx3: + 40 hex), INVALID_AMOUNT (not greater than 0, or a text that is not plain decimal digits) or INVALID_AMOUNT_PRECISION (more than 6 decimals) */
   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>;
 }
 
+/** A signed contract call as it was sent: no key in it, safe to store; `requestId` is sha256 of its CX3_CALL_V1 digest */
+export interface Cx3SignedRequest {
+  contractAddress: string;
+  method: string;
+  params: object;
+  fromAddress: string;
+  signature: string;
+  senderPublicKey: string;
+  timestamp: number;
+  requestId: string;
+}
+
+/** ABI methods become properties, except names JavaScript calls by itself (then, catch, finally, toJSON, inspect): reach those with call() / send() */
 export class Contract {
   address: string;
   target: string | null;
@@ -242,7 +271,10 @@ export class TransactionResponse {
   blockHeight?: number;
   contractAddress: string | null;
   async: boolean;
-  /** "pending" for async, TX_TIMEOUT (queued) and dropped answers; "confirmed" / "failed" for sync ones */
+  /**
+   * "pending" for async, TX_TIMEOUT (queued) and dropped answers and for a transfer accepted but in no block yet;
+   * "confirmed" only with a blockHeight; "failed" for a refused one (also the node's HTTP 200 `{ error }` answer)
+   */
   status: string;
   /** trimmed from a block: not final, another validator may still include it until finalAfter */
   dropped: boolean;
@@ -250,9 +282,13 @@ export class TransactionResponse {
   finalAfter: number | null;
   /** the signed request's id (lookup: provider.getRequest) */
   requestId: string | null;
+  /** contract sends: the signed call as sent (not enumerable, not in JSON); wallet.resendTransaction takes it */
+  signedRequest?: Cx3SignedRequest;
   hint: string | null;
   error: string | null;
-  /** follows pending / dropped answers (until finalAfter by default); rejects only on a final failure */
+  /** the answer without the provider (JSON.stringify uses it) */
+  toJSON(): Record<string, unknown>;
+  /** follows pending / dropped answers (until finalAfter by default); rejects on a refused answer, on a final failure, and with NO_TX_HASH when the answer names no transaction */
   wait(opts?: { timeoutMs?: number; intervalMs?: number; onPending?: (status: any) => void; onConfirmed?: (status: any) => void }): Promise<any>;
 }
 

package/index.js

@@ -34,7 +34,7 @@ const {
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.3.9";
+const VERSION = "0.3.11";
 
 /**
  * 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.9",
+  "version": "0.3.11",
   "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": {
@@ -40,7 +40,7 @@
     "node": ">=20.19.0"
   },
   "dependencies": {
-    "@noble/secp256k1": "^3.2.0"
+    "@noble/secp256k1": "3.2.0"
   },
   "exports": {
     ".": {

package/src/contract.js

@@ -7,6 +7,8 @@
 const { normalizeAbi, argsToParams } = require("./abi");
 const { Cx3Error } = require("./errors");
 
+const RESERVED_METHOD_NAMES = new Set(["then", "catch", "finally", "toJSON", "inspect", "__proto__"]);
+
 /**
  * Contract handle with ABI-bound methods.
  *
@@ -32,7 +34,10 @@ class Contract {
 
         const self = this;
         for (const name of Object.keys(this.interface)) {
-            if (name in this) continue;
+            // A method named like something JavaScript calls by itself never becomes a property: `await contract`
+            // calls `then`, JSON.stringify calls `toJSON`, and either would send a signed call nobody asked
+            // for. Such a method stays reachable as contract.call(name, …) / contract.send(name, …).
+            if (name in this || RESERVED_METHOD_NAMES.has(name)) continue;
             this[name] = async function (...args) {
                 return self._invoke(name, args);
             };

package/src/provider.js

@@ -65,7 +65,16 @@ function withoutCredentialHeaders(headers) {
     return out;
 }
 
-const CLIENT_ID_RE = /^cx3app_[a-f0-9]{24}$/i;
+// http to another machine (not localhost / 127.x / ::1)
+function isRemotePlainHttp(baseUrl) {
+    let u;
+    try { u = new URL(baseUrl); } catch (_) { return false; }
+    if (u.protocol !== "http:") return false;
+    const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return !(host === "localhost" || host.endsWith(".localhost") || host === "::1" || /^127(\.\d{1,3}){3}$/.test(host));
+}
+
+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)
@@ -78,6 +87,12 @@ function isTransientError(e) {
 }
 
 class Cx3Provider {
+    // Credentials live in private fields: JSON.stringify, util.inspect, console.log, Object.keys and a
+    // spread of the provider (or of anything that holds it) never show them.
+    #clientSecret = "";
+    #apiKey = "";
+    #token = null;          // { value, refreshAt, scope }
+
     /**
      * @param {string} baseUrl  CX3Api gateway URL (`CX3_NODE_URL`, e.g. https://cx3api.carbonx3.com), or a development node with `devNode`
      * @param {object} [options]
@@ -100,29 +115,47 @@ class Cx3Provider {
                 "BASIC_AUTH_UNSUPPORTED"
             );
         }
-        const env = (name) => (process.env[name] || "").trim();
+        this.devNode = options.devNode === true;
+        // a development node gets only what the caller passes: the gateway credentials of the environment never go to it
+        const env = (name) => (this.devNode ? "" : (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.#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))) {
+        this.#apiKey = String(options.apiKey != null ? options.apiKey : env("CX3_API_KEY")).trim();
+        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";
+        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"
             );
         }
+        // credentials over plain http can be read on the way: only this machine, or the caller's own word
+        if ((this.oauth || hasKey) && options.allowInsecure !== true && isRemotePlainHttp(this.baseUrl)) {
+            throw new Cx3Error(
+                "Credentials are not sent over plain http: use an https URL (or allowInsecure: true on a network you trust)",
+                "INSECURE_BASE_URL"
+            );
+        }
+        // The network this provider is for: with both given, signatures are made for this network only and
+        // an endpoint that names another one is refused (CHAIN_IDENTITY_MISMATCH).
+        this.pinnedIdentity = null;
+        if (options.chainId != null || options.genesisHash != null) {
+            const chainId = String(options.chainId == null ? "" : options.chainId).trim();
+            const genesisHash = normalizeGenesisHash(options.genesisHash);
+            if (!chainId || !genesisHash) {
+                throw new Cx3Error("chainId and genesisHash are given together (genesisHash: 64 hex)", "NO_CHAIN_IDENTITY");
+            }
+            this.pinnedIdentity = { chainId, genesisHash };
+        }
         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();
@@ -132,12 +165,12 @@ class Cx3Provider {
     }
 
     get apiKeyMode() {
-        return walletApiKeyMode(this.apiKey);
+        return walletApiKeyMode(this.#apiKey);
     }
 
     /** "oauth" | "apiKey" | "devNode" */
     get authMode() {
-        if (this.devNode && !this.oauth && walletApiKeyMode(this.apiKey) === "public") return "devNode";
+        if (this.devNode && !this.oauth && walletApiKeyMode(this.#apiKey) === "public") return "devNode";
         return this.oauth ? "oauth" : "apiKey";
     }
 
@@ -147,7 +180,7 @@ class Cx3Provider {
      */
     async getAccessToken(force = false) {
         if (!this.oauth) return null;
-        if (!force && this._token && Date.now() < this._token.refreshAt) return this._token.value;
+        if (!force && this.#token && Date.now() < this.#token.refreshAt) return this.#token.value;
         if (!this._tokenPromise) {
             this._tokenPromise = this._fetchToken().finally(() => { this._tokenPromise = null; });
         }
@@ -155,7 +188,7 @@ class Cx3Provider {
     }
 
     async _fetchToken() {
-        const form = new URLSearchParams({ grant_type: "client_credentials", client_id: this.clientId, client_secret: this._clientSecret });
+        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",
@@ -167,8 +200,22 @@ class Cx3Provider {
             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;
+        this.#token = { value: json.access_token, refreshAt: Date.now() + Math.max(30, ttl - 60) * 1000, scope: json.scope || "" };
+        return this.#token.value;
+    }
+
+    /** Forget the held access token: the next request asks for a new one. */
+    clearAccessToken() {
+        this.#token = null;
+    }
+
+    /** What a log or a JSON answer may show of a provider: where it points and how it signs in, no credential. */
+    toJSON() {
+        return { baseUrl: this.baseUrl, authMode: this.authMode, clientId: this.clientId || undefined, scope: this.scope || undefined };
+    }
+
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `Cx3Provider ${JSON.stringify(this.toJSON())}`;
     }
 
     async _headers(forceToken = false) {
@@ -178,8 +225,8 @@ class Cx3Provider {
         };
         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;
+        } else if (/^cx3wk_[a-f0-9]{48}$/i.test(this.#apiKey)) {
+            headers["X-Api-Key"] = this.#apiKey;
         }
         return headers;
     }
@@ -413,6 +460,14 @@ class Cx3Provider {
         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");
+        const pin = this.pinnedIdentity;
+        if (pin && (pin.chainId !== chainId || pin.genesisHash !== genesisHash)) {
+            throw new Cx3Error(
+                "The endpoint is on another network than the one this provider was made for: nothing is signed",
+                "CHAIN_IDENTITY_MISMATCH",
+                { expected: { ...pin }, got: { chainId, genesisHash } }
+            );
+        }
         this._chainIdentity = { at: Date.now(), value: { chainId, genesisHash } };
         return { chainId, genesisHash };
     }

package/src/transaction.js

@@ -17,13 +17,19 @@ class TransactionResponse {
      */
     constructor(result, provider = null, opts = {}) {
         this.raw = result || {};
-        this.provider = provider;
+        // not enumerable: a result that is logged, spread or sent as JSON does not drag the provider along
+        Object.defineProperty(this, "provider", { value: provider, enumerable: false, writable: true, configurable: true });
         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;
+        // The node refuses a native transfer with HTTP 200 and { error, state }, without a `success` field
+        // (review 3, 2026-11-12): an answer is a success only when it says so, or when it names the
+        // transaction (hash) or the request it queued, and carries no error.
+        const named = !!this.txHash || !!this.raw.requestId || this.raw.async === true;
+        const refused = this.raw.success === false || (this.raw.success !== true && (!!this.raw.error || !named));
+        this.success = queued || !refused;
         this.blockHeight = this.raw.blockHeight;
         this.contractAddress = this.raw.contractAddress || null;
         this.async = !!this.raw.async || opts.wait === 0;
@@ -32,8 +38,16 @@ class TransactionResponse {
         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);
+        // "confirmed" only with the block it is in: an accepted transfer that is still in the pool is pending
+        const own = !this.success ? "failed" : (this.async || this.blockHeight == null ? "pending" : "confirmed");
+        this.status = queued ? "pending" : (this.success ? (this.raw.status || own) : "failed");
+        this.error = queued ? null : (this.raw.error || this.raw.message || (this.success ? null : "TX_REFUSED"));
+    }
+
+    /** The answer without the provider (what JSON.stringify and a log show). */
+    toJSON() {
+        const { raw, ...own } = this;
+        return { ...own, raw };
     }
 
     /**
@@ -54,7 +68,8 @@ class TransactionResponse {
             };
         }
         if (!this.txHash) {
-            return this.raw;
+            // nothing to follow: resolving here would report a transaction nobody can name as done
+            throw new Cx3TxError("The answer names no transaction to wait for", "NO_TX_HASH", this.raw);
         }
         if (!this.provider) {
             throw new Cx3TxError("No provider to wait on transaction", "NO_PROVIDER", this.raw);

package/src/wallet.js

@@ -24,6 +24,33 @@ function isValidTokenSymbol(symbol) {
     return TOKEN_SYMBOL_RE.test(String(symbol == null ? "" : symbol));
 }
 
+/**
+ * A text the chain verifies as its own: a typed digest (CX3_CALL_V1|…, CX3_DEPLOY_V1|…, CX3_OWNER_V1|…)
+ * or a transaction's canonical JSON payload. The same rule as the CX3Wallet extension's sign request.
+ */
+function isChainPayload(message) {
+    let text;
+    try {
+        text = typeof message === "string" ? message : Buffer.from(message).toString("utf8");
+    } catch (_) {
+        return false;
+    }
+    if (/^CX3_[A-Z0-9]+_V\d+\|/.test(text)) return true;
+    let obj = null;
+    try {
+        obj = JSON.parse(text);
+    } catch (_) {
+        return false;
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) return false;
+    return "fromAddress" in obj || ("type" in obj && "nonce" in obj);
+}
+
+/** Request id of a signed contract send: sha256 (hex) of its CX3_CALL_V1 digest, as the gateway names it. */
+function requestIdOf(digest) {
+    return Buffer.from(sha256(Buffer.from(String(digest), "utf8"))).toString("hex");
+}
+
 /**
  * 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
@@ -61,13 +88,17 @@ function withDeployWait(result, provider) {
  * Local secp256k1 wallet for Green Chain digests.
  */
 class Cx3Wallet {
+    // The key is a private field: JSON.stringify, util.inspect, console.log, Object.keys and a spread of
+    // the wallet (or of a result that holds it) never show it. It leaves only through exportPrivateKey().
+    #privateKey;
+
     /**
      * @param {string|Uint8Array|Buffer} privateKey
      * @param {import('./provider').Cx3Provider|null} [provider]
      */
     constructor(privateKey, provider = null) {
         if (!privateKey) throw new Cx3Error("privateKey required", "NO_PRIVATE_KEY");
-        this._privateKey = privateKey;
+        this.#privateKey = privateKey;
         this.provider = provider;
         this.address = privateKeyToAddress(privateKey);
         this.publicKey = privateKeyToPublicKey(privateKey, true).toString("hex");
@@ -78,21 +109,49 @@ class Cx3Wallet {
     }
 
     connect(provider) {
-        return new Cx3Wallet(this._privateKey, provider);
+        return new Cx3Wallet(this.#privateKey, provider);
+    }
+
+    /** The private key as given to the constructor (a createRandom() wallet: the only way to save it). */
+    exportPrivateKey() {
+        return this.#privateKey;
+    }
+
+    /** What a log or a JSON answer may show of a wallet: its address and public key. */
+    toJSON() {
+        return { address: this.address, publicKey: this.publicKey };
+    }
+
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `Cx3Wallet ${JSON.stringify(this.toJSON())}`;
     }
 
     getAddress() {
         return this.address;
     }
 
-    /** Sign raw bytes / a digest string as given (sha256 + secp256k1): the typed digests use this. */
+    /**
+     * Sign raw bytes / a text as given (sha256 + secp256k1), without the site-message prefix.
+     * A text the chain would accept as a transaction, contract call, deploy or owner action is refused
+     * (SIGN_REFUSED_TRANSACTION_PAYLOAD): a service that signs "any message" for its users would otherwise
+     * hand out transfer signatures. Those have their own methods (transferNative, signSend, signDeploy,
+     * signOwnerAction); for a message from outside, use signPersonalMessage.
+     */
     async signMessage(message) {
-        return signMessage(message, this._privateKey);
+        if (isChainPayload(message)) {
+            throw new Cx3Error("This text is a chain transaction or call, not a message", "SIGN_REFUSED_TRANSACTION_PAYLOAD");
+        }
+        return signMessage(message, this.#privateKey);
+    }
+
+    /** The wallet's own typed digests and transfer payloads. */
+    #signPayload(payload) {
+        return signMessage(payload, this.#privateKey);
     }
 
     /** Sign a site message the way the CX3Wallet extension and app do (with the site-message prefix). */
     async signPersonalMessage(message) {
-        return signPersonalMessage(message, this._privateKey);
+        return signPersonalMessage(message, this.#privateKey);
     }
 
     /** The network identity typed digests bind: `opts.chainId` + `opts.genesisHash`, else the provider's. */
@@ -121,7 +180,7 @@ class Cx3Wallet {
             contentHash,
             timestamp
         }, await this._identity(opts));
-        const signed = await this.signMessage(digest);
+        const signed = await this.#signPayload(digest);
         return {
             ...signed,
             owner,
@@ -143,7 +202,7 @@ class Cx3Wallet {
         const timestamp = Date.now();
         const safeParams = toJsonSafe(params || {});
         const digest = buildSendDigest(contractAddress, method, safeParams, fromAddress, timestamp, await this._identity(opts));
-        const signed = await this.signMessage(digest);
+        const signed = await this.#signPayload(digest);
         return {
             ...signed,
             fromAddress,
@@ -157,7 +216,7 @@ class Cx3Wallet {
         const own = normalizeAddress(owner || this.address);
         const timestamp = Date.now();
         const digest = buildOwnerActionDigest(action, address, own, timestamp, await this._identity(opts));
-        const signed = await this.signMessage(digest);
+        const signed = await this.#signPayload(digest);
         return {
             ...signed,
             owner: own,
@@ -176,20 +235,72 @@ class Cx3Wallet {
         if (opts.privateCheck !== false && typeof this.provider.checkPrivateTokenSend === "function") {
             await this.provider.checkPrivateTokenSend(contractAddress, method, params, this.address);
         }
-        const signed = await this.signSend(contractAddress, method, params);
-        const body = {
+        const signed = await this.signSend(contractAddress, method, params, opts);
+        // everything the gateway needs to take the same signed call again: no key, safe to store
+        const signedRequest = {
+            contractAddress,
+            method,
+            params: signed.params,
             fromAddress: signed.fromAddress,
             signature: signed.signature,
             senderPublicKey: signed.senderPublicKey,
-            timestamp: signed.timestamp
+            timestamp: signed.timestamp,
+            requestId: requestIdOf(signed.digest)
         };
+        return this.#postSigned(signedRequest, opts);
+    }
+
+    /**
+     * Send a signed contract call again, exactly as it was signed: the `signedRequest` of an earlier
+     * answer or of a SEND_OUTCOME_UNKNOWN error. The gateway knows a signed request by its id, so the
+     * call cannot run twice; a new signature would be a second call.
+     */
+    async resendTransaction(signedRequest, opts = {}) {
+        if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
+        const r = signedRequest || {};
+        if (!r.signature || !r.senderPublicKey || !r.timestamp || !r.method || !r.contractAddress) {
+            throw new Cx3Error("signedRequest of an earlier send required", "INVALID_SIGNED_REQUEST");
+        }
+        if (normalizeAddress(r.fromAddress) !== normalizeAddress(this.address)) {
+            throw new Cx3Error("This request was signed by another wallet", "INVALID_SIGNED_REQUEST");
+        }
+        return this.#postSigned({ ...r }, opts);
+    }
+
+    async #postSigned(signedRequest, opts) {
         const asyncMode = opts.wait === 0 || opts.async === true;
-        // send exactly the params that were signed (BigInt already as strings)
-        const result = await this.provider.send(contractAddress, method, signed.params, {
-            ...body,
-            wait: asyncMode ? 0 : undefined
-        });
-        return new TransactionResponse(result, this.provider, opts);
+        let result;
+        try {
+            // send exactly the params that were signed (BigInt already as strings)
+            result = await this.provider.send(signedRequest.contractAddress, signedRequest.method, signedRequest.params, {
+                fromAddress: signedRequest.fromAddress,
+                signature: signedRequest.signature,
+                senderPublicKey: signedRequest.senderPublicKey,
+                timestamp: signedRequest.timestamp,
+                wait: asyncMode ? 0 : undefined
+            });
+        } catch (e) {
+            // The caller gets the request's name and its signed form with every failure, so a lost answer is
+            // looked up (provider.getRequest) or sent again as it is (resendTransaction), never signed anew.
+            if (e instanceof Cx3Error) {
+                e.requestId = signedRequest.requestId;
+                e.signedRequest = signedRequest;
+                throw e;
+            }
+            const open = new Cx3Error(
+                "No answer to the send: the call may still run. Look it up or send the same signed request again; do not sign a new one.",
+                "SEND_OUTCOME_UNKNOWN",
+                { requestId: signedRequest.requestId, cause: String((e && e.message) || e) }
+            );
+            open.requestId = signedRequest.requestId;
+            open.signedRequest = signedRequest;
+            throw open;
+        }
+        const tx = new TransactionResponse(result, this.provider, opts);
+        if (!tx.requestId) tx.requestId = signedRequest.requestId;
+        // not enumerable: the answer logs and serializes as before
+        Object.defineProperty(tx, "signedRequest", { value: signedRequest, enumerable: false, configurable: true, writable: true });
+        return tx;
     }
 
     /**
@@ -198,7 +309,7 @@ class Cx3Wallet {
      * (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) {
+    async deployContract(fields, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
         fields = toJsonSafe(fields || {});
         const ctor = fields.constructorArgs && typeof fields.constructorArgs === "object" && !Array.isArray(fields.constructorArgs) ? fields.constructorArgs : {};
@@ -218,7 +329,7 @@ class Cx3Wallet {
             ...fields,
             owner: fields.owner || this.address,
             contentHash
-        });
+        }, opts);
         const body = {
             ...fields,
             owner: signed.owner,
@@ -236,9 +347,9 @@ class Cx3Wallet {
         return withDeployWait(result, this.provider);
     }
 
-    async _ownerActionRequest(action, address, owner, method, path) {
+    async _ownerActionRequest(action, address, owner, method, path, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
-        const signed = await this.signOwnerAction(action, address, owner);
+        const signed = await this.signOwnerAction(action, address, owner, opts);
         return this.provider.request(path, {
             method,
             body: {
@@ -250,33 +361,36 @@ class Cx3Wallet {
         });
     }
 
-    async pauseContract(address, owner = null) {
+    async pauseContract(address, owner = null, opts = {}) {
         return this._ownerActionRequest(
             "pause",
             address,
             owner,
             "PUT",
-            `/contracts/${encodeURIComponent(address)}/pause`
+            `/contracts/${encodeURIComponent(address)}/pause`,
+            opts
         );
     }
 
-    async unpauseContract(address, owner = null) {
+    async unpauseContract(address, owner = null, opts = {}) {
         return this._ownerActionRequest(
             "unpause",
             address,
             owner,
             "PUT",
-            `/contracts/${encodeURIComponent(address)}/unpause`
+            `/contracts/${encodeURIComponent(address)}/unpause`,
+            opts
         );
     }
 
-    async deleteContract(address, owner = null) {
+    async deleteContract(address, owner = null, opts = {}) {
         return this._ownerActionRequest(
             "delete",
             address,
             owner,
             "DELETE",
-            `/contracts/${encodeURIComponent(address)}`
+            `/contracts/${encodeURIComponent(address)}`,
+            opts
         );
     }
 
@@ -288,9 +402,18 @@ class Cx3Wallet {
      */
     async transferNative(to, amount, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
-        const toAddress = String(to || "").trim();
-        if (!toAddress) throw new Cx3Error("recipient required", "NO_RECIPIENT");
-        const amt = typeof amount === "number" ? amount : Number(amount);
+        if (to == null || String(to).trim() === "") throw new Cx3Error("recipient required", "NO_RECIPIENT");
+        // a full address only (0x / cx3: + 40 hex): anything else is not signed
+        const toAddress = normalizeAddress(to);
+        if (!/^0x[0-9a-f]{40}$/.test(toAddress)) {
+            throw new Cx3Error("The recipient is not a CX3 address (0x + 40 hex)", "INVALID_RECIPIENT");
+        }
+        // a text amount is plain decimal digits: "0x10" or "1e3" would be read as another number
+        if (typeof amount === "string" && !/^\d{1,15}(\.\d+)?$/.test(amount.trim())) {
+            throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
+        }
+        if (typeof amount !== "number" && typeof amount !== "string") throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
+        const amt = typeof amount === "number" ? amount : Number(amount.trim());
         if (!Number.isFinite(amt) || amt <= 0) {
             throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
         }
@@ -327,7 +450,7 @@ class Cx3Wallet {
             chainId: identity.chainId,
             genesisHash: identity.genesisHash
         });
-        const signed = await this.signMessage(payload);
+        const signed = await this.#signPayload(payload);
         const body = {
             type: "TRANSFER",
             fromAddress: stripNativeAddress(this.address),