@carbonx3/cx3.js 0.1.1 → 0.3.0

package/README.md

@@ -1,100 +1,288 @@
 # @carbonx3/cx3.js
 
-Official **Node.js** client (**CX3js**) for [CarbonX3 Green Chain](https://carbonx3.com/).
+[![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/).
 
-The **browser** client is the **CX3 IIFE**: `<script src="cx3.min.js"></script>` (`window.cx3`). Do not `require` this package in a page.
+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.
 
-| Export | Role |
-|--------|------|
-| `Cx3Provider` | HTTP client (`{node}/api/v1`) |
-| `Cx3Wallet` | secp256k1 signing (deploy / send / native CX3) |
-| `Contract` / `provider.getContract` | ABI-bound calls |
-| `Cx3TokenFactory` | Standard deploys (CX30–CX3192, CX337–CX341) |
+> **Network status:** CarbonX3 Green Chain currently runs as a development network (devnet, chain id `cx3-dev-2`). Devnet CX3, tokens and contracts are test data with no monetary value and may be cleared when the devnet is reset.
 
-## Install
+## 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
 npm install @carbonx3/cx3.js
 ```
 
-Node.js **18+** (native `fetch`).
+## Create an application
+
+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) |
+
+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 } = require("@carbonx3/cx3.js");
+const { Cx3Provider, Cx3Wallet } = require("@carbonx3/cx3.js");
 
-const provider = new Cx3Provider("https://your-green-chain-node");
+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);
 
-const token = await provider.getContract(process.env.CONTRACT_ADDRESS, null, wallet);
-const balance = await token.balanceOf(wallet.address);
+async function main() {
+  // Native CX3 balance
+  console.log(await provider.getBalance(wallet.address));
 
-const tx = await token.transfer("0xRecipient…", "1000000000000000000");
-await tx.wait();
+  // 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));
+
+  // Wallet-signed token transfer (BigInt or decimal string)
+  const tx = await token.transfer("0xRecipient…", 10n ** 18n);
+  await tx.wait();
 
-const factory = new Cx3TokenFactory(wallet);
-const deployed = await factory.deployCX30({
-  name: "My Token",
-  symbol: "MTK",
-  initialSupply: "0",
-  target: "CX3WASM"
+  // Native CX3 transfer
+  await wallet.transferNative("0xRecipient…", 1.5);
+}
+
+main().catch((err) => {
+  console.error(err.code || err.name, err.message);
+  process.exitCode = 1;
 });
-console.log(deployed.contractAddress);
 ```
 
-## Connect
+ES modules work too: `import { Cx3Provider, Cx3Wallet } from "@carbonx3/cx3.js";`. The remaining examples assume an `async` context.
+
+## Authentication
+
+**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`.
+
+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 });
+```
+
+**Development node.** `new Cx3Provider(devNodeUrl, { devNode: true })` talks to a development node that runs without authentication (its `/api/v1` routes).
 
-**1. Green Chain node (usual case)** — pass the node URL only. No username, password, or API key.
+**Credentials are required.** Without an application, an API key or `devNode: true`, the constructor throws `CREDENTIALS_REQUIRED`.
+
+**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`.
+
+## Reading chain data
+
+Public chain data, served by the gateway to every application (a development node answers `DAPP_ONLY`):
 
 ```javascript
-const provider = new Cx3Provider("https://your-green-chain-node");
+const status = await provider.getStatus();                               // { height, hash, timestamp, chainId, genesisHash }
+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)
 ```
 
-**2. Your own node** — add HTTP Basic **only if that node requires it**. If it does not, skip this and keep option 1.
+With the `read` scope:
+
+| 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 provider = new Cx3Provider("https://your-node", {
-  auth: {
-    user: process.env.CX3_INTERNAL_AUTH_USER,
-    pass: process.env.CX3_INTERNAL_AUTH_PASS
-  }
-});
+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();
+```
+
+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
 ```
 
-### Optional wallet API key
+| 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
+```
 
-Leave unset for **public** access (any wallet). Set a `cx3wk_…` key only to lock this client to that wallet. Never put an API key in browser JavaScript.
+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**, then `sha256` + **secp256k1**:
+Digests are UTF-8 strings, hashed with SHA-256 and signed with secp256k1, byte-identical to what the Green Chain node verifies. Each kind starts with its own prefix (signing domains), so a signature of one kind never verifies as another; `chainId` and `genesisHash` are the network's (`provider.getChainIdentity()`, fetched by the wallet methods themselves) and addresses are lower-case `0x` + 40 hex:
+
+- **Deploy:** `CX3_DEPLOY_V1|` + `JSON.stringify([chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, timestamp])`
+- **Contract send:** `CX3_CALL_V1|` + `JSON.stringify([chainId, genesisHash, contractAddress, method, params, fromAddress, timestamp])`. The chain checks this signature again inside the relayed transaction: a call runs as your wallet only with it.
+- **Owner action:** `CX3_OWNER_V1|` + `JSON.stringify([chainId, genesisHash, action, address, owner, timestamp])`
+- **Site message:** `0x19` + `"CX3 Signed Message:\n"` + UTF-8 length + message (`signPersonalMessage`), the way the CX3Wallet extension and app sign `cx3_sign_message`
+- **Native transfer:** `JSON.stringify({ type, fromAddress, toAddress, amount, nonce, timestamp, data, gasLimit, gasPrice, chainId, genesisHash })`, with 40-hex addresses and no `0x`; `chainId` and `genesisHash` (`0x` + 64 hex) are the network's, from `provider.getChainIdentity()`
 
-- Deploy: `deploy|{owner}|{standard}|{name}|{symbol}|{decimals}|{initialSupply}|{timestamp}`
-- Send: `{contractAddress}|{method}|{JSON.stringify(params)}|{fromAddress}`
-- Owner: `{action}|{address}|{owner}|{timestamp}`
-- Native CX3: `wallet.transferNative(to, amount)`
+BigInt values in params are converted to decimal strings before signing, and exactly those params are sent. Signatures carry a timestamp and are accepted within ±5 minutes of the node's clock; a native transfer is taken only by a block within 10 minutes of its timestamp. The genesis hash ties a native transfer to one network and one genesis: after a chain reset, a transfer signed before it no longer verifies. An address is `0x` + the last 20 bytes of `sha256(uncompressedPublicKey)`.
 
-Address = `0x` + last 20 bytes of `sha256(uncompressedPublicKey)`.
+The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `buildOwnerActionDigest` (each takes the identity as its last argument), `buildTransferPayload`, `personalMessageBytes`, `signMessage` (signs a digest as given), `signPersonalMessage`, `privateKeyToAddress` and `createPrivateKey`.
 
-## ABI-bound methods
+## Error handling
 
-1. Standard interface JSON (`methods.balanceOf.type = "view"`)
-2. Compiler flat ABI (`[{ type: "function", name, inputs, stateMutability }]`)
+Every error is a `Cx3Error` with a `code`. `Cx3HttpError` adds the HTTP `status` and the response `body`; `Cx3TxError` adds the transaction `receipt`.
 
 ```javascript
-await token.balanceOf(owner);
-await token.transfer(to, amount);
-await token.call("balanceOf", { account: owner });
+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;
+}
 ```
 
-## Docs
+| 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 |
+| `NO_CHAIN_IDENTITY` | The network's chain id or genesis hash is unavailable; a native transfer is not signed without them |
+
+## Browser applications
+
+This package is for Node.js servers. Web pages use the **CX3 IIFE** (`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()` |
+
+## TypeScript
+
+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:
+
+- **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.
+
+## 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](https://cx3script.com/docs?doc=cx3js-sdk)
+- [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
 
-UNLICENSED — Mersolution Technology Ltd.
+`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,53 @@ 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 and genesisHash from the gateway */
+  getStatus(): Promise<{ success: boolean; height: number; hash: string | null; timestamp: number | null; chainId?: string | null; genesisHash?: string | null }>;
+  /** The network identity a native transfer signs over; throws NO_CHAIN_IDENTITY when unavailable */
+  getChainIdentity(): Promise<{ chainId: string; genesisHash: string }>;
   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 +105,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>;
@@ -86,15 +139,20 @@ export class Cx3Wallet {
     derivedAddress: string;
     hash: string;
   }>;
-  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 site message the way the CX3Wallet extension and app sign it (0x19 "CX3 Signed Message:\n" prefix) */
+  signPersonalMessage(message: string): Promise<any>;
+  /** Typed digests (CX3_DEPLOY_V1 / CX3_CALL_V1 / CX3_OWNER_V1) bound to the network's chainId + genesisHash (from the provider unless given in opts) */
+  signDeploy(fields: object, opts?: Cx3ChainIdentity): Promise<any>;
+  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>;
+  /** 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; genesisHash?: string; wait?: number }): Promise<TransactionResponse>;
   bindApiKey(address?: string): Promise<any>;
 }
 
@@ -114,13 +172,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,14 +218,27 @@ 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;
-export function buildSendDigest(contractAddress: string, method: string, params: object, fromAddress: string, timestamp?: number | string): string;
-export function buildOwnerActionDigest(action: string, address: string, owner: string, timestamp: number): string;
+/** The network a typed digest or a native transfer is bound to (provider.getChainIdentity()) */
+export interface Cx3ChainIdentity { chainId?: string; genesisHash?: string }
+/** CX3_DEPLOY_V1|[chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, timestamp] */
+export function buildDeployDigest(fields: object, identity: Cx3ChainIdentity): string;
+/** CX3_CALL_V1|[chainId, genesisHash, contract, method, params, from, timestamp] */
+export function buildSendDigest(contractAddress: string, method: string, params: object, fromAddress: string, timestamp: number, identity: Cx3ChainIdentity): string;
+/** CX3_OWNER_V1|[chainId, genesisHash, action, address, owner, timestamp] */
+export function buildOwnerActionDigest(action: string, address: string, owner: string, timestamp: number, identity: Cx3ChainIdentity): string;
+/** 0x19 "CX3 Signed Message:\n" + UTF-8 length + message: what a wallet signs for a site message */
+export function personalMessageBytes(message: string): Uint8Array;
+export function signPersonalMessage(message: string, privateKey: string | Uint8Array | Buffer): Promise<any>;
+/** Native TRANSFER payload; fields.chainId and fields.genesisHash are required */
 export function buildTransferPayload(fields: object): string;
 export function signMessage(message: string | Uint8Array, privateKey: string | Uint8Array | Buffer): Promise<any>;
 export function privateKeyToAddress(privateKey: string | Uint8Array | Buffer): string;
 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,25 +11,29 @@ const {
     normalizeAddress,
     ensure0x,
     strip0x,
-    walletApiKeyMode
+    walletApiKeyMode,
+    toJsonSafe
 } = require("./src/utils");
 const {
     buildDeployDigest,
     buildSendDigest,
     buildOwnerActionDigest,
-    buildTransferPayload
+    buildTransferPayload,
+    personalMessageBytes
 } = require("./src/digest");
 const {
     signMessage,
+    signPersonalMessage,
     privateKeyToAddress,
     createPrivateKey
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.1.1";
+const VERSION = "0.3.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,13 +59,17 @@ module.exports = {
     ensure0x,
     strip0x,
     walletApiKeyMode,
+    toJsonSafe,
     buildDeployDigest,
     buildSendDigest,
     buildOwnerActionDigest,
     buildTransferPayload,
+    personalMessageBytes,
     signMessage,
+    signPersonalMessage,
     privateKeyToAddress,
     createPrivateKey,
     normalizeAbi,
-    argsToParams
+    argsToParams,
+    isValidTokenSymbol
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@carbonx3/cx3.js",
-  "version": "0.1.1",
-  "description": "CarbonX3 Green Chain JavaScript SDK (CX3js) - Provider / Wallet / Contract over REST + JSON",
-  "homepage": "https://cx3script.com/docs?doc=cx3js-sdk",
+  "version": "0.3.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"
   },
@@ -24,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": {
     ".": {