@carbonx3/cx3.js 0.1.0 → 0.2.0

package/README.md

@@ -1,138 +1,278 @@
-# @carbonx3/cx3.js — CarbonX3 Green Chain SDK
+# @carbonx3/cx3.js
 
-Official JavaScript client (**CX3js**) for **CarbonX3 Green Chain**.
+[![npm version](https://img.shields.io/npm/v/@carbonx3/cx3.js.svg)](https://www.npmjs.com/package/@carbonx3/cx3.js)
+[![Node.js version](https://img.shields.io/node/v/@carbonx3/cx3.js.svg)](https://nodejs.org/)
+[![Types](https://img.shields.io/npm/types/@carbonx3/cx3.js.svg)](https://www.npmjs.com/package/@carbonx3/cx3.js)
 
-Talks to the node over **REST + JSON** (`/api/v1/...`) with named method params.
+The official Node.js SDK (**CX3js**) for [CarbonX3 Green Chain](https://carbonx3.com/).
 
-| `@carbonx3/cx3.js` | Role | Green Chain API |
-|----------|------|-----------------|
-| `Cx3Provider` | HTTP client | `CX3_NODE_URL` + `/api/v1` |
-| `Cx3Wallet` | secp256k1 signing | Deploy / send digests |
-| `Contract` / `provider.getContract` | ABI-bound calls | `/contract/call` + `/contract/send` |
-| `Cx3TokenFactory` | Standard deploys | `POST /deployContract` (CX30–CX3192, CX337–CX341) |
+CX3js connects server-side applications to CarbonX3 Green Chain through the CX3Api gateway. It signs in as an OAuth2 application, signs transactions locally with secp256k1, binds contract ABIs to plain JavaScript methods and deploys the Green Chain token standards. Requests are REST + JSON with named parameters, not binary calldata.
 
-## Install
+> **Network status:** CarbonX3 Green Chain currently runs as a development network (devnet, chain id `cx3-dev`). Devnet CX3, tokens and contracts are test data with no monetary value and may be cleared when the devnet is reset.
+
+## Features
+
+- **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.
+- **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.
+- **Public chain reads**: chain status, wallet tokens and activity, CarbonFi pools and CX3WASM interfaces (WIT).
+- **TypeScript declarations included**; works with both `require` and `import`.
+
+## Requirements
+
+- Node.js **20.19** or later (native `fetch`).
+- An application (client ID and client secret) created in CX3WebUI, as described below.
+
+## Installation
 
 ```bash
-# when published
 npm install @carbonx3/cx3.js
+```
 
-# from monorepo root
-npm install ./CX3Web3JS
+## Create an application
 
-# or inside another package
-npm install file:../CX3Web3JS
-```
+1. Open [CX3WebUI](https://cx3webui.carbonx3.com) → **Settings → API → Applications** and connect the wallet the application acts for.
+2. Name the application, choose its scopes and click **Create App**. The wallet signs the request.
+3. Store the **client ID** (`cx3app_…`) and the **client secret** (`cx3sec_…`, shown only once) in your server's environment.
+
+| Scope | Grants |
+|-------|--------|
+| `read` | Balances, nonces, contracts, ABIs, events, transfers, transactions and read-only calls |
+| `write` | Wallet-signed contract sends and native CX3 transfers |
+| `deploy` | Contract deploys, plus pause, unpause and delete (owner-signed) |
 
-Node.js **18+** (native `fetch`).
+A wallet can hold up to five applications. Revoking an application on the same page stops its access tokens within a minute.
 
 ## Quick start
 
 ```javascript
-const {
-  Cx3Provider,
-  Cx3Wallet,
-  Cx3TokenFactory,
-  readCallValue
-} = require("@carbonx3/cx3.js");
-
-const provider = new Cx3Provider(process.env.CX3_NODE_URL, {
-  auth: {
-    user: process.env.CX3_INTERNAL_AUTH_USER,
-    pass: process.env.CX3_INTERNAL_AUTH_PASS
-  }
-  // or: apiKey: process.env.CX3_API_KEY   // empty = public (any wallet); cx3wk_ = that wallet only
-});
+const { Cx3Provider, Cx3Wallet } = require("@carbonx3/cx3.js");
 
+const provider = new Cx3Provider("https://cx3api.carbonx3.com", {
+  clientId: process.env.CX3_CLIENT_ID,         // cx3app_…
+  clientSecret: process.env.CX3_CLIENT_SECRET  // cx3sec_…
+});
 const wallet = new Cx3Wallet(process.env.CX3_PRIVATE_KEY, provider);
-await wallet.bindApiKey();
 
-// Read
-const token = await provider.getContract(process.env.CONTRACT_ADDRESS, null, wallet);
-const balance = await token.balanceOf(wallet.address);
-console.log("balance", balance);
+async function main() {
+  // Native CX3 balance
+  console.log(await provider.getBalance(wallet.address));
 
-const cx3Balance = await provider.getBalance(wallet.address);
+  // Token contract; its ABI is loaded from the chain
+  const token = await provider.getContract(process.env.CONTRACT_ADDRESS, null, wallet);
+  console.log(await token.balanceOf(wallet.address));
 
-// Write
-const tx = await token.transfer("0xRecipient…", "1000000000000000000");
-await tx.wait();
+  // Wallet-signed token transfer (BigInt or decimal string)
+  const tx = await token.transfer("0xRecipient…", 10n ** 18n);
+  await tx.wait();
 
-await wallet.pauseContract(process.env.CONTRACT_ADDRESS);
-await wallet.transferNative("0xRecipient…", 1);
+  // Native CX3 transfer
+  await wallet.transferNative("0xRecipient…", 1.5);
+}
 
-// Deploy CX30
-const factory = new Cx3TokenFactory(wallet);
-const deployed = await factory.deployCX30({
-  name: "My Token",
-  symbol: "MTK",
-  initialSupply: "0",
-  target: "CX3WASM"
+main().catch((err) => {
+  console.error(err.code || err.name, err.message);
+  process.exitCode = 1;
 });
-console.log(deployed.contractAddress);
 ```
 
-## Signing (important)
+ES modules work too: `import { Cx3Provider, Cx3Wallet } from "@carbonx3/cx3.js";`. The remaining examples assume an `async` context.
+
+## Authentication
 
-Digests are **UTF-8 strings**, then `sha256` + **secp256k1** (same as CX3Wallet):
+**OAuth2 application (recommended).** The provider exchanges `clientId` and `clientSecret` at `POST /oauth/token` (client credentials grant) for a one-hour access token and sends it as `Authorization: Bearer …`. It renews the token a minute before it expires and, if the gateway answers `invalid_token`, fetches a fresh one and retries once. The secret is sent only to the token endpoint. `scope: ["read"]` requests fewer scopes than the application has. When the options are omitted, the provider reads `CX3_CLIENT_ID` and `CX3_CLIENT_SECRET`.
 
-- Deploy: `deploy|{owner}|{standard}|{name}|{symbol}|{decimals}|{initialSupply}|{timestamp}`
-- Send: `{contractAddress}|{method}|{JSON.stringify(params)}|{fromAddress}`
-- Owner: `{action}|{address}|{owner}|{timestamp}`
-- Native CX3: canonical JSON payload (`buildTransferPayload`) then `wallet.transferNative(to, amount)`
+The access token identifies the application; every write is still signed by the wallet. A route outside the application's scopes answers `403 insufficient_scope`, and routes reserved for CarbonX3's own services answer `403 ROUTE_NOT_ALLOWED`. Each application has its own rate limit (300 requests per minute by default, `429 RATE_LIMITED`).
+
+`provider.bindApiKey(address)` (or `wallet.bindApiKey()`) confirms that a wallet is the one the application belongs to: `{ ok: true }`, otherwise `wallet_mismatch`.
+
+**Wallet API key (legacy).** A `cx3wk_…` key from the same settings page still works while applications move to OAuth2. Pass it as `apiKey` (or set `CX3_API_KEY`); it is sent as `X-Api-Key` and carries every scope of its wallet.
+
+```javascript
+const provider = new Cx3Provider("https://cx3api.carbonx3.com", { apiKey: process.env.CX3_API_KEY });
+```
 
-Address = `0x` + last 20 bytes of `sha256(uncompressedPublicKey)`.
+**Development node.** `new Cx3Provider(devNodeUrl, { devNode: true })` talks to a development node that runs without authentication (its `/api/v1` routes).
 
-## ABI-bound methods
+**Credentials are required.** Without an application, an API key or `devNode: true`, the constructor throws `CREDENTIALS_REQUIRED`.
 
-Supports:
+**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`.
 
-1. Standard interface JSON (`methods.balanceOf.type = "view"`)
-2. Compiler flat ABI (`[{ type: "function", name, inputs, stateMutability }]`)
+## Reading chain data
 
-Positional args map to ABI input names:
+Public chain data, served by the gateway to every application (a development node answers `DAPP_ONLY`):
 
 ```javascript
-await token.balanceOf(owner);           // → { address: owner } or { account: owner }
-await token.transfer(to, amount);       // → { to, amount }
-await token.call("balanceOf", { account: owner });
+const status = await provider.getStatus();                               // { height, hash, timestamp, chainId }
+const { tokens } = await provider.getTokens(wallet.address);             // every token with this wallet's balance
+const page = await provider.getActivity(wallet.address, { limit: 20 });  // newest first, no block rewards
+const older = await provider.getActivity(wallet.address, { before: page.nextBefore });
+const { pairs } = await provider.getDexPairs();                          // CarbonFi pools
+const lp = await provider.getLpBalance(pairs[0].id, wallet.address);     // LP balance in one pool
+const { wit } = await provider.getWit(contractAddress);                  // CX3WASM interface (WIT)
 ```
 
-## Environment
+With the `read` scope:
 
-```bash
-CX3_NODE_URL=https://your-node
-CX3_INTERNAL_AUTH_USER=cx3-internal
-CX3_INTERNAL_AUTH_PASS=…
-CX3_API_KEY=cx3wk_…          # optional; empty = public (any wallet); set = that wallet only (X-Api-Key)
-CX3_PRIVATE_KEY=…   # 64-hex or 0x-prefixed
-CX3_CHAIN_ID=cx3-dev         # native transfer payload (default)
+| Method | Returns |
+|--------|---------|
+| `getBalance(address)`, `getBalanceAndNonce(address)`, `getNonce(address)`, `getPendingNonce(address)` | Native CX3 balance and nonces |
+| `getContractInfo(address)`, `getAbi(address)`, `listContracts({ limit, offset, owner, standard, type, live })` | Contract registry entries and ABIs |
+| `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 |
+
+## Contracts
+
+```javascript
+const token = await provider.getContract(address, null, wallet);  // ABI from the chain
+
+await token.balanceOf(owner);                        // view → read-only call
+await token.call("balanceOf", { address: owner });   // named parameters (CX30)
+const tx = await token.transfer(to, amount);         // transaction → wallet-signed send
+await tx.wait();
 ```
 
-## Package layout
+Supported ABI shapes:
+
+1. Standard interface JSON: `{ methods: { balanceOf: { type: "view", inputs: [...] } } }`
+2. Compiler flat ABI: `[{ type: "function", name, inputs, stateMutability }]`
+3. CX3WASM compiler ABI: `{ functions: [{ name, params, view }] }`
+
+`provider.getContract(address)` loads the ABI the chain calls the contract with: shape 2 for contracts compiled to CX3JS, shape 3 for CX3WASM. Built-in chain standards (ABI inputs `["params"]`) take one named object: `await lp.transfer({ to, amount })`. A contract handle created with a provider instead of a wallet can only read; its writes throw `NO_SIGNER`.
+
+## 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).
+
+- 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.
+
+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.
+
+## Deploying tokens
+
+```javascript
+const { Cx3TokenFactory } = require("@carbonx3/cx3.js");
 
+const factory = new Cx3TokenFactory(wallet);  // the application needs the deploy scope
+const result = await factory.deployCX30({ name: "My Token", symbol: "MTK", initialSupply: "0" });
+console.log(result.contractAddress);          // result.contract is a ready Contract handle
 ```
-CX3Web3JS/
-  index.js          # public API
-  index.d.ts
-  src/
-    provider.js
-    wallet.js
-    contract.js
-    factory.js
-    crypto.js
-    digest.js
-    …
-  test/
+
+| Helper | Standard |
+|--------|----------|
+| `deployCX30` | Fungible token |
+| `deployCX31` | Unit / accounting token |
+| `deployCX300` | Real-world asset |
+| `deployCX315` | Loyalty |
+| `deployCX3192` | Soulbound identity |
+| `deployCX337` … `deployCX341` | Green standards: CBAM proof, sustainability report, supply chain, materiality assessment, green claims |
+
+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`).
+
+## Private tokens
+
+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.
+- **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.
+
+```javascript
+const res = await factory.deployCX30({
+  name: "Team Credit",
+  symbol: "TEAMC",
+  initialSupply: "1000000",
+  visibility: "private",
+  authorizedWallets: ["0x…", "0x…"]  // up to 200; one signed addToWhitelist each after the deploy
+});
+// res.authorized → [{ wallet, success, txHash }]
+await res.contract.addToWhitelist("0xNew…", "");  // later, owner only; removeFromWhitelist removes one
 ```
 
-## License
+A private CX31, CX300, CX315 or CX3192 takes its CX3WebUI source as `sourceCode`; the green standards have no private variant. Private keeps a token out of other wallets' lists and hands, but it does not make it secret: blocks, transfers and contract calls stay readable on the chain, as on [CX3Scan](https://cx3scan.carbonx3.com).
+
+## Signing
+
+Digests are UTF-8 strings, hashed with SHA-256 and signed with secp256k1, byte-identical to what the Green Chain node verifies:
 
-UNLICENSED — Mersolution Technology Ltd.
+- **Deploy:** `deploy|{owner}|{standard}|{name}|{symbol}|{decimals}|{initialSupply}|{timestamp}`
+- **Contract send:** `{contractAddress}|{method}|{JSON.stringify(params)}|{fromAddress}|{timestamp}`
+- **Owner action:** `{action}|{address}|{owner}|{timestamp}`
+- **Native transfer:** `JSON.stringify({ type, fromAddress, toAddress, amount, nonce, timestamp, data, gasLimit, gasPrice, chainId })`, with 40-hex addresses and no `0x`
 
-## Docs
+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. An address is `0x` + the last 20 bytes of `sha256(uncompressedPublicKey)`.
 
-CX3Script documentation site (sidebar **cx3.js SDK**):
+The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `buildOwnerActionDigest`, `buildTransferPayload`, `signMessage`, `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`.
+
+```javascript
+const { Cx3HttpError } = require("@carbonx3/cx3.js");
+
+try {
+  await token.transfer(to, amount);
+} catch (err) {
+  if (err instanceof Cx3HttpError && err.status === 403) console.error("Not allowed:", err.code);
+  else throw err;
+}
+```
+
+| Code | Meaning |
+|------|---------|
+| `CREDENTIALS_REQUIRED` | No application, API key or `devNode` was given |
+| `INVALID_CLIENT_CREDENTIALS` | The client ID or secret is not in the `cx3app_…` / `cx3sec_…` format |
+| `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 |
+| `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 |
+| `BASIC_AUTH_UNSUPPORTED` | The `auth` option was used |
+
+## Browser applications
+
+This package is for Node.js servers. Web pages use the **CX3 IIFE** (`cx3.min.js`, `window.cx3`) together with the CX3Wallet extension: [download it](https://cx3script.com/download/cx3.min.js) and 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_API_KEY` | Legacy wallet API key |
+| `CX3_NODE_URL` | Gateway URL for `getDefaultProvider()` |
+| `CX3_CHAIN_ID` | Chain id in native transfer signatures (default `cx3-dev`) |
+
+## TypeScript
+
+Type declarations (`index.d.ts`) ship with the package.
+
+## Upgrading from 0.1.x
+
+CX3js is in beta (0.x), so a minor version may contain breaking changes. Version 0.2.0:
+
+- **Credentials are required.** The provider talks to the CX3Api gateway as an OAuth2 application (or with a wallet API key) and throws `CREDENTIALS_REQUIRED` without one. A development node without authentication needs `devNode: true`; 0.1.x used node routes under `/api/v1` by default.
+- **HTTP Basic was removed.** The `auth` option throws `BASIC_AUTH_UNSUPPORTED`, and `headers` cannot carry `Authorization` or `X-Api-Key`.
+- **Node.js 20.19 or later** is required (`@noble/secp256k1` 3.x).
+- **Fixes:** BigInt params are signed and sent as decimal strings, and `transferNative` sends the gas fields it signs.
+- **New:** public chain reads (`getStatus`, `getTokens`, `getActivity`, `getDexPairs`, `getLpBalance`, `getWit`), private tokens and `isValidTokenSymbol`.
+
+## Documentation
+
+- [CX3js SDK reference](https://cx3script.com/docs?doc=cx3js-sdk)
+- [Node.js after deploy](https://cx3script.com/docs?doc=node-after-deploy)
+- [CX3 IIFE for browsers](https://cx3script.com/docs?doc=cx3iife)
+- [CX3Script developer site](https://cx3script.com)
+- [CarbonX3 Green Chain](https://carbonx3.com/)
+
+## License
 
-- Monorepo: `CX3VM-WebSites/cx3docs/docs/cx3js-sdk.md`
-- Local: `/CX3VM-WebSites/docs?doc=cx3js-sdk`
+`UNLICENSED`: proprietary software of Mersolution Technology Ltd. Use is subject to the [CX3Script Terms of Use](https://cx3script.com/terms).

package/index.d.ts

@@ -18,15 +18,22 @@ export class Cx3TxError extends Cx3Error {
   constructor(message: string, code?: string, receipt?: unknown);
 }
 
-export interface Cx3Auth {
-  user: string;
-  pass: string;
-}
-
 export interface Cx3ProviderOptions {
-  apiPrefix?: string;
-  auth?: Cx3Auth;
+  /** OAuth2 client id (cx3app_…) from CX3WebUI → Settings → API → Applications; env CX3_CLIENT_ID */
+  clientId?: string;
+  /** OAuth2 client secret (cx3sec_…); env CX3_CLIENT_SECRET. Keep it on the server. */
+  clientSecret?: string;
+  /** ask for fewer scopes than the app has: "read", "write", "deploy" */
+  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 */
+  devNode?: 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) */
+  auth?: never;
+  /** extra headers; Authorization and X-Api-Key are dropped (use clientId / clientSecret or apiKey) */
   headers?: Record<string, string>;
   fetch?: typeof fetch;
   timeoutMs?: number;
@@ -38,16 +45,51 @@ export interface Cx3PageQuery {
   offset?: number;
 }
 
+export interface Cx3WalletToken {
+  address: string;
+  name?: string;
+  symbol?: string;
+  decimals?: number;
+  standard?: string;
+  /** null when the node could not read it */
+  balance: string | null;
+  totalSupply?: string;
+  paused?: boolean;
+  /** this wallet deployed it */
+  mine: boolean;
+  /** private token: listed for its owner, its authorized wallets and holders */
+  private?: boolean;
+  authorized?: boolean;
+}
+
 export class Cx3Provider {
   baseUrl: string;
   apiPrefix: string;
+  gateway: boolean;
+  devNode: boolean;
+  oauth: boolean;
+  clientId: string;
   apiKeyMode: "public" | "private" | "invalid";
+  authMode: "oauth" | "apiKey" | "devNode";
+  /** Throws CREDENTIALS_REQUIRED without clientId / clientSecret, apiKey or devNode */
   constructor(baseUrl: string, options?: Cx3ProviderOptions);
+  /** 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>;
   call(contractAddress: string, method: string, params?: object, sender?: string): Promise<any>;
   send(contractAddress: string, method: string, params?: object, extras?: object): Promise<any>;
   getAbi(address: string): Promise<any>;
+  /** WIT interface of a CX3WASM contract */
+  getWit(address: string): Promise<{ success: boolean; address: string; target: string | null; wit: string }>;
+  /** Chain head, with chainId from the gateway */
+  getStatus(): Promise<{ success: boolean; height: number; hash: string | null; timestamp: number | null; chainId?: string | null }>;
   getContractInfo(address: string): Promise<any>;
+  /** Private token (registry `metadata.visibility === "private"`); kept per address */
+  isPrivateToken(address: string): Promise<boolean>;
+  /** The owner (registry record) or a wallet the token's isWhitelisted view lists; false also for a token without such a list; null = no answer */
+  isTokenAuthorized(token: string, wallet: string): Promise<boolean | null>;
+  /** Throws Cx3Error PRIVATE_TOKEN_SENDER / PRIVATE_TOKEN_RECIPIENT for a transfer, transferFrom or mint of a private token between wallets that are not authorized */
+  checkPrivateTokenSend(contractAddress: string, method: string, params?: object, from?: string): Promise<void>;
   getContractState(address: string): Promise<any>;
   getContractSource(address: string): Promise<any>;
   getContractBytecode(address: string): Promise<any>;
@@ -61,7 +103,16 @@ export class Cx3Provider {
   getNonce(address: string): Promise<number>;
   getPendingNonce(address: string): Promise<any>;
   bindApiKey(address: string): Promise<any>;
-  listContracts(opts?: { limit?: number; offset?: number }): Promise<any>;
+  /** The gateway lists a private token only when the app's wallet is its owner or an authorized wallet */
+  listContracts(opts?: { limit?: number; offset?: number; viewer?: string; owner?: string; standard?: string; type?: string; live?: boolean }): Promise<any>;
+  /** Every registry token with this wallet's balance (gateway public read group) */
+  getTokens(address: string): Promise<{ success: boolean; address: string; tokens: Cx3WalletToken[]; total: number; unread: number }>;
+  /** Wallet history, newest first, without block rewards; next page with `{ before: page.nextBefore }` */
+  getActivity(address: string, opts?: { limit?: number; before?: string }): Promise<{ success: boolean; address: string; transactions: any[]; nextBefore: string | null; limit: number }>;
+  /** CarbonFi pools */
+  getDexPairs(): Promise<{ success: boolean; pairs: any[] }>;
+  /** 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>;
   getContract(address: string, abi?: unknown, signer?: Cx3Wallet | null): Promise<Contract>;
@@ -89,12 +140,14 @@ export class Cx3Wallet {
   signDeploy(fields: object): Promise<any>;
   signSend(contractAddress: string, method: string, params?: object): Promise<any>;
   signOwnerAction(action: string, address: string, owner?: string | null): Promise<any>;
-  sendTransaction(contractAddress: string, method: string, params?: object, opts?: object): Promise<TransactionResponse>;
+  /** 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>;
   pauseContract(address: string, owner?: string | null): Promise<any>;
   unpauseContract(address: string, owner?: string | null): Promise<any>;
   deleteContract(address: string, owner?: string | null): Promise<any>;
-  transferNative(to: string, amount: number | string, opts?: object): Promise<TransactionResponse>;
+  transferNative(to: string, amount: number | string, opts?: { nonce?: number; timestamp?: number; data?: unknown; gasLimit?: number; gasPrice?: number; chainId?: string; chainIdBind?: boolean; wait?: number }): Promise<TransactionResponse>;
   bindApiKey(address?: string): Promise<any>;
 }
 
@@ -114,13 +167,29 @@ export class Contract {
   [method: string]: any;
 }
 
+export interface Cx3TokenDeployFields {
+  name?: string;
+  symbol?: string;
+  decimals?: number;
+  initialSupply?: string | number | bigint;
+  target?: "CX3WASM" | "CX3JS";
+  sourceCode?: string;
+  metadata?: Record<string, string | number | boolean>;
+  /** "private": only the owner and authorizedWallets send, receive and see the token (CX30 rendered by the chain; CX31 / CX300 / CX315 / CX3192 need sourceCode) */
+  visibility?: "public" | "private";
+  /** up to 200 wallets, each added with one signed addToWhitelist after the deploy */
+  authorizedWallets?: string[];
+  [k: string]: unknown;
+}
+
 export class Cx3TokenFactory {
   constructor(wallet: Cx3Wallet);
-  deployCX30(fields?: object): Promise<any>;
-  deployCX31(fields?: object): Promise<any>;
-  deployCX300(fields?: object): Promise<any>;
-  deployCX315(fields?: object): Promise<any>;
-  deployCX3192(fields?: object): Promise<any>;
+  /** 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>;
@@ -144,6 +213,8 @@ export function getDefaultProvider(options?: Cx3ProviderOptions & { url?: string
 export function readCallValue(response: any): unknown;
 export function normalizeAddress(addr: string): string;
 export function walletApiKeyMode(key?: string | null): "public" | "private" | "invalid";
+/** BigInt → decimal string, recursively (params are signed and sent in this form) */
+export function toJsonSafe<T>(value: T): unknown;
 export function ensure0x(hex: string): string;
 export function strip0x(hex: string): string;
 export function buildDeployDigest(fields: object): string;
@@ -155,3 +226,5 @@ export function privateKeyToAddress(privateKey: string | Uint8Array | Buffer): s
 export function createPrivateKey(): string;
 export function normalizeAbi(abi: unknown): Record<string, any>;
 export function argsToParams(inputs: any[], args: any[]): object;
+/** Green Chain token symbol rule: capital letters A-Z and digits 0-9 only. */
+export function isValidTokenSymbol(symbol: unknown): boolean;

package/index.js

@@ -1,7 +1,7 @@
 "use strict";
 
 const { Cx3Provider } = require("./src/provider");
-const { Cx3Wallet } = require("./src/wallet");
+const { Cx3Wallet, isValidTokenSymbol } = require("./src/wallet");
 const { Contract } = require("./src/contract");
 const { Cx3TokenFactory } = require("./src/factory");
 const { TransactionResponse } = require("./src/transaction");
@@ -11,7 +11,8 @@ const {
     normalizeAddress,
     ensure0x,
     strip0x,
-    walletApiKeyMode
+    walletApiKeyMode,
+    toJsonSafe
 } = require("./src/utils");
 const {
     buildDeployDigest,
@@ -26,10 +27,11 @@ const {
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 /**
- * Convenience: provider from env `CX3_NODE_URL` (+ optional Basic auth env).
+ * Convenience: provider from `options.url` or env `CX3_NODE_URL` — the CX3Api gateway
+ * (https://cx3api.carbonx3.com) or a development node that runs without auth.
  */
 function getDefaultProvider(options = {}) {
     const url = options.url || process.env.CX3_NODE_URL;
@@ -55,6 +57,7 @@ module.exports = {
     ensure0x,
     strip0x,
     walletApiKeyMode,
+    toJsonSafe,
     buildDeployDigest,
     buildSendDigest,
     buildOwnerActionDigest,
@@ -63,5 +66,6 @@ module.exports = {
     privateKeyToAddress,
     createPrivateKey,
     normalizeAbi,
-    argsToParams
+    argsToParams,
+    isValidTokenSymbol
 };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@carbonx3/cx3.js",
-  "version": "0.1.0",
-  "description": "CarbonX3 Green Chain JavaScript SDK (CX3js) - Provider / Wallet / Contract over REST + JSON",
+  "version": "0.2.0",
+  "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": {
     "access": "public"
   },
@@ -23,16 +24,23 @@
     "green-chain",
     "cx3js",
     "cx3wasm",
+    "cx3script",
+    "blockchain",
+    "web3",
+    "smart-contracts",
+    "tokens",
+    "oauth2",
+    "secp256k1",
     "sdk"
   ],
-  "author": "Mersolution Technology Ltd.",
+  "author": "Mersolution Technology Ltd. (https://cx3script.com)",
   "license": "UNLICENSED",
   "type": "commonjs",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0"
   },
   "dependencies": {
-    "@noble/secp256k1": "^1.7.1"
+    "@noble/secp256k1": "^3.2.0"
   },
   "exports": {
     ".": {

package/src/abi.js

@@ -99,6 +99,13 @@ function argsToParams(inputs, args) {
             "BAD_ARGS"
         );
     }
+    // Built-in chain standards declare `inputs: ["params"]`: one named object
+    if (list.length === 1 && list[0] === "params") {
+        throw new Cx3Error(
+            "This method takes one named params object, e.g. transfer({ to, amount })",
+            "BAD_ARGS"
+        );
+    }
     if (args.length > list.length) {
         throw new Cx3Error(
             `Too many arguments: expected ${list.length}, got ${args.length}`,
@@ -108,7 +115,7 @@ function argsToParams(inputs, args) {
     const params = {};
     for (let i = 0; i < args.length; i++) {
         const input = list[i];
-        const key = input.name || input.key || `arg${i}`;
+        const key = typeof input === "string" ? input : (input.name || input.key || `arg${i}`);
         params[key] = args[i];
     }
     return params;