@carbonx3/cx3.js 0.1.1 → 0.3.0

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;

package/src/contract.js

@@ -64,6 +64,11 @@ class Contract {
         const provider = this.provider;
         const sender = this.signer ? this.signer.address : "";
         const res = await provider.call(this.address, method, params, sender);
+        // the node answers a failed read with HTTP 200 + { success: false, error }
+        if (res && res.success === false) {
+            const code = String(res.error || res.message || "CALL_FAILED");
+            throw new Cx3Error(code, code, res);
+        }
         return res.value !== undefined ? res.value : res;
     }
 

package/src/crypto.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const crypto = require("crypto");
+// @noble/secp256k1 3.x is an ES module: require() loads it on Node 20.19+ / 22.12+ (package.json "engines").
 const secp = require("@noble/secp256k1");
 const { strip0x, ensure0x } = require("./utils");
 const { Cx3Error } = require("./errors");
@@ -48,10 +49,11 @@ async function signMessage(message, privateKeyInput) {
         ? 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");
+    // msgHash is already the digest (prehash: false); deterministic RFC 6979, low-S — the same bytes 1.7.x produced.
+    // "recovered" = 65 bytes: recovery id, then r || s.
+    const signed = await secp.signAsync(msgHash, priv, { prehash: false, format: "recovered" });
+    const recovery = signed[0];
+    const signature = Buffer.from(signed.subarray(1)).toString("hex");
     const publicKey = privateKeyToPublicKey(priv, true).toString("hex");
     const publicKeyUncompressed = privateKeyToPublicKey(priv, false).toString("hex");
     return {
@@ -67,6 +69,16 @@ async function signMessage(message, privateKeyInput) {
     };
 }
 
+/**
+ * Sign a site message the way the CX3Wallet extension and app do (cx3_sign_message):
+ * sha256(0x19 "CX3 Signed Message:\n" + UTF-8 length + message). Such a signature never verifies as
+ * a contract call, deploy, owner action or transaction (signing domains).
+ */
+async function signPersonalMessage(message, privateKeyInput) {
+    const { personalMessageBytes } = require("./digest");
+    return signMessage(personalMessageBytes(message), privateKeyInput);
+}
+
 function createPrivateKey() {
     for (let i = 0; i < 64; i++) {
         const priv = crypto.randomBytes(32);
@@ -86,5 +98,6 @@ module.exports = {
     privateKeyToPublicKey,
     privateKeyToAddress,
     signMessage,
+    signPersonalMessage,
     createPrivateKey
 };

package/src/digest.js

@@ -1,41 +1,64 @@
 "use strict";
 
+const { Cx3Error } = require("./errors");
+
 /**
- * Canonical digests must stay byte-identical to
- * CX3GreenChain/src/api/controllers/ContractController.js
+ * Signing domains, byte-identical to CX3GreenChain src/security/crypto/signingDomains.js
+ * (docs/security/signing-domains.md). Each starts with its own prefix, so a signature from one never
+ * verifies as another:
+ *   contract call  CX3_CALL_V1|[chainId, genesisHash, contract, method, params, from, timestamp]
+ *   deploy         CX3_DEPLOY_V1|[chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, timestamp]
+ *   owner action   CX3_OWNER_V1|[chainId, genesisHash, action, address, owner, timestamp]
+ *   site message   0x19 "CX3 Signed Message:\n" + UTF-8 length + message (hashPersonalMessage)
+ * chainId + genesisHash are the network's (provider.getChainIdentity()); addresses lower-case 0x + 40 hex.
  */
 
-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("|");
+/** lower-case 0x + 40 hex ("cx3:" / "0x" accepted), or "" */
+function normalizeDigestAddress(addr) {
+    let s = String(addr == null ? "" : addr).trim().toLowerCase();
+    if (s.startsWith("cx3:")) s = s.slice(4);
+    if (s.startsWith("0x")) s = s.slice(2);
+    return /^[0-9a-f]{40}$/.test(s) ? `0x${s}` : "";
 }
 
-function buildSendDigest(contractAddress, method, params, fromAddress, timestamp) {
-    const base = `${contractAddress}|${method}|${JSON.stringify(params || {})}|${fromAddress || ""}`;
-    if (timestamp !== undefined && timestamp !== null && timestamp !== "") {
-        return `${base}|${timestamp}`;
+function requireIdentity(identity) {
+    const chainId = String((identity && identity.chainId) || "").trim();
+    const genesisHash = normalizeGenesisHash(identity && identity.genesisHash);
+    if (!chainId || !genesisHash) {
+        throw new Cx3Error("chainId and genesisHash required (provider.getChainIdentity())", "NO_CHAIN_IDENTITY");
     }
-    return base;
+    return [chainId, genesisHash];
+}
+
+function buildDeployDigest({ owner, standard, name, symbol, decimals, initialSupply, timestamp }, identity) {
+    return `CX3_DEPLOY_V1|${JSON.stringify([
+        ...requireIdentity(identity), normalizeDigestAddress(owner), String(standard || ""), String(name || ""),
+        String(symbol || ""), decimals == null ? 18 : Number(decimals),
+        initialSupply == null ? "0" : String(initialSupply), Number(timestamp)
+    ])}`;
 }
 
-function buildOwnerActionDigest(action, address, owner, timestamp) {
-    return `${action}|${address}|${owner}|${timestamp}`;
+function buildSendDigest(contractAddress, method, params, fromAddress, timestamp, identity) {
+    return `CX3_CALL_V1|${JSON.stringify([
+        ...requireIdentity(identity), normalizeDigestAddress(contractAddress), String(method),
+        params == null ? {} : params, normalizeDigestAddress(fromAddress), Number(timestamp)
+    ])}`;
+}
+
+function buildOwnerActionDigest(action, address, owner, timestamp, identity) {
+    return `CX3_OWNER_V1|${JSON.stringify([
+        ...requireIdentity(identity), String(action), normalizeDigestAddress(address), normalizeDigestAddress(owner), Number(timestamp)
+    ])}`;
+}
+
+/** The bytes a wallet signs for a site message: 0x19 "CX3 Signed Message:\n" + UTF-8 length + message. */
+function personalMessageBytes(message) {
+    const msg = new TextEncoder().encode(typeof message === "string" ? message : JSON.stringify(message));
+    const prefix = new TextEncoder().encode(`\x19CX3 Signed Message:\n${msg.length}`);
+    const out = new Uint8Array(prefix.length + msg.length);
+    out.set(prefix, 0);
+    out.set(msg, prefix.length);
+    return out;
 }
 
 function stripNativeAddress(addr) {
@@ -46,12 +69,27 @@ function stripNativeAddress(addr) {
     return s.toLowerCase();
 }
 
+/** "0x" + 64 lower-case hex, or null. */
+function normalizeGenesisHash(value) {
+    const s = String(value == null ? "" : value).trim().toLowerCase();
+    const hex = s.startsWith("0x") ? s.slice(2) : s;
+    return /^[0-9a-f]{64}$/.test(hex) ? `0x${hex}` : null;
+}
+
 /**
  * Canonical native TRANSFER payload — byte-identical to
  * CX3GreenChain Transaction.canonicalPayload / CX3Wallet CX3Tx.buildTransferPayload.
+ * Ends with the network's chainId and genesis hash (provider.getChainIdentity()): the node verifies
+ * against its own genesis, so a transfer signed for another network or an earlier genesis is refused.
+ * Both are required — there is no fallback a signature could silently be made under.
  */
 function buildTransferPayload(fields = {}) {
-    const payload = {
+    const chainId = String(fields.chainId == null ? "" : fields.chainId).trim();
+    const genesisHash = normalizeGenesisHash(fields.genesisHash);
+    if (!chainId || !genesisHash) {
+        throw new Cx3Error("chainId and genesisHash required (provider.getChainIdentity())", "NO_CHAIN_IDENTITY");
+    }
+    return JSON.stringify({
         type: fields.type || "TRANSFER",
         fromAddress: stripNativeAddress(fields.fromAddress),
         toAddress: stripNativeAddress(fields.toAddress),
@@ -60,15 +98,10 @@ function buildTransferPayload(fields = {}) {
         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);
+        gasPrice: typeof fields.gasPrice === "number" && fields.gasPrice > 0 ? fields.gasPrice : 0,
+        chainId,
+        genesisHash
+    });
 }
 
 module.exports = {
@@ -76,5 +109,8 @@ module.exports = {
     buildSendDigest,
     buildOwnerActionDigest,
     buildTransferPayload,
+    personalMessageBytes,
+    normalizeDigestAddress,
+    normalizeGenesisHash,
     stripNativeAddress
 };

package/src/factory.js

@@ -2,9 +2,49 @@
 
 const { Cx3Error } = require("./errors");
 const { Contract } = require("./contract");
+const { normalizeAddress, isPlainObject } = require("./utils");
+
+// the token standards the CX3WebUI deploys as Public or Private
+const PRIVATE_STANDARDS = new Set(["CX30", "CX31", "CX300", "CX315", "CX3192"]);
+const MAX_AUTHORIZED_WALLETS = 200;
+
+function authorizedWalletList(list) {
+    if (list == null) return [];
+    if (!Array.isArray(list)) {
+        throw new Cx3Error("authorizedWallets is an array of wallet addresses", "BAD_DEPLOY_ARGS");
+    }
+    const out = [];
+    for (const raw of list) {
+        const a = normalizeAddress(raw);
+        if (!/^0x[0-9a-f]{40}$/.test(a)) {
+            throw new Cx3Error("authorizedWallets: every entry is a wallet address (0x + 40 hex)", "INVALID_AUTHORIZED_WALLET", { wallet: String(raw) });
+        }
+        if (!out.includes(a)) out.push(a);
+    }
+    if (out.length > MAX_AUTHORIZED_WALLETS) {
+        throw new Cx3Error(`authorizedWallets takes at most ${MAX_AUTHORIZED_WALLETS} wallets`, "TOO_MANY_AUTHORIZED_WALLETS");
+    }
+    return out;
+}
+
+// addToWhitelist params by the contract's ABI names (addr or account, then kycHash / invType = "")
+function whitelistParams(def, wallet) {
+    const names = (def && Array.isArray(def.inputs) ? def.inputs : [])
+        .map((i) => (typeof i === "string" ? i : i && i.name))
+        .filter(Boolean);
+    if (!names.length) return { addr: wallet, kycHash: "" };
+    const params = {};
+    names.forEach((n, i) => { params[n] = i === 0 ? wallet : ""; });
+    return params;
+}
 
 /**
  * Standard token deploy helpers.
+ *
+ * `visibility: "private"` deploys a private token, like the CX3WebUI "Private" choice: only the owner
+ * and `authorizedWallets` send, receive and see it. The chain renders a private CX30 itself; CX31,
+ * CX300, CX315 and CX3192 take their CX3WebUI source (`sourceCode`). Each authorized wallet is added
+ * with one signed `addToWhitelist` after the deploy (`result.authorized`).
  */
 class Cx3TokenFactory {
     /**
@@ -104,8 +144,18 @@ class Cx3TokenFactory {
         if (!fields.name || !fields.symbol) {
             throw new Cx3Error("name and symbol are required", "BAD_DEPLOY_ARGS");
         }
+        const { visibility, authorizedWallets, ...rest } = fields;
+        let body = rest;
+        let wallets = [];
+        if (visibility === "private") {
+            ({ body, wallets } = this._privateFields(standard, rest, authorizedWallets));
+        } else if (visibility != null && visibility !== "public") {
+            throw new Cx3Error('visibility is "public" or "private"', "BAD_DEPLOY_ARGS");
+        } else if (authorizedWallets != null) {
+            throw new Cx3Error('authorizedWallets belongs to visibility: "private"', "BAD_DEPLOY_ARGS");
+        }
         const result = await this.wallet.deployContract({
-            ...fields,
+            ...body,
             standard
         });
         if (result && result.success !== false && result.contractAddress) {
@@ -122,9 +172,63 @@ class Cx3TokenFactory {
                     this.wallet
                 );
             }
+            if (wallets.length) result.authorized = await this._authorize(result.contract, wallets);
         }
         return result;
     }
+
+    _privateFields(standard, fields, list) {
+        if (!PRIVATE_STANDARDS.has(standard)) {
+            throw new Cx3Error(`${standard} has no private variant (CX30, CX31, CX300, CX315 and CX3192 do)`, "PRIVATE_NOT_SUPPORTED");
+        }
+        const wallets = authorizedWalletList(list);
+        const hasSource = !!(fields.sourceCode || fields.bytecode);
+        if (!hasSource && (standard !== "CX30" || (fields.target && fields.target !== "CX3WASM"))) {
+            throw new Cx3Error(
+                `A private ${standard} ${standard === "CX30" ? "on CX3JS " : ""}is deployed from its CX3WebUI source (sourceCode); the chain renders only a CX3WASM CX30 itself`,
+                "PRIVATE_NEEDS_SOURCE"
+            );
+        }
+        const metadata = {
+            ...(isPlainObject(fields.metadata) ? fields.metadata : {}),
+            visibility: "private",
+            authorizedWallets: wallets.length
+        };
+        const body = { ...fields, whitelistable: true, metadata };
+        if (!hasSource) {
+            // the chain renders CX30 from constructorArgs; whitelistable adds the authorized list
+            // (isWhitelisted, addToWhitelist / removeFromWhitelist) and the transfer guards
+            body.constructorArgs = {
+                name: fields.name,
+                symbol: fields.symbol,
+                decimals: fields.decimals !== undefined ? Number(fields.decimals) : 18,
+                totalSupply: fields.initialSupply || fields.totalSupply || "0",
+                owner: fields.owner || this.wallet.address,
+                mintable: fields.mintable !== undefined ? fields.mintable : true,
+                burnable: fields.burnable !== undefined ? fields.burnable : true,
+                pausable: fields.pausable !== undefined ? fields.pausable : true,
+                blacklistable: !!fields.blacklistable,
+                ...(isPlainObject(fields.constructorArgs) ? fields.constructorArgs : {}),
+                whitelistable: true
+            };
+        }
+        return { body, wallets };
+    }
+
+    // one signed addToWhitelist per wallet (the CX3WebUI writes them into the constructor instead)
+    async _authorize(contract, wallets) {
+        const def = contract.interface && contract.interface.addToWhitelist;
+        const out = [];
+        for (const w of wallets) {
+            try {
+                const tx = await this.wallet.sendTransaction(contract.address, "addToWhitelist", whitelistParams(def, w));
+                out.push({ wallet: w, success: tx.success !== false, txHash: tx.txHash || null });
+            } catch (e) {
+                out.push({ wallet: w, success: false, error: (e && (e.code || e.message)) || "SEND_FAILED" });
+            }
+        }
+        return out;
+    }
 }
 
 module.exports = { Cx3TokenFactory };