@carbonx3/cx3.js 0.1.0

package/src/transaction.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const { Cx3TxError } = require("./errors");
+
+/**
+ * Result of a mutating send / deploy.
+ */
+class TransactionResponse {
+    /**
+     * @param {object} result  Raw Green Chain JSON
+     * @param {import('./provider').Cx3Provider|null} provider
+     * @param {object} [opts]
+     */
+    constructor(result, provider = null, opts = {}) {
+        this.raw = result || {};
+        this.provider = provider;
+        this.success = this.raw.success !== false;
+        this.txHash = this.raw.txHash || this.raw.hash || null;
+        this.hash = this.txHash;
+        this.blockHeight = this.raw.blockHeight;
+        this.contractAddress = this.raw.contractAddress || null;
+        this.async = !!this.raw.async || opts.wait === 0;
+        this.status = this.raw.status || (this.async ? "pending" : (this.success ? "confirmed" : "failed"));
+        this.error = this.raw.error || this.raw.message || null;
+    }
+
+    /**
+     * Wait for confirmation when the node returned async / pending.
+     * Sync responses that already include blockHeight resolve immediately.
+     */
+    async wait(opts = {}) {
+        if (!this.success) {
+            throw new Cx3TxError(this.error || "TX_FAILED", this.error || "TX_FAILED", this.raw);
+        }
+        if (!this.async && this.blockHeight != null) {
+            return {
+                status: "confirmed",
+                txHash: this.txHash,
+                blockHeight: this.blockHeight,
+                ...this.raw
+            };
+        }
+        if (!this.txHash) {
+            return this.raw;
+        }
+        if (!this.provider) {
+            throw new Cx3TxError("No provider to wait on transaction", "NO_PROVIDER", this.raw);
+        }
+        return this.provider.waitForTransaction(this.txHash, opts);
+    }
+}
+
+module.exports = { TransactionResponse };

package/src/utils.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * Normalize Green Chain read responses:
+ * metadata fast-path uses `result`, VM path uses `return`,
+ * some proxies (and the browser IIFE) expose `value`.
+ */
+function readCallValue(response) {
+    if (response == null) return undefined;
+    if (Object.prototype.hasOwnProperty.call(response, "result") && response.result !== undefined) {
+        return response.result;
+    }
+    if (Object.prototype.hasOwnProperty.call(response, "return") && response.return !== undefined) {
+        return response.return;
+    }
+    if (Object.prototype.hasOwnProperty.call(response, "value") && response.value !== undefined) {
+        return response.value;
+    }
+    return undefined;
+}
+
+function strip0x(hex) {
+    const s = String(hex || "");
+    return s.startsWith("0x") || s.startsWith("0X") ? s.slice(2) : s;
+}
+
+function ensure0x(hex) {
+    const s = String(hex || "");
+    if (!s) return s;
+    return s.startsWith("0x") || s.startsWith("0X") ? "0x" + s.slice(2).toLowerCase() : "0x" + s.toLowerCase();
+}
+
+/** Accept `0x…` or `cx3:…` wallet / contract ids; prefer 0x for digests. */
+function normalizeAddress(addr) {
+    if (addr == null || addr === "") return "";
+    const s = String(addr).trim();
+    if (s.startsWith("cx3:")) return "0x" + s.slice(4).toLowerCase();
+    if (s.startsWith("0x") || s.startsWith("0X")) return "0x" + s.slice(2).toLowerCase();
+    if (/^[0-9a-fA-F]{40}$/.test(s)) return "0x" + s.toLowerCase();
+    return s;
+}
+
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Same rules as AppSmokeTest `cx3_dapp_key_mode`:
+ * empty → public (any wallet); valid cx3wk_ → private (that wallet); else invalid.
+ */
+function walletApiKeyMode(key) {
+    const n = String(key == null ? "" : key).trim();
+    if (!n) return "public";
+    if (/^cx3wk_[a-f0-9]{48}$/i.test(n)) return "private";
+    return "invalid";
+}
+
+module.exports = {
+    readCallValue,
+    strip0x,
+    ensure0x,
+    normalizeAddress,
+    sleep,
+    isPlainObject,
+    walletApiKeyMode
+};

package/src/wallet.js

@@ -0,0 +1,247 @@
+"use strict";
+
+const {
+    privateKeyToAddress,
+    privateKeyToPublicKey,
+    signMessage,
+    createPrivateKey
+} = require("./crypto");
+const { normalizeAddress } = require("./utils");
+const { Cx3Error } = require("./errors");
+const { buildDeployDigest, buildSendDigest, buildOwnerActionDigest, buildTransferPayload, stripNativeAddress } = require("./digest");
+const { TransactionResponse } = require("./transaction");
+
+/**
+ * Local secp256k1 wallet for Green Chain digests.
+ */
+class Cx3Wallet {
+    /**
+     * @param {string|Uint8Array|Buffer} privateKey
+     * @param {import('./provider').Cx3Provider|null} [provider]
+     */
+    constructor(privateKey, provider = null) {
+        if (!privateKey) throw new Cx3Error("privateKey required", "NO_PRIVATE_KEY");
+        this._privateKey = privateKey;
+        this.provider = provider;
+        this.address = privateKeyToAddress(privateKey);
+        this.publicKey = privateKeyToPublicKey(privateKey, true).toString("hex");
+    }
+
+    static createRandom(provider = null) {
+        return new Cx3Wallet(createPrivateKey(), provider);
+    }
+
+    connect(provider) {
+        return new Cx3Wallet(this._privateKey, provider);
+    }
+
+    getAddress() {
+        return this.address;
+    }
+
+    async signMessage(message) {
+        return signMessage(message, this._privateKey);
+    }
+
+    async signDeploy(fields) {
+        const owner = normalizeAddress(fields.owner || this.address);
+        const timestamp = fields.timestamp || Date.now();
+        const digest = buildDeployDigest({
+            owner,
+            standard: fields.standard,
+            name: fields.name,
+            symbol: fields.symbol,
+            decimals: fields.decimals,
+            initialSupply: fields.initialSupply,
+            timestamp
+        });
+        const signed = await this.signMessage(digest);
+        return {
+            ...signed,
+            owner,
+            timestamp,
+            digest
+        };
+    }
+
+    async signSend(contractAddress, method, params) {
+        const fromAddress = this.address;
+        const timestamp = Date.now();
+        const digest = buildSendDigest(contractAddress, method, params || {}, fromAddress, timestamp);
+        const signed = await this.signMessage(digest);
+        return {
+            ...signed,
+            fromAddress,
+            timestamp,
+            digest
+        };
+    }
+
+    async signOwnerAction(action, address, owner = null) {
+        const own = normalizeAddress(owner || this.address);
+        const timestamp = Date.now();
+        const digest = buildOwnerActionDigest(action, address, own, timestamp);
+        const signed = await this.signMessage(digest);
+        return {
+            ...signed,
+            owner: own,
+            timestamp,
+            digest
+        };
+    }
+
+    /**
+     * Signed state-changing call via attached provider.
+     */
+    async sendTransaction(contractAddress, method, params = {}, opts = {}) {
+        if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
+        const signed = await this.signSend(contractAddress, method, params);
+        const body = {
+            fromAddress: signed.fromAddress,
+            signature: signed.signature,
+            senderPublicKey: signed.senderPublicKey,
+            timestamp: signed.timestamp
+        };
+        const asyncMode = opts.wait === 0 || opts.async === true;
+        const result = await this.provider.send(contractAddress, method, params, {
+            ...body,
+            wait: asyncMode ? 0 : undefined
+        });
+        return new TransactionResponse(result, this.provider, opts);
+    }
+
+    /**
+     * Deploy via Green Chain `POST /deployContract`.
+     */
+    async deployContract(fields) {
+        if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
+        const signed = await this.signDeploy({
+            ...fields,
+            owner: fields.owner || this.address
+        });
+        const body = {
+            ...fields,
+            owner: signed.owner,
+            requestedBy: fields.requestedBy || signed.owner,
+            wallet: fields.wallet || signed.owner,
+            timestamp: signed.timestamp,
+            signature: signed.signature,
+            senderPublicKey: signed.senderPublicKey
+        };
+        const result = await this.provider.request("/deployContract", {
+            method: "POST",
+            body
+        });
+        return result;
+    }
+
+    async _ownerActionRequest(action, address, owner, method, path) {
+        if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
+        const signed = await this.signOwnerAction(action, address, owner);
+        return this.provider.request(path, {
+            method,
+            body: {
+                owner: signed.owner,
+                timestamp: signed.timestamp,
+                signature: signed.signature,
+                senderPublicKey: signed.senderPublicKey
+            }
+        });
+    }
+
+    async pauseContract(address, owner = null) {
+        return this._ownerActionRequest(
+            "pause",
+            address,
+            owner,
+            "PUT",
+            `/contracts/${encodeURIComponent(address)}/pause`
+        );
+    }
+
+    async unpauseContract(address, owner = null) {
+        return this._ownerActionRequest(
+            "unpause",
+            address,
+            owner,
+            "PUT",
+            `/contracts/${encodeURIComponent(address)}/unpause`
+        );
+    }
+
+    async deleteContract(address, owner = null) {
+        return this._ownerActionRequest(
+            "delete",
+            address,
+            owner,
+            "DELETE",
+            `/contracts/${encodeURIComponent(address)}`
+        );
+    }
+
+    /**
+     * Native CX3 coin transfer (`POST /sendTransaction`).
+     * Distinct from `sendTransaction()` which is a signed `/contract/send`.
+     */
+    async transferNative(to, amount, opts = {}) {
+        if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
+        const toAddress = String(to || "").trim();
+        if (!toAddress) throw new Cx3Error("recipient required", "NO_RECIPIENT");
+        const amt = typeof amount === "number" ? amount : Number(amount);
+        if (!Number.isFinite(amt) || amt <= 0) {
+            throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
+        }
+        let nonce = opts.nonce;
+        if (nonce == null) {
+            try {
+                const pending = await this.provider.getPendingNonce(this.address);
+                nonce = pending && pending.nextNonce;
+            } catch (_) {
+                nonce = undefined;
+            }
+            if (nonce == null) {
+                nonce = await this.provider.getNonce(this.address);
+            }
+        }
+        const timestamp = opts.timestamp || Date.now();
+        const payload = buildTransferPayload({
+            fromAddress: this.address,
+            toAddress,
+            amount: amt,
+            nonce,
+            timestamp,
+            data: opts.data || null,
+            gasLimit: opts.gasLimit,
+            gasPrice: opts.gasPrice,
+            chainId: opts.chainId,
+            chainIdBind: opts.chainIdBind
+        });
+        const signed = await this.signMessage(payload);
+        const body = {
+            type: "TRANSFER",
+            fromAddress: stripNativeAddress(this.address),
+            toAddress: stripNativeAddress(toAddress),
+            amount: amt,
+            nonce,
+            timestamp,
+            data: opts.data || null,
+            r: signed.signature,
+            s: null,
+            v: signed.v,
+            publicKey: signed.publicKeyUncompressed || signed.publicKey
+        };
+        const result = await this.provider.request("/sendTransaction", {
+            method: "POST",
+            body
+        });
+        if (result && result.hash && !result.txHash) result.txHash = result.hash;
+        return new TransactionResponse(result, this.provider, opts);
+    }
+
+    async bindApiKey(address) {
+        if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
+        return this.provider.bindApiKey(address || this.address);
+    }
+}
+
+module.exports = { Cx3Wallet };