@carbonx3/cx3.js 0.1.0

package/src/crypto.js

@@ -0,0 +1,90 @@
+"use strict";
+
+const crypto = require("crypto");
+const secp = require("@noble/secp256k1");
+const { strip0x, ensure0x } = require("./utils");
+const { Cx3Error } = require("./errors");
+
+function sha256(data) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    return crypto.createHash("sha256").update(buf).digest();
+}
+
+function privateKeyToBytes(input) {
+    if (input instanceof Uint8Array || Buffer.isBuffer(input)) {
+        if (input.length !== 32) throw new Cx3Error("Invalid private key length", "INVALID_PRIVATE_KEY");
+        return Buffer.from(input);
+    }
+    const hex = strip0x(String(input || "")).toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+        throw new Cx3Error("Invalid private key hex", "INVALID_PRIVATE_KEY");
+    }
+    return Buffer.from(hex, "hex");
+}
+
+function privateKeyToPublicKey(privateKeyInput, compressed = true) {
+    const priv = privateKeyToBytes(privateKeyInput);
+    const pub = secp.getPublicKey(priv, compressed);
+    return Buffer.from(pub);
+}
+
+/**
+ * Address derivation matches CX3Wallet / Green Chain:
+ * address = 0x + last 20 bytes of sha256(uncompressed_pubkey)
+ */
+function privateKeyToAddress(privateKeyInput) {
+    const pubUncompressed = privateKeyToPublicKey(privateKeyInput, false);
+    const hash = sha256(pubUncompressed);
+    return ensure0x(hash.slice(-20).toString("hex"));
+}
+
+/**
+ * Sign a UTF-8 digest string (or bytes).
+ * Returns compact r||s hex (64 bytes) + compressed public key — same shape as CX3Wallet.
+ */
+async function signMessage(message, privateKeyInput) {
+    const priv = privateKeyToBytes(privateKeyInput);
+    const msgBytes = typeof message === "string"
+        ? Buffer.from(message, "utf8")
+        : Buffer.from(message);
+    const msgHash = sha256(msgBytes);
+    const signed = await secp.sign(msgHash, priv, { der: false, recovered: true });
+    const sigBytes = Array.isArray(signed) ? signed[0] : signed;
+    const recovery = Array.isArray(signed) ? signed[1] : (signed.recovery != null ? signed.recovery : 0);
+    const signature = Buffer.from(sigBytes).toString("hex");
+    const publicKey = privateKeyToPublicKey(priv, true).toString("hex");
+    const publicKeyUncompressed = privateKeyToPublicKey(priv, false).toString("hex");
+    return {
+        signature,
+        r: signature,
+        s: null,
+        v: (recovery != null ? recovery : 0) + 27,
+        publicKey,
+        senderPublicKey: publicKey,
+        publicKeyUncompressed,
+        hash: ensure0x(msgHash.toString("hex")),
+        derivedAddress: privateKeyToAddress(priv)
+    };
+}
+
+function createPrivateKey() {
+    for (let i = 0; i < 64; i++) {
+        const priv = crypto.randomBytes(32);
+        try {
+            secp.getPublicKey(priv, false);
+            return priv.toString("hex");
+        } catch (_) {
+            /* retry */
+        }
+    }
+    throw new Cx3Error("Could not generate private key", "KEYGEN_FAILED");
+}
+
+module.exports = {
+    sha256,
+    privateKeyToBytes,
+    privateKeyToPublicKey,
+    privateKeyToAddress,
+    signMessage,
+    createPrivateKey
+};

package/src/digest.js

@@ -0,0 +1,80 @@
+"use strict";
+
+/**
+ * Canonical digests must stay byte-identical to
+ * CX3GreenChain/src/api/controllers/ContractController.js
+ */
+
+function buildDeployDigest({
+    owner,
+    standard,
+    name,
+    symbol,
+    decimals = 18,
+    initialSupply = "0",
+    timestamp
+}) {
+    return [
+        "deploy",
+        owner || "",
+        standard || "",
+        name || "",
+        symbol || "",
+        decimals !== undefined ? decimals : 18,
+        initialSupply !== undefined ? String(initialSupply) : "0",
+        timestamp || 0
+    ].join("|");
+}
+
+function buildSendDigest(contractAddress, method, params, fromAddress, timestamp) {
+    const base = `${contractAddress}|${method}|${JSON.stringify(params || {})}|${fromAddress || ""}`;
+    if (timestamp !== undefined && timestamp !== null && timestamp !== "") {
+        return `${base}|${timestamp}`;
+    }
+    return base;
+}
+
+function buildOwnerActionDigest(action, address, owner, timestamp) {
+    return `${action}|${address}|${owner}|${timestamp}`;
+}
+
+function stripNativeAddress(addr) {
+    const s = String(addr || "").trim();
+    if (!s) return "";
+    if (s.startsWith("cx3:")) return s.slice(4).toLowerCase();
+    if (s.startsWith("0x") || s.startsWith("0X")) return s.slice(2).toLowerCase();
+    return s.toLowerCase();
+}
+
+/**
+ * Canonical native TRANSFER payload — byte-identical to
+ * CX3GreenChain Transaction.canonicalPayload / CX3Wallet CX3Tx.buildTransferPayload.
+ */
+function buildTransferPayload(fields = {}) {
+    const payload = {
+        type: fields.type || "TRANSFER",
+        fromAddress: stripNativeAddress(fields.fromAddress),
+        toAddress: stripNativeAddress(fields.toAddress),
+        amount: fields.amount ?? 0,
+        nonce: fields.nonce,
+        timestamp: fields.timestamp,
+        data: fields.data || null,
+        gasLimit: typeof fields.gasLimit === "number" && fields.gasLimit > 0 ? fields.gasLimit : 0,
+        gasPrice: typeof fields.gasPrice === "number" && fields.gasPrice > 0 ? fields.gasPrice : 0
+    };
+    const bind = fields.chainIdBind != null
+        ? !!fields.chainIdBind
+        : process.env.CX3_CHAIN_ID_BIND !== "0";
+    if (bind) {
+        payload.chainId = String(fields.chainId || process.env.CX3_CHAIN_ID || "cx3-dev");
+    }
+    return JSON.stringify(payload);
+}
+
+module.exports = {
+    buildDeployDigest,
+    buildSendDigest,
+    buildOwnerActionDigest,
+    buildTransferPayload,
+    stripNativeAddress
+};

package/src/errors.js

@@ -0,0 +1,29 @@
+"use strict";
+
+class Cx3Error extends Error {
+    constructor(message, code = "CX3_ERROR", details = null) {
+        super(message);
+        this.name = "Cx3Error";
+        this.code = code;
+        this.details = details;
+    }
+}
+
+class Cx3HttpError extends Cx3Error {
+    constructor(message, status, body = null) {
+        super(message, (body && (body.error || body.code)) || `HTTP_${status}`, body);
+        this.name = "Cx3HttpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+
+class Cx3TxError extends Cx3Error {
+    constructor(message, code = "TX_FAILED", receipt = null) {
+        super(message, code, receipt);
+        this.name = "Cx3TxError";
+        this.receipt = receipt;
+    }
+}
+
+module.exports = { Cx3Error, Cx3HttpError, Cx3TxError };

package/src/factory.js

@@ -0,0 +1,130 @@
+"use strict";
+
+const { Cx3Error } = require("./errors");
+const { Contract } = require("./contract");
+
+/**
+ * Standard token deploy helpers.
+ */
+class Cx3TokenFactory {
+    /**
+     * @param {import('./wallet').Cx3Wallet} wallet  Must have a provider
+     */
+    constructor(wallet) {
+        if (!wallet || !wallet.deployContract) {
+            throw new Cx3Error("Cx3TokenFactory requires a Cx3Wallet", "NO_WALLET");
+        }
+        this.wallet = wallet;
+    }
+
+    /**
+     * Deploy CX30 fungible token.
+     * @param {object} fields  name, symbol, decimals, initialSupply, capabilities, target, …
+     * @returns {Promise<{ contractAddress, txHash, blockHeight, contract?: Contract }>}
+     */
+    async deployCX30(fields = {}) {
+        return this._deployStandard("CX30", {
+            decimals: 18,
+            initialSupply: "0",
+            mintable: true,
+            burnable: true,
+            pausable: true,
+            target: "CX3WASM",
+            ...fields
+        });
+    }
+
+    async deployCX31(fields = {}) {
+        return this._deployStandard("CX31", { decimals: 18, target: "CX3WASM", ...fields });
+    }
+
+    async deployCX300(fields = {}) {
+        return this._deployStandard("CX300", { decimals: 18, target: "CX3WASM", ...fields });
+    }
+
+    async deployCX315(fields = {}) {
+        return this._deployStandard("CX315", { decimals: 0, target: "CX3WASM", ...fields });
+    }
+
+    async deployCX3192(fields = {}) {
+        return this._deployStandard("CX3192", { decimals: 0, target: "CX3WASM", ...fields });
+    }
+
+    async deployCX337(fields = {}) {
+        return this._deployStandard("CX337", {
+            name: "CX337 CBAM Proof",
+            symbol: "CX337CBAM",
+            decimals: 0,
+            target: "CX3WASM",
+            ...fields
+        });
+    }
+
+    async deployCX338(fields = {}) {
+        return this._deployStandard("CX338", {
+            name: "CX338 Sustainability Report",
+            symbol: "CX338SUS",
+            decimals: 0,
+            target: "CX3WASM",
+            ...fields
+        });
+    }
+
+    async deployCX339(fields = {}) {
+        return this._deployStandard("CX339", {
+            name: "CX339 Supply Chain",
+            symbol: "CX339SC",
+            decimals: 0,
+            target: "CX3WASM",
+            ...fields
+        });
+    }
+
+    async deployCX340(fields = {}) {
+        return this._deployStandard("CX340", {
+            name: "CX340 Materiality Assessment",
+            symbol: "CX340MAT",
+            decimals: 0,
+            target: "CX3WASM",
+            ...fields
+        });
+    }
+
+    async deployCX341(fields = {}) {
+        return this._deployStandard("CX341", {
+            name: "CX341 Green Claims",
+            symbol: "CX341GC",
+            decimals: 0,
+            target: "CX3WASM",
+            ...fields
+        });
+    }
+
+    async _deployStandard(standard, fields) {
+        if (!fields.name || !fields.symbol) {
+            throw new Cx3Error("name and symbol are required", "BAD_DEPLOY_ARGS");
+        }
+        const result = await this.wallet.deployContract({
+            ...fields,
+            standard
+        });
+        if (result && result.success !== false && result.contractAddress) {
+            try {
+                result.contract = await this.wallet.provider.getContract(
+                    result.contractAddress,
+                    null,
+                    this.wallet
+                );
+            } catch (_) {
+                result.contract = new Contract(
+                    result.contractAddress,
+                    { methods: {} },
+                    this.wallet
+                );
+            }
+        }
+        return result;
+    }
+}
+
+module.exports = { Cx3TokenFactory };

package/src/provider.js

@@ -0,0 +1,361 @@
+"use strict";
+
+const { Cx3Error, Cx3HttpError, Cx3TxError } = require("./errors");
+const { readCallValue, sleep, normalizeAddress, walletApiKeyMode } = require("./utils");
+const { Contract } = require("./contract");
+
+/**
+ * Green Chain HTTP provider.
+ *
+ * Talks to `{baseUrl}/api/v1/...` — never CX3VM directly.
+ */
+class Cx3Provider {
+    /**
+     * @param {string} baseUrl  Green Chain node URL (`CX3_NODE_URL`)
+     * @param {object} [options]
+     * @param {string} [options.apiPrefix="/api/v1"]
+     * @param {{ user: string, pass: string }} [options.auth] Basic auth (legacy node → Green Chain)
+     * @param {string} [options.apiKey] Wallet API key (`cx3wk_…`) for CX3Api `X-Api-Key`
+     * @param {Record<string,string>} [options.headers] Extra headers
+     * @param {typeof fetch} [options.fetch] Custom fetch (tests)
+     * @param {number} [options.timeoutMs]
+     */
+    constructor(baseUrl, options = {}) {
+        if (!baseUrl) throw new Cx3Error("Cx3Provider requires baseUrl (CX3_NODE_URL)", "NO_BASE_URL");
+        this.baseUrl = String(baseUrl).replace(/\/$/, "");
+        this.apiPrefix = options.apiPrefix != null ? options.apiPrefix : "/api/v1";
+        this.auth = options.auth || null;
+        this.apiKey = String(options.apiKey != null ? options.apiKey : (process.env.CX3_API_KEY || "")).trim();
+        this.extraHeaders = options.headers || {};
+        this.fetchImpl = options.fetch || globalThis.fetch;
+        this.timeoutMs = options.timeoutMs || 60000;
+        if (typeof this.fetchImpl !== "function") {
+            throw new Cx3Error("fetch is not available — use Node 18+ or pass options.fetch", "NO_FETCH");
+        }
+    }
+
+    get apiKeyMode() {
+        return walletApiKeyMode(this.apiKey);
+    }
+
+    _headers() {
+        const headers = {
+            "Content-Type": "application/json",
+            ...this.extraHeaders
+        };
+        if (/^cx3wk_[a-f0-9]{48}$/i.test(this.apiKey)) {
+            headers["X-Api-Key"] = this.apiKey;
+            return headers;
+        }
+        if (this.auth && this.auth.user && this.auth.pass) {
+            const token = Buffer.from(`${this.auth.user}:${this.auth.pass}`).toString("base64");
+            headers.Authorization = `Basic ${token}`;
+        } else {
+            const user = process.env.CX3_INTERNAL_AUTH_USER;
+            const pass = process.env.CX3_INTERNAL_AUTH_PASS;
+            if (user && pass) {
+                headers.Authorization = `Basic ${Buffer.from(`${user}:${pass}`).toString("base64")}`;
+            }
+        }
+        return headers;
+    }
+
+    _rejectEnvelope(json) {
+        if (json && json.error) {
+            throw new Cx3Error(String(json.error), String(json.error), json);
+        }
+        return json;
+    }
+
+    _pageQuery(opts = {}) {
+        const query = {};
+        if (opts.type != null && opts.type !== "") query.type = opts.type;
+        if (opts.limit != null && opts.limit !== "") query.limit = opts.limit;
+        if (opts.offset != null && opts.offset !== "") query.offset = opts.offset;
+        return query;
+    }
+
+    /**
+     * Low-level HTTP helper.
+     * @param {string} path  e.g. `/contract/call`
+     * @param {{ method?: string, body?: object, query?: Record<string,string|number> }} [opts]
+     */
+    async request(path, opts = {}) {
+        if (this.apiKeyMode === "invalid") {
+            throw new Cx3Error("api_key_required", "api_key_required");
+        }
+        const method = opts.method || "GET";
+        let url = `${this.baseUrl}${this.apiPrefix}${path.startsWith("/") ? path : `/${path}`}`;
+        if (opts.query) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
+            }
+            const s = qs.toString();
+            if (s) url += (url.includes("?") ? "&" : "?") + s;
+        }
+
+        const controller = typeof AbortController !== "undefined" ? new AbortController() : null;
+        const timer = controller
+            ? setTimeout(() => controller.abort(), this.timeoutMs)
+            : null;
+
+        try {
+            const res = await this.fetchImpl(url, {
+                method,
+                headers: this._headers(),
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                signal: controller ? controller.signal : undefined
+            });
+            const json = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                throw new Cx3HttpError(
+                    json.error || json.message || `HTTP ${res.status}`,
+                    res.status,
+                    json
+                );
+            }
+            return json;
+        } finally {
+            if (timer) clearTimeout(timer);
+        }
+    }
+
+    async getContractInfo(address) {
+        const addr = encodeURIComponent(address);
+        return this.request(`/contract/${addr}`);
+    }
+
+    async getAbi(address) {
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/abi`);
+    }
+
+    async getEvents(address, typeOrOpts = "", opts = {}) {
+        const extra = (typeOrOpts && typeof typeOrOpts === "object")
+            ? typeOrOpts
+            : { type: typeOrOpts, limit: opts.limit, offset: opts.offset };
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/events`, {
+            query: this._pageQuery({
+                type: extra.type,
+                limit: extra.limit,
+                offset: extra.offset
+            })
+        });
+    }
+
+    async getHolders(address, opts = {}) {
+        const extra = (opts && typeof opts === "object") ? opts : {};
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/holders`, {
+            query: this._pageQuery({ limit: extra.limit, offset: extra.offset })
+        });
+    }
+
+    async getTransfers(address, limitOrOpts = 20, opts = {}) {
+        let limit = 20;
+        let offset;
+        if (limitOrOpts && typeof limitOrOpts === "object") {
+            limit = limitOrOpts.limit != null ? limitOrOpts.limit : 20;
+            offset = limitOrOpts.offset;
+        } else {
+            limit = limitOrOpts;
+            offset = opts && opts.offset;
+        }
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/transfers`, {
+            query: this._pageQuery({ limit, offset })
+        });
+    }
+
+    async getTransferByHash(address, hash) {
+        const addr = encodeURIComponent(address);
+        const tx = encodeURIComponent(hash);
+        return this.request(`/contracts/${addr}/transfers/${tx}`);
+    }
+
+    async getContractState(address) {
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/state`);
+    }
+
+    async getContractSource(address) {
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/source`);
+    }
+
+    async getContractBytecode(address) {
+        const addr = encodeURIComponent(address);
+        return this.request(`/contracts/${addr}/bytecode`);
+    }
+
+    async getAddressTransactions(address, limit = 20) {
+        const addr = encodeURIComponent(address);
+        return this.request(`/address/${addr}/txs`, { query: { limit } });
+    }
+
+    async getBalanceAndNonce(address) {
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        const json = await this.request("/getBalanceAndNonce", { query: { address: addr } });
+        return this._rejectEnvelope(json);
+    }
+
+    async getBalance(address) {
+        const json = await this.getBalanceAndNonce(address);
+        return json.balance;
+    }
+
+    async getNonce(address) {
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        const json = await this.request("/getNonce", { query: { address: addr } });
+        this._rejectEnvelope(json);
+        return json.nonce;
+    }
+
+    async getPendingNonce(address) {
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        const json = await this.request("/getPendingNonce", { query: { address: addr } });
+        return this._rejectEnvelope(json);
+    }
+
+    /**
+     * Bind / verify the presented cx3wk_ API key against a wallet address.
+     * Empty key → public (any wallet), `{ ok: true, public: true }` — same as dApp whoami.
+     * Valid cx3wk_ → private: GET `/whoami` then CX3Api `/wallet/api-key/bind` on 404.
+     */
+    async bindApiKey(address) {
+        const addr = normalizeAddress(address);
+        if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
+        const mode = this.apiKeyMode;
+        if (mode === "invalid") {
+            throw new Cx3Error("api_key_required", "api_key_required");
+        }
+        if (mode === "public") {
+            return { ok: true, public: true };
+        }
+        const query = { address: addr };
+        try {
+            const json = await this.request("/whoami", { query });
+            return this._rejectEnvelope(json);
+        } catch (e) {
+            if (e && e.status === 404) {
+                const json = await this.request("/wallet/api-key/bind", { query });
+                return this._rejectEnvelope(json);
+            }
+            throw e;
+        }
+    }
+
+    async listContracts({ limit = 50, offset = 0 } = {}) {
+        return this.request("/getContracts", { query: { limit, offset } });
+    }
+
+    /**
+     * Read-only contract call.
+     */
+    async call(contractAddress, method, params = {}, sender = "") {
+        const body = {
+            contractAddress,
+            method,
+            params: params || {}
+        };
+        if (sender) body.fromAddress = normalizeAddress(sender);
+        const json = await this.request("/contract/call", { method: "POST", body });
+        return {
+            ...json,
+            value: readCallValue(json)
+        };
+    }
+
+    /**
+     * State-changing call (unsigned unless signature fields are set).
+     * Prefer Cx3Wallet / Contract for signed sends.
+     */
+    async send(contractAddress, method, params = {}, extras = {}) {
+        const body = {
+            contractAddress,
+            method,
+            params: params || {},
+            fromAddress: normalizeAddress(extras.fromAddress || extras.sender || ""),
+            ...extras
+        };
+        delete body.sender;
+        return this.request("/contract/send", {
+            method: "POST",
+            body,
+            query: extras.wait === 0 ? { wait: 0 } : undefined
+        });
+    }
+
+    async getTxStatus(txHash) {
+        const hash = encodeURIComponent(txHash);
+        // Prefer /api/v1 if available; fall back to gateway-style /tx/... under base.
+        try {
+            return await this.request(`/tx/${hash}/status`);
+        } catch (e) {
+            if (e.status === 404) {
+                const url = `${this.baseUrl}/tx/${hash}/status`;
+                const res = await this.fetchImpl(url, { headers: this._headers() });
+                const json = await res.json().catch(() => ({}));
+                if (!res.ok) throw new Cx3HttpError(json.error || `HTTP ${res.status}`, res.status, json);
+                return json;
+            }
+            throw e;
+        }
+    }
+
+    /**
+     * Poll until confirmed / failed / timeout.
+     * @returns {Promise<object>} terminal receipt
+     */
+    async waitForTransaction(txHash, opts = {}) {
+        const timeoutMs = opts.timeoutMs || 60000;
+        let interval = opts.intervalMs || 1000;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            await sleep(interval);
+            const status = await this.getTxStatus(txHash);
+            if (typeof opts.onPending === "function" && status.status === "pending") {
+                try { opts.onPending(status); } catch (_) { /* ignore */ }
+            }
+            if (status.status === "confirmed") {
+                if (typeof opts.onConfirmed === "function") {
+                    try { opts.onConfirmed(status); } catch (_) { /* ignore */ }
+                }
+                return status;
+            }
+            if (status.status === "failed") {
+                throw new Cx3TxError(status.error || "TX_FAILED", "TX_FAILED", status);
+            }
+            interval = Math.min(5000, Math.round(interval * 1.5));
+        }
+        const err = new Cx3TxError("TX_TRACK_TIMEOUT", "TX_TRACK_TIMEOUT", { txHash });
+        err.txHash = txHash;
+        throw err;
+    }
+
+    /**
+     * Load ABI from chain (optional override) and return a Contract handle.
+     * @param {string} address
+     * @param {object|array|null} [abi]
+     * @param {import('./wallet').Cx3Wallet|null} [signer]
+     */
+    async getContract(address, abi = null, signer = null) {
+        let resolvedAbi = abi;
+        let target = null;
+        if (!resolvedAbi) {
+            const meta = await this.getAbi(address);
+            resolvedAbi = meta.abi || meta;
+            target = meta.target || null;
+        }
+        const c = new Contract(address, resolvedAbi, signer || this);
+        if (target) c.target = target;
+        return c;
+    }
+}
+
+module.exports = { Cx3Provider };