@carbonx3/cx3.js 0.2.0 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@ The official Node.js SDK (**CX3js**) for [CarbonX3 Green Chain](https://carbonx3
 
 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.
 
-> **Network status:** CarbonX3 Green Chain currently runs as a development network (devnet, chain id `cx3-dev`). Devnet CX3, tokens and contracts are test data with no monetary value and may be cleared when the devnet is reset.
+> **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.
 
 ## Features
 
@@ -105,7 +105,7 @@ const provider = new Cx3Provider("https://cx3api.carbonx3.com", { apiKey: proces
 Public chain data, served by the gateway to every application (a development node answers `DAPP_ONLY`):
 
 ```javascript
-const status = await provider.getStatus();                               // { height, hash, timestamp, chainId }
+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 });
@@ -199,16 +199,17 @@ A private CX31, CX300, CX315 or CX3192 takes its CX3WebUI source as `sourceCode`
 
 ## Signing
 
-Digests are UTF-8 strings, hashed with SHA-256 and signed with secp256k1, byte-identical to what the Green Chain node verifies:
+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:** `deploy|{owner}|{standard}|{name}|{symbol}|{decimals}|{initialSupply}|{timestamp}`
-- **Contract send:** `{contractAddress}|{method}|{JSON.stringify(params)}|{fromAddress}|{timestamp}`
-- **Owner action:** `{action}|{address}|{owner}|{timestamp}`
-- **Native transfer:** `JSON.stringify({ type, fromAddress, toAddress, amount, nonce, timestamp, data, gasLimit, gasPrice, chainId })`, with 40-hex addresses and no `0x`
+- **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()`
 
-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. An address is `0x` + the last 20 bytes of `sha256(uncompressedPublicKey)`.
+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)`.
 
-The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `buildOwnerActionDigest`, `buildTransferPayload`, `signMessage`, `privateKeyToAddress` and `createPrivateKey`.
+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`.
 
 ## Error handling
 
@@ -237,6 +238,7 @@ try {
 | `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
 
@@ -249,12 +251,20 @@ This package is for Node.js servers. Web pages use the **CX3 IIFE** (`cx3.min.js
 | `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()` |
-| `CX3_CHAIN_ID` | Chain id in native transfer signatures (default `cx3-dev`) |
 
 ## 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:

package/index.d.ts

@@ -81,8 +81,10 @@ export class Cx3Provider {
   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 from the gateway */
-  getStatus(): Promise<{ success: boolean; height: number; hash: string | null; timestamp: number | null; chainId?: string | null }>;
+  /** 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>;
@@ -137,9 +139,12 @@ 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>;
+  /** 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. */
@@ -147,7 +152,7 @@ export class Cx3Wallet {
   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?: { nonce?: number; timestamp?: number; data?: unknown; gasLimit?: number; gasPrice?: number; chainId?: string; chainIdBind?: boolean; wait?: number }): 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>;
 }
 
@@ -217,9 +222,18 @@ export function walletApiKeyMode(key?: string | null): "public" | "private" | "i
 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;

package/index.js

@@ -18,16 +18,18 @@ 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.2.0";
+const VERSION = "0.3.0";
 
 /**
  * Convenience: provider from `options.url` or env `CX3_NODE_URL` — the CX3Api gateway
@@ -62,7 +64,9 @@ module.exports = {
     buildSendDigest,
     buildOwnerActionDigest,
     buildTransferPayload,
+    personalMessageBytes,
     signMessage,
+    signPersonalMessage,
     privateKeyToAddress,
     createPrivateKey,
     normalizeAbi,

package/package.json

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

package/src/crypto.js

@@ -69,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);
@@ -88,5 +98,6 @@ module.exports = {
     privateKeyToPublicKey,
     privateKeyToAddress,
     signMessage,
+    signPersonalMessage,
     createPrivateKey
 };

package/src/digest.js

@@ -1,35 +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
-}) {
-    // Template literal like the node (join() would turn null into "")
-    const dec = decimals !== undefined ? decimals : 18;
-    const supply = initialSupply !== undefined ? String(initialSupply) : "0";
-    return `deploy|${owner || ""}|${standard || ""}|${name || ""}|${symbol || ""}|${dec}|${supply}|${timestamp || 0}`;
+/** 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) {
@@ -40,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),
@@ -54,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 = {
@@ -70,5 +109,8 @@ module.exports = {
     buildSendDigest,
     buildOwnerActionDigest,
     buildTransferPayload,
+    personalMessageBytes,
+    normalizeDigestAddress,
+    normalizeGenesisHash,
     stripNativeAddress
 };

package/src/provider.js

@@ -3,6 +3,7 @@
 const { Cx3Error, Cx3HttpError, Cx3TxError } = require("./errors");
 const { readCallValue, sleep, normalizeAddress, walletApiKeyMode, toJsonSafe } = require("./utils");
 const { Contract } = require("./contract");
+const { normalizeGenesisHash } = require("./digest");
 
 /**
  * Green Chain HTTP provider.
@@ -385,6 +386,24 @@ class Cx3Provider {
         return { success: true, height: blk.index != null ? blk.index : blk.height, hash: blk.hash || null, timestamp: blk.timestamp || null };
     }
 
+    /**
+     * `{ chainId, genesisHash }`: the network identity a native transfer signs over (the gateway's
+     * /status, a development node's /chain/identity). Throws NO_CHAIN_IDENTITY when either is missing.
+     */
+    async getChainIdentity() {
+        // changes only with a new genesis: kept for a minute (one request per signature otherwise)
+        const hit = this._chainIdentity;
+        if (hit && Date.now() - hit.at < 60000) return { ...hit.value };
+        const r = this.gateway
+            ? this._rejectEnvelope(await this._dappRead("/status"))
+            : this._rejectEnvelope(await this.request("/chain/identity"));
+        const chainId = typeof r.chainId === "string" ? r.chainId.trim() : "";
+        const genesisHash = normalizeGenesisHash(r.genesisHash);
+        if (!chainId || !genesisHash) throw new Cx3Error("network identity unavailable", "NO_CHAIN_IDENTITY");
+        this._chainIdentity = { at: Date.now(), value: { chainId, genesisHash } };
+        return { chainId, genesisHash };
+    }
+
     async getEvents(address, typeOrOpts = "", opts = {}) {
         const extra = (typeOrOpts && typeof typeOrOpts === "object")
             ? typeOrOpts

package/src/wallet.js

@@ -4,6 +4,7 @@ const {
     privateKeyToAddress,
     privateKeyToPublicKey,
     signMessage,
+    signPersonalMessage,
     createPrivateKey
 } = require("./crypto");
 const { normalizeAddress, toJsonSafe } = require("./utils");
@@ -46,11 +47,24 @@ class Cx3Wallet {
         return this.address;
     }
 
+    /** Sign raw bytes / a digest string as given (sha256 + secp256k1): the typed digests use this. */
     async signMessage(message) {
         return signMessage(message, this._privateKey);
     }
 
-    async signDeploy(fields) {
+    /** Sign a site message the way the CX3Wallet extension and app do (with the site-message prefix). */
+    async signPersonalMessage(message) {
+        return signPersonalMessage(message, this._privateKey);
+    }
+
+    /** The network identity typed digests bind: `opts.chainId` + `opts.genesisHash`, else the provider's. */
+    async _identity(opts = {}) {
+        if (opts.chainId && opts.genesisHash) return { chainId: opts.chainId, genesisHash: opts.genesisHash };
+        if (!this.provider) throw new Cx3Error("chainId and genesisHash required without a provider", "NO_CHAIN_IDENTITY");
+        return this.provider.getChainIdentity();
+    }
+
+    async signDeploy(fields, opts = {}) {
         const owner = normalizeAddress(fields.owner || this.address);
         const timestamp = fields.timestamp || Date.now();
         const digest = buildDeployDigest({
@@ -61,7 +75,7 @@ class Cx3Wallet {
             decimals: fields.decimals,
             initialSupply: fields.initialSupply,
             timestamp
-        });
+        }, await this._identity(opts));
         const signed = await this.signMessage(digest);
         return {
             ...signed,
@@ -71,11 +85,11 @@ class Cx3Wallet {
         };
     }
 
-    async signSend(contractAddress, method, params) {
+    async signSend(contractAddress, method, params, opts = {}) {
         const fromAddress = this.address;
         const timestamp = Date.now();
         const safeParams = toJsonSafe(params || {});
-        const digest = buildSendDigest(contractAddress, method, safeParams, fromAddress, timestamp);
+        const digest = buildSendDigest(contractAddress, method, safeParams, fromAddress, timestamp, await this._identity(opts));
         const signed = await this.signMessage(digest);
         return {
             ...signed,
@@ -86,10 +100,10 @@ class Cx3Wallet {
         };
     }
 
-    async signOwnerAction(action, address, owner = null) {
+    async signOwnerAction(action, address, owner = null, opts = {}) {
         const own = normalizeAddress(owner || this.address);
         const timestamp = Date.now();
-        const digest = buildOwnerActionDigest(action, address, own, timestamp);
+        const digest = buildOwnerActionDigest(action, address, own, timestamp, await this._identity(opts));
         const signed = await this.signMessage(digest);
         return {
             ...signed,
@@ -232,6 +246,10 @@ class Cx3Wallet {
                 nonce = await this.provider.getNonce(this.address);
             }
         }
+        // the signature covers the network's chainId + genesis hash: asked from the network unless given
+        const identity = opts.chainId && opts.genesisHash
+            ? { chainId: opts.chainId, genesisHash: opts.genesisHash }
+            : await this.provider.getChainIdentity();
         const timestamp = opts.timestamp || Date.now();
         const payload = buildTransferPayload({
             fromAddress: this.address,
@@ -242,8 +260,8 @@ class Cx3Wallet {
             data: opts.data || null,
             gasLimit: opts.gasLimit,
             gasPrice: opts.gasPrice,
-            chainId: opts.chainId,
-            chainIdBind: opts.chainIdBind
+            chainId: identity.chainId,
+            genesisHash: identity.genesisHash
         });
         const signed = await this.signMessage(payload);
         const body = {