@carbonx3/cx3.js 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @carbonx3/cx3.js — CarbonX3 Green Chain SDK
+
+Official JavaScript client (**CX3js**) for **CarbonX3 Green Chain**.
+
+Talks to the node over **REST + JSON** (`/api/v1/...`) with named method params.
+
+| `@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) |
+
+## Install
+
+```bash
+# when published
+npm install @carbonx3/cx3.js
+
+# from monorepo root
+npm install ./CX3Web3JS
+
+# or inside another package
+npm install file:../CX3Web3JS
+```
+
+Node.js **18+** (native `fetch`).
+
+## 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 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);
+
+const cx3Balance = await provider.getBalance(wallet.address);
+
+// Write
+const tx = await token.transfer("0xRecipient…", "1000000000000000000");
+await tx.wait();
+
+await wallet.pauseContract(process.env.CONTRACT_ADDRESS);
+await wallet.transferNative("0xRecipient…", 1);
+
+// Deploy CX30
+const factory = new Cx3TokenFactory(wallet);
+const deployed = await factory.deployCX30({
+  name: "My Token",
+  symbol: "MTK",
+  initialSupply: "0",
+  target: "CX3WASM"
+});
+console.log(deployed.contractAddress);
+```
+
+## Signing (important)
+
+Digests are **UTF-8 strings**, then `sha256` + **secp256k1** (same as CX3Wallet):
+
+- 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)`
+
+Address = `0x` + last 20 bytes of `sha256(uncompressedPublicKey)`.
+
+## ABI-bound methods
+
+Supports:
+
+1. Standard interface JSON (`methods.balanceOf.type = "view"`)
+2. Compiler flat ABI (`[{ type: "function", name, inputs, stateMutability }]`)
+
+Positional args map to ABI input names:
+
+```javascript
+await token.balanceOf(owner);           // → { address: owner } or { account: owner }
+await token.transfer(to, amount);       // → { to, amount }
+await token.call("balanceOf", { account: owner });
+```
+
+## Environment
+
+```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)
+```
+
+## Package layout
+
+```
+CX3Web3JS/
+  index.js          # public API
+  index.d.ts
+  src/
+    provider.js
+    wallet.js
+    contract.js
+    factory.js
+    crypto.js
+    digest.js
+    …
+  test/
+```
+
+## License
+
+UNLICENSED — Mersolution Technology Ltd.
+
+## Docs
+
+CX3Script documentation site (sidebar **cx3.js SDK**):
+
+- Monorepo: `CX3VM-WebSites/cx3docs/docs/cx3js-sdk.md`
+- Local: `/CX3VM-WebSites/docs?doc=cx3js-sdk`

package/index.d.ts

@@ -0,0 +1,157 @@
+export const VERSION: string;
+
+export class Cx3Error extends Error {
+  code: string;
+  details: unknown;
+  constructor(message: string, code?: string, details?: unknown);
+}
+
+export class Cx3HttpError extends Cx3Error {
+  status: number;
+  body: unknown;
+  constructor(message: string, status: number, body?: unknown);
+}
+
+export class Cx3TxError extends Cx3Error {
+  receipt: unknown;
+  txHash?: string;
+  constructor(message: string, code?: string, receipt?: unknown);
+}
+
+export interface Cx3Auth {
+  user: string;
+  pass: string;
+}
+
+export interface Cx3ProviderOptions {
+  apiPrefix?: string;
+  auth?: Cx3Auth;
+  apiKey?: string;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export interface Cx3PageQuery {
+  type?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export class Cx3Provider {
+  baseUrl: string;
+  apiPrefix: string;
+  apiKeyMode: "public" | "private" | "invalid";
+  constructor(baseUrl: string, options?: Cx3ProviderOptions);
+  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>;
+  getContractInfo(address: string): Promise<any>;
+  getContractState(address: string): Promise<any>;
+  getContractSource(address: string): Promise<any>;
+  getContractBytecode(address: string): Promise<any>;
+  getEvents(address: string, typeOrOpts?: string | Cx3PageQuery, opts?: Cx3PageQuery): Promise<any>;
+  getHolders(address: string, opts?: Cx3PageQuery): Promise<any>;
+  getTransfers(address: string, limitOrOpts?: number | Cx3PageQuery, opts?: Cx3PageQuery): Promise<any>;
+  getTransferByHash(address: string, hash: string): Promise<any>;
+  getAddressTransactions(address: string, limit?: number): Promise<any>;
+  getBalanceAndNonce(address: string): Promise<any>;
+  getBalance(address: string): Promise<any>;
+  getNonce(address: string): Promise<number>;
+  getPendingNonce(address: string): Promise<any>;
+  bindApiKey(address: string): Promise<any>;
+  listContracts(opts?: { limit?: number; offset?: number }): Promise<any>;
+  getTxStatus(txHash: string): Promise<any>;
+  waitForTransaction(txHash: string, opts?: object): Promise<any>;
+  getContract(address: string, abi?: unknown, signer?: Cx3Wallet | null): Promise<Contract>;
+}
+
+export class Cx3Wallet {
+  address: string;
+  publicKey: string;
+  provider: Cx3Provider | null;
+  constructor(privateKey: string | Uint8Array | Buffer, provider?: Cx3Provider | null);
+  static createRandom(provider?: Cx3Provider | null): Cx3Wallet;
+  connect(provider: Cx3Provider): Cx3Wallet;
+  getAddress(): string;
+  signMessage(message: string | Uint8Array): Promise<{
+    signature: string;
+    r: string;
+    s: null;
+    v: number;
+    publicKey: string;
+    senderPublicKey: string;
+    publicKeyUncompressed: string;
+    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>;
+  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>;
+  bindApiKey(address?: string): Promise<any>;
+}
+
+export class Contract {
+  address: string;
+  target: string | null;
+  interface: Record<string, { name: string; kind: "view" | "tx"; inputs: any[] }>;
+  constructor(address: string, abi: unknown, runner: Cx3Provider | Cx3Wallet);
+  connect(runner: Cx3Provider | Cx3Wallet): Contract;
+  call(method: string, params?: object): Promise<any>;
+  send(method: string, params?: object, opts?: object): Promise<TransactionResponse>;
+  getEvents(type?: string): Promise<any>;
+  getInfo(): Promise<any>;
+  getTransfers(opts?: Cx3PageQuery): Promise<any>;
+  getHolders(opts?: Cx3PageQuery): Promise<any>;
+  getState(): Promise<any>;
+  [method: string]: any;
+}
+
+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>;
+  deployCX337(fields?: object): Promise<any>;
+  deployCX338(fields?: object): Promise<any>;
+  deployCX339(fields?: object): Promise<any>;
+  deployCX340(fields?: object): Promise<any>;
+  deployCX341(fields?: object): Promise<any>;
+}
+
+export class TransactionResponse {
+  raw: any;
+  success: boolean;
+  txHash: string | null;
+  hash: string | null;
+  blockHeight?: number;
+  contractAddress: string | null;
+  async: boolean;
+  status: string;
+  wait(opts?: object): Promise<any>;
+}
+
+export function getDefaultProvider(options?: Cx3ProviderOptions & { url?: string }): Cx3Provider;
+export function readCallValue(response: any): unknown;
+export function normalizeAddress(addr: string): string;
+export function walletApiKeyMode(key?: string | null): "public" | "private" | "invalid";
+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;
+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;

package/index.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const { Cx3Provider } = require("./src/provider");
+const { Cx3Wallet } = require("./src/wallet");
+const { Contract } = require("./src/contract");
+const { Cx3TokenFactory } = require("./src/factory");
+const { TransactionResponse } = require("./src/transaction");
+const { Cx3Error, Cx3HttpError, Cx3TxError } = require("./src/errors");
+const {
+    readCallValue,
+    normalizeAddress,
+    ensure0x,
+    strip0x,
+    walletApiKeyMode
+} = require("./src/utils");
+const {
+    buildDeployDigest,
+    buildSendDigest,
+    buildOwnerActionDigest,
+    buildTransferPayload
+} = require("./src/digest");
+const {
+    signMessage,
+    privateKeyToAddress,
+    createPrivateKey
+} = require("./src/crypto");
+const { normalizeAbi, argsToParams } = require("./src/abi");
+
+const VERSION = "0.1.0";
+
+/**
+ * Convenience: provider from env `CX3_NODE_URL` (+ optional Basic auth env).
+ */
+function getDefaultProvider(options = {}) {
+    const url = options.url || process.env.CX3_NODE_URL;
+    return new Cx3Provider(url, options);
+}
+
+module.exports = {
+    VERSION,
+    // Core
+    Cx3Provider,
+    Cx3Wallet,
+    Contract,
+    Cx3TokenFactory,
+    TransactionResponse,
+    // Errors
+    Cx3Error,
+    Cx3HttpError,
+    Cx3TxError,
+    // Helpers
+    getDefaultProvider,
+    readCallValue,
+    normalizeAddress,
+    ensure0x,
+    strip0x,
+    walletApiKeyMode,
+    buildDeployDigest,
+    buildSendDigest,
+    buildOwnerActionDigest,
+    buildTransferPayload,
+    signMessage,
+    privateKeyToAddress,
+    createPrivateKey,
+    normalizeAbi,
+    argsToParams
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@carbonx3/cx3.js",
+  "version": "0.1.0",
+  "description": "CarbonX3 Green Chain JavaScript SDK (CX3js) - Provider / Wallet / Contract over REST + JSON",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/unit.test.js",
+    "test:live": "node test/live.smoke.js"
+  },
+  "keywords": [
+    "carbonx3",
+    "cx3",
+    "green-chain",
+    "cx3js",
+    "cx3wasm",
+    "sdk"
+  ],
+  "author": "Mersolution Technology Ltd.",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@noble/secp256k1": "^1.7.1"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  }
+}

package/src/abi.js

@@ -0,0 +1,117 @@
+"use strict";
+
+const { Cx3Error } = require("./errors");
+const { isPlainObject } = require("./utils");
+
+/**
+ * Normalize CX3 ABI variants into a map:
+ *   { [methodName]: { name, kind: "view"|"tx", inputs: [{name,type}] } }
+ *
+ * Supported shapes:
+ * 1) Interface JSON: `{ methods: { balanceOf: { type:"view", inputs:[...] } } }`
+ * 2) Compiler flat ABI: `[{ type:"function", name, inputs, stateMutability }]`
+ * 3) WASM object: `{ functions: [...] }`
+ */
+function normalizeAbi(abi) {
+    const map = Object.create(null);
+    if (!abi) return map;
+
+    if (Array.isArray(abi)) {
+        for (const entry of abi) {
+            if (!entry || !entry.name) continue;
+            if (entry.type && entry.type !== "function" && entry.type !== "view" && entry.type !== "tx") {
+                continue;
+            }
+            map[entry.name] = {
+                name: entry.name,
+                kind: inferKind(entry),
+                inputs: entry.inputs || entry.params || []
+            };
+        }
+        return map;
+    }
+
+    if (abi.methods && isPlainObject(abi.methods)) {
+        for (const [name, def] of Object.entries(abi.methods)) {
+            map[name] = {
+                name,
+                kind: inferKind(def),
+                inputs: (def && def.inputs) || []
+            };
+        }
+        return map;
+    }
+
+    if (Array.isArray(abi.functions)) {
+        return normalizeAbi(abi.functions);
+    }
+
+    // Bare object of method defs
+    if (isPlainObject(abi)) {
+        for (const [name, def] of Object.entries(abi)) {
+            if (!def || typeof def !== "object") continue;
+            if (name === "name" || name === "version" || name === "description") continue;
+            map[name] = {
+                name,
+                kind: inferKind(def),
+                inputs: def.inputs || def.params || []
+            };
+        }
+    }
+    return map;
+}
+
+function inferKind(def) {
+    if (!def) return "tx";
+    if (isViewMutability(def)) return "view";
+    const t = String(def.type || def.kind || "").toLowerCase();
+    if (t === "view" || t === "pure") return "view";
+    if (t === "tx" || t === "nonpayable" || t === "payable") return "tx";
+    if (t === "function") return isViewMutability(def) ? "view" : "tx";
+    // WASM compiler ABI shape (`{ functions: [{ name, params, view, ... }] }`,
+    // see CX3VM WITGenerator.extractFunctions) has no `type`/`stateMutability`
+    // string at all — read-only methods are flagged with a plain boolean
+    // `view` field instead. Without this check every WASM function (including
+    // balanceOf/allowance/etc.) falls through to "tx", so Contract._invoke()
+    // routes reads through wallet.sendTransaction() instead of provider.call().
+    if (typeof def.view === "boolean") return def.view ? "view" : "tx";
+    return "tx";
+}
+
+function isViewMutability(def) {
+    const m = String(def.stateMutability || def.mutability || "").toLowerCase();
+    return m === "view" || m === "pure" || m === "readonly";
+}
+
+/**
+ * Map positional args → named params object using ABI inputs.
+ * Also accepts a single plain object as the only argument.
+ */
+function argsToParams(inputs, args) {
+    const list = Array.isArray(inputs) ? inputs : [];
+    if (args.length === 1 && isPlainObject(args[0])) {
+        return { ...args[0] };
+    }
+    if (list.length === 0) {
+        if (args.length === 0) return {};
+        throw new Cx3Error(
+            `Method expects named params object or ABI inputs; got ${args.length} positional arg(s)`,
+            "BAD_ARGS"
+        );
+    }
+    if (args.length > list.length) {
+        throw new Cx3Error(
+            `Too many arguments: expected ${list.length}, got ${args.length}`,
+            "BAD_ARGS"
+        );
+    }
+    const params = {};
+    for (let i = 0; i < args.length; i++) {
+        const input = list[i];
+        const key = input.name || input.key || `arg${i}`;
+        params[key] = args[i];
+    }
+    return params;
+}
+
+module.exports = { normalizeAbi, argsToParams, inferKind };

package/src/contract.js

@@ -0,0 +1,113 @@
+"use strict";
+
+const { normalizeAbi, argsToParams } = require("./abi");
+const { Cx3Error } = require("./errors");
+
+/**
+ * Contract handle with ABI-bound methods.
+ *
+ *   const token = new Contract(addr, abi, wallet);
+ *   await token.balanceOf(owner);          // view → /contract/call
+ *   const tx = await token.transfer(to, amount); // tx → signed /contract/send
+ *   await tx.wait();
+ */
+class Contract {
+    /**
+     * @param {string} address
+     * @param {object|array} abi
+     * @param {import('./provider').Cx3Provider|import('./wallet').Cx3Wallet} runner  provider or wallet
+     */
+    constructor(address, abi, runner) {
+        if (!address) throw new Cx3Error("contract address required", "NO_ADDRESS");
+        if (!runner) throw new Cx3Error("provider or wallet required", "NO_RUNNER");
+
+        this.address = address;
+        this.target = null;
+        this.interface = normalizeAbi(abi);
+        this._runner = runner;
+
+        const self = this;
+        for (const name of Object.keys(this.interface)) {
+            if (name in this) continue;
+            this[name] = async function (...args) {
+                return self._invoke(name, args);
+            };
+        }
+    }
+
+    get provider() {
+        return this._runner.provider || this._runner;
+    }
+
+    get signer() {
+        return this._runner.signMessage ? this._runner : null;
+    }
+
+    connect(runner) {
+        const c = new Contract(this.address, { methods: rebuildMethods(this.interface) }, runner);
+        c.target = this.target;
+        return c;
+    }
+
+    async _invoke(methodName, args) {
+        const def = this.interface[methodName];
+        if (!def) throw new Cx3Error(`Unknown method: ${methodName}`, "UNKNOWN_METHOD");
+        const params = argsToParams(def.inputs, args);
+
+        if (def.kind === "view") {
+            return this.call(methodName, params);
+        }
+        return this.send(methodName, params);
+    }
+
+    async call(method, params = {}) {
+        const provider = this.provider;
+        const sender = this.signer ? this.signer.address : "";
+        const res = await provider.call(this.address, method, params, sender);
+        return res.value !== undefined ? res.value : res;
+    }
+
+    async send(method, params = {}, opts = {}) {
+        const signer = this.signer;
+        if (!signer) {
+            throw new Cx3Error(
+                `Method ${method} requires a Cx3Wallet signer (pass wallet as runner)`,
+                "NO_SIGNER"
+            );
+        }
+        return signer.sendTransaction(this.address, method, params, opts);
+    }
+
+    async getEvents(type = "") {
+        return this.provider.getEvents(this.address, type);
+    }
+
+    async getInfo() {
+        return this.provider.getContractInfo(this.address);
+    }
+
+    async getTransfers(opts) {
+        return this.provider.getTransfers(this.address, opts);
+    }
+
+    async getHolders(opts) {
+        return this.provider.getHolders(this.address, opts);
+    }
+
+    async getState() {
+        return this.provider.getContractState(this.address);
+    }
+}
+
+function rebuildMethods(iface) {
+    const methods = {};
+    for (const [name, def] of Object.entries(iface)) {
+        methods[name] = {
+            type: def.kind,
+            inputs: def.inputs
+        };
+    }
+    return methods;
+}
+
+module.exports = { Contract };