@carbonx3/cx3.js 0.3.7 → 0.3.9

package/README.md

@@ -219,7 +219,7 @@ A private CX31, CX300, CX315 or CX3192 takes its CX3WebUI source as `sourceCode`
 
 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])`
+- **Deploy:** `CX3_DEPLOY_V2|` + `JSON.stringify([chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, contentHash, timestamp])`. `contentHash` is `Cx3Wallet.deployContentHash(request)`: the SHA-256 of the code, the constructor arguments, the target and the template switches of the request, so the signature is good for that content only. `deployContract` computes it, signs it and sends it. `signDeploy` without a `contentHash` signs the older `CX3_DEPLOY_V1` (the same list without it), which the network still accepts.
 - **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`
@@ -270,7 +270,7 @@ try {
 
 ## Browser applications
 
-This package is for Node.js servers. Web pages use the **CX3 IIFE** (`window.cx3`) together with the CX3Wallet extension: [`@carbonx3/cx3-iife`](https://www.npmjs.com/package/@carbonx3/cx3-iife) on npm and jsDelivr, or [download it](https://cx3script.com/download/cx3-0.2.8.min.js); 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.
+This package is for Node.js servers. Web pages use the **CX3 IIFE** (`window.cx3`) together with the CX3Wallet extension: [`@carbonx3/cx3-iife`](https://www.npmjs.com/package/@carbonx3/cx3-iife) on npm and jsDelivr, or [download it](https://cx3script.com/download/cx3-0.2.9.min.js); 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
 
@@ -286,7 +286,7 @@ 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 (0.3.1 to 0.3.4 change only this README, the file headers and comments, not the code). In 0.3.5, `bindApiKey` with a wallet API key asks the gateway's `/wallet/api-key/bind` (before, it asked `/whoami`, which the gateway refuses, so it always failed). In 0.3.6, `wait()` follows a send or deploy the gateway reports as not final (`dropped`) until its `finalAfter` instead of failing after 60 s, a `TX_TIMEOUT` answer with a hash is pending, `getRequest()` looks up a signed request, and `transferNative` refuses more than 6 decimals. 0.3.7 changes only this README: a native transfer's gas price floor is 0.0001 (the 0.3.6 README said 0.000001).
+Version 0.3.0 signs native transfers for the network's new signing format (0.3.1 to 0.3.4 change only this README, the file headers and comments, not the code). In 0.3.5, `bindApiKey` with a wallet API key asks the gateway's `/wallet/api-key/bind` (before, it asked `/whoami`, which the gateway refuses, so it always failed). In 0.3.6, `wait()` follows a send or deploy the gateway reports as not final (`dropped`) until its `finalAfter` instead of failing after 60 s, a `TX_TIMEOUT` answer with a hash is pending, `getRequest()` looks up a signed request, and `transferNative` refuses more than 6 decimals. 0.3.7 changes only this README: a native transfer's gas price floor is 0.0001 (the 0.3.6 README said 0.000001). 0.3.8 changes only this README too: the CX3 IIFE download link names `cx3-0.2.9.min.js`. In 0.3.9, `deployContract` signs `CX3_DEPLOY_V2`: the code and the constructor arguments of the request are under the signature (`Cx3Wallet.deployContentHash`, `signDeploy({ contentHash })`, `deployContentText`).
 
 - **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.

package/index.d.ts

@@ -149,7 +149,10 @@ export class Cx3Wallet {
   /** 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) */
+  /** With fields.contentHash (Cx3Wallet.deployContentHash(request)) the digest is CX3_DEPLOY_V2; the answer carries digestVersion 2 | 1 */
   signDeploy(fields: object, opts?: Cx3ChainIdentity): Promise<any>;
+  /** sha256 (hex) of the code, constructor arguments, target and template switches of a deploy request */
+  static deployContentHash(request: object): string;
   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 */
@@ -263,8 +266,10 @@ export function ensure0x(hex: string): string;
 export function strip0x(hex: string): 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] */
+/** With fields.contentHash: CX3_DEPLOY_V2|[chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, contentHash, timestamp]; without: CX3_DEPLOY_V1 (the same list without it) */
 export function buildDeployDigest(fields: object, identity: Cx3ChainIdentity): string;
+/** The text whose sha256 (hex) is a deploy request's contentHash */
+export function deployContentText(request: object): 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] */

package/index.js

@@ -20,6 +20,7 @@ const {
 } = require("./src/utils");
 const {
     buildDeployDigest,
+    deployContentText,
     buildSendDigest,
     buildOwnerActionDigest,
     buildTransferPayload,
@@ -33,7 +34,7 @@ const {
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.3.7";
+const VERSION = "0.3.9";
 
 /**
  * Convenience: provider from `options.url` or env `CX3_NODE_URL` — the CX3Api gateway
@@ -65,6 +66,7 @@ module.exports = {
     walletApiKeyMode,
     toJsonSafe,
     buildDeployDigest,
+    deployContentText,
     buildSendDigest,
     buildOwnerActionDigest,
     buildTransferPayload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonx3/cx3.js",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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": {

package/src/digest.js

@@ -34,7 +34,48 @@ function requireIdentity(identity) {
     return [chainId, genesisHash];
 }
 
-function buildDeployDigest({ owner, standard, name, symbol, decimals, initialSupply, timestamp }, identity) {
+/** JSON with object keys in order, undefined as null (the node's signingDomains.canonicalJson). */
+function canonicalJson(v) {
+    if (v === undefined || v === null || typeof v === "function" || typeof v === "symbol") return "null";
+    if (typeof v === "bigint") return JSON.stringify(v.toString());
+    if (typeof v !== "object") return JSON.stringify(v) === undefined ? "null" : JSON.stringify(v);
+    if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+    return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`).join(",")}}`;
+}
+
+/**
+ * The text whose sha256 (hex) is a deploy request's contentHash — what the request deploys beyond the
+ * CX3_DEPLOY_V1 fields: the code as sent, the constructor arguments, the target, the template switches.
+ * Byte-identical to the node's signingDomains.deployContentHash input.
+ */
+function deployContentText(body) {
+    const b = body && typeof body === "object" ? body : {};
+    const flag = (v) => (v === undefined || v === null ? null : (v === true || v === "true"));
+    return canonicalJson({
+        sourceCode: String(b.sourceCode || b.bytecode || ""),
+        constructorArgs: b.constructorArgs === undefined ? null : b.constructorArgs,
+        target: String(b.target || ""),
+        mintable: flag(b.mintable),
+        burnable: flag(b.burnable),
+        pausable: flag(b.pausable),
+        totalSupply: b.totalSupply === undefined || b.totalSupply === null ? null : String(b.totalSupply)
+    });
+}
+
+/**
+ * With `contentHash` (64 hex, sha256 of deployContentText) the digest is CX3_DEPLOY_V2: the code and
+ * the constructor arguments are under the signature too. Without it, CX3_DEPLOY_V1.
+ */
+function buildDeployDigest({ owner, standard, name, symbol, decimals, initialSupply, contentHash, timestamp }, identity) {
+    const hash = String(contentHash == null ? "" : contentHash).toLowerCase();
+    if (hash) {
+        if (!/^[0-9a-f]{64}$/.test(hash)) throw new Cx3Error("contentHash must be 64 hex characters", "INVALID_CONTENT_HASH");
+        return `CX3_DEPLOY_V2|${JSON.stringify([
+            ...requireIdentity(identity), normalizeDigestAddress(owner), String(standard || ""), String(name || ""),
+            String(symbol || ""), decimals == null ? 18 : Number(decimals),
+            initialSupply == null ? "0" : String(initialSupply), hash, Number(timestamp)
+        ])}`;
+    }
     return `CX3_DEPLOY_V1|${JSON.stringify([
         ...requireIdentity(identity), normalizeDigestAddress(owner), String(standard || ""), String(name || ""),
         String(symbol || ""), decimals == null ? 18 : Number(decimals),
@@ -109,6 +150,8 @@ function buildTransferPayload(fields = {}) {
 }
 
 module.exports = {
+    canonicalJson,
+    deployContentText,
     buildDeployDigest,
     buildSendDigest,
     buildOwnerActionDigest,

package/src/wallet.js

@@ -9,11 +9,12 @@ const {
     privateKeyToPublicKey,
     signMessage,
     signPersonalMessage,
-    createPrivateKey
+    createPrivateKey,
+    sha256
 } = require("./crypto");
 const { normalizeAddress, toJsonSafe } = require("./utils");
 const { Cx3Error } = require("./errors");
-const { buildDeployDigest, buildSendDigest, buildOwnerActionDigest, buildTransferPayload, stripNativeAddress } = require("./digest");
+const { buildDeployDigest, buildSendDigest, buildOwnerActionDigest, buildTransferPayload, stripNativeAddress, deployContentText } = require("./digest");
 const { TransactionResponse } = require("./transaction");
 
 /** Green Chain deploy rule: a token symbol is capital letters A-Z and digits 0-9 only. */
@@ -101,9 +102,15 @@ class Cx3Wallet {
         return this.provider.getChainIdentity();
     }
 
+    /**
+     * Sign a deploy request. With `fields.contentHash` (Cx3Wallet.deployContentHash(request)) the digest is
+     * CX3_DEPLOY_V2: the code and the constructor arguments are under the signature, and the request
+     * must carry the same `contentHash`. Without it, CX3_DEPLOY_V1.
+     */
     async signDeploy(fields, opts = {}) {
         const owner = normalizeAddress(fields.owner || this.address);
         const timestamp = fields.timestamp || Date.now();
+        const contentHash = fields.contentHash ? String(fields.contentHash).toLowerCase() : undefined;
         const digest = buildDeployDigest({
             owner,
             standard: fields.standard,
@@ -111,6 +118,7 @@ class Cx3Wallet {
             symbol: fields.symbol,
             decimals: fields.decimals,
             initialSupply: fields.initialSupply,
+            contentHash,
             timestamp
         }, await this._identity(opts));
         const signed = await this.signMessage(digest);
@@ -118,10 +126,18 @@ class Cx3Wallet {
             ...signed,
             owner,
             timestamp,
-            digest
+            digest,
+            digestVersion: contentHash ? 2 : 1,
+            ...(contentHash ? { contentHash } : {})
         };
     }
 
+    /** sha256 (hex) of what a deploy request deploys beyond the named fields — the node's deployContentHash. */
+    static deployContentHash(request) {
+        const asSent = JSON.parse(JSON.stringify(toJsonSafe(request || {})));
+        return Buffer.from(sha256(deployContentText(asSent))).toString("hex");
+    }
+
     async signSend(contractAddress, method, params, opts = {}) {
         const fromAddress = this.address;
         const timestamp = Date.now();
@@ -196,9 +212,12 @@ class Cx3Wallet {
                 );
             }
         }
+        // CX3_DEPLOY_V2: the code and the constructor arguments of this request are signed too
+        const contentHash = Cx3Wallet.deployContentHash(fields);
         const signed = await this.signDeploy({
             ...fields,
-            owner: fields.owner || this.address
+            owner: fields.owner || this.address,
+            contentHash
         });
         const body = {
             ...fields,
@@ -207,7 +226,8 @@ class Cx3Wallet {
             wallet: fields.wallet || signed.owner,
             timestamp: signed.timestamp,
             signature: signed.signature,
-            senderPublicKey: signed.senderPublicKey
+            senderPublicKey: signed.senderPublicKey,
+            contentHash
         };
         const result = await this.provider.request("/deployContract", {
             method: "POST",