@carbonx3/cx3.js 0.3.3 → 0.3.5

package/README.md

@@ -145,12 +145,12 @@ 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) still bounds the work it may do.
 
-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`, 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.
 
 ## Deploying tokens
 
@@ -179,7 +179,7 @@ Token symbols are capital letters `A-Z` and digits `0-9` only. The SDK checks th
 
 A private token is sent, received and seen only by its owner and its authorized wallets. The token contract enforces this on the chain, and the SDK follows the same rules:
 
-- **Lists:** `getTokens` shows a private token only to its owner, its authorized wallets and its holders; `listContracts()` shows it only when the application's wallet is its owner or an authorized wallet. Its holders and raw state answer `403 PRIVATE_TOKEN` to every application except the owner's.
+- **Lists:** `getTokens` shows a private token only to its owner, its authorized wallets and its holders, and only with that wallet's own signed proof (header `X-CX3-Wallet-Proof`, since 2026-10-19; CX3Wallet sends it for its own lists), so an application gets the public tokens; `listContracts()` shows it only when the application's wallet is its owner or an authorized wallet. Its holders and raw state answer `403 PRIVATE_TOKEN` to every application except the owner's.
 - **Sends:** before a `transfer`, `transferFrom` or `mint` of a private token, the wallet asks the token whether both ends are authorized. If one is not, it throws `PRIVATE_TOKEN_SENDER` or `PRIVATE_TOKEN_RECIPIENT` instead of signing a send the block would refuse. `{ privateCheck: false }` skips the check.
 - **Checks:** `provider.isPrivateToken(token)` and `provider.isTokenAuthorized(token, wallet)`, which returns `true` for the owner or a listed wallet, `false` otherwise and `null` when the node does not answer.
 
@@ -233,7 +233,7 @@ 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_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 |
@@ -242,7 +242,7 @@ try {
 
 ## 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.1.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.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.
 
 ## Environment variables
 
@@ -258,7 +258,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.3 change only this README and the file headers, 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).
 
 - **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.js

@@ -33,7 +33,7 @@ const {
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.3.3";
+const VERSION = "0.3.5";
 
 /**
  * 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.3",
+  "version": "0.3.5",
   "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/provider.js

@@ -502,7 +502,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 +519,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;

package/src/utils.js

@@ -71,7 +71,7 @@ function toJsonSafe(value) {
 }
 
 /**
- * Same rules as AppSmokeTest `cx3_dapp_key_mode`:
+ * Same rules as DappsExamples/CX3AssetDashboard `cx3_dapp_key_mode`:
  * empty → public (any wallet); valid cx3wk_ → private (that wallet); else invalid.
  */
 function walletApiKeyMode(key) {