phantasma-sdk-ts 0.7.0 → 0.8.0

package/dist/cjs/types/extensions/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./p-binary-reader.js"), exports);
+__exportStar(require("./p-binary-writer.js"), exports);
+__exportStar(require("./base16.js"), exports);
+__exportStar(require("./describer.js"), exports);

package/dist/cjs/types/extensions/p-binary-reader.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PBinaryReader = void 0;
+const csharp_binary_stream_1 = require("csharp-binary-stream");
+const index_js_1 = require("../../interfaces/index.js");
+const index_js_2 = require("../../utils/index.js");
+const index_js_3 = require("../../vm/index.js");
+const ed25519_signature_js_1 = require("../ed25519-signature.js");
+const timestamp_js_1 = require("../timestamp.js");
+const carbon_serialization_js_1 = require("../carbon-serialization.js");
+class PBinaryReader {
+    get length() {
+        return this.reader.length;
+    }
+    get position() {
+        return this.reader.position;
+    }
+    set position(value) {
+        this.reader.position = value;
+    }
+    get isEndOfStream() {
+        return this.reader.isEndOfStream;
+    }
+    readBoolean() {
+        return this.reader.readBoolean();
+    }
+    readByte() {
+        return this.reader.readByte();
+    }
+    readBytes(bytesToRead) {
+        return this.reader.readBytes(bytesToRead);
+    }
+    readSignedByte() {
+        return this.reader.readSignedByte();
+    }
+    readShort() {
+        return this.reader.readShort();
+    }
+    readUnsignedShort() {
+        return this.reader.readUnsignedShort();
+    }
+    readInt() {
+        return this.reader.readInt();
+    }
+    readUnsignedInt() {
+        return this.reader.readUnsignedInt();
+    }
+    readLongString() {
+        return this.reader.readLongString();
+    }
+    readLong() {
+        return this.reader.readLong();
+    }
+    readUnsignedLongString() {
+        return this.reader.readUnsignedLongString();
+    }
+    readUnsignedLong() {
+        return this.reader.readUnsignedLong();
+    }
+    readFloat() {
+        return this.reader.readFloat();
+    }
+    readDouble() {
+        return this.reader.readDouble();
+    }
+    readChar(encoding) {
+        return this.reader.readChar(encoding);
+    }
+    readChars(charactersToRead, encoding) {
+        return this.reader.readChars(charactersToRead, encoding);
+    }
+    readCharBytes(bytesToRead, encoding) {
+        return this.reader.readCharBytes(bytesToRead, encoding);
+    }
+    constructor(arg1) {
+        this.reader = new csharp_binary_stream_1.BinaryReader(arg1);
+    }
+    read(numBytes) {
+        const res = (0, index_js_2.bytesToHex)(this.readBytes(numBytes)).substr(0, numBytes * 2);
+        //this.position += numBytes;
+        return res;
+    }
+    readString() {
+        const len = this.readVarInt();
+        return this.readStringBytes(len);
+    }
+    readStringBytes(numBytes) {
+        let res = '';
+        for (let i = 0; i < numBytes; ++i) {
+            res += String.fromCharCode(this.readByte());
+        }
+        return res;
+    }
+    readBigInteger() {
+        const len = this.readVarInt();
+        return (0, carbon_serialization_js_1.twosComplementLEToBigInt)(Uint8Array.from(this.readBytes(len)));
+    }
+    readBigIntAccurate() {
+        return this.readBigInteger().toString();
+    }
+    readSignatureV2() {
+        const kind = this.readByte();
+        const signature = new ed25519_signature_js_1.Ed25519Signature();
+        signature.kind = kind;
+        switch (kind) {
+            case index_js_1.SignatureKind.None:
+                return null;
+            case index_js_1.SignatureKind.Ed25519:
+                const len = this.readVarInt();
+                signature.bytes = new Uint8Array(this.readBytes(len));
+                break;
+            case index_js_1.SignatureKind.ECDSA:
+                this.readByte();
+                signature.bytes = (0, index_js_2.stringToUint8Array)(this.readString());
+                break;
+            default:
+                throw new Error(`read signature: unsupported kind ${kind}`);
+        }
+        return signature;
+    }
+    readSignature() {
+        const kind = this.readByte();
+        const signature = new ed25519_signature_js_1.Ed25519Signature();
+        signature.kind = kind;
+        switch (kind) {
+            case index_js_1.SignatureKind.None:
+                return null;
+            case index_js_1.SignatureKind.Ed25519:
+                const len = this.readVarInt();
+                signature.bytes = (0, index_js_2.stringToUint8Array)(this.read(len));
+                break;
+            case index_js_1.SignatureKind.ECDSA:
+                this.readByte();
+                signature.bytes = (0, index_js_2.stringToUint8Array)(this.readString());
+                break;
+            default:
+                throw new Error(`read signature: unsupported kind ${kind}`);
+        }
+        return signature;
+    }
+    readByteArray() {
+        const length = this.readVarInt();
+        if (length == 0)
+            return '';
+        const res = this.read(length);
+        return res;
+    }
+    readTimestamp() {
+        //var len = this.readByte();
+        let result = 0;
+        const bytes = this.read(4);
+        (bytes.match(/.{1,2}/g) ?? [])
+            .reverse()
+            .forEach((c) => (result = result * 256 + parseInt(c, 16)));
+        const timestamp = new timestamp_js_1.Timestamp(result);
+        return timestamp;
+    }
+    readVarInt() {
+        const len = this.readByte();
+        let res = 0;
+        if (len === 0xfd) {
+            [...(this.read(2).match(/.{1,2}/g) ?? [])]
+                .reverse()
+                .forEach((c) => (res = res * 256 + parseInt(c, 16)));
+            return res;
+        }
+        else if (len === 0xfe) {
+            [...(this.read(4).match(/.{1,2}/g) ?? [])]
+                .reverse()
+                .forEach((c) => (res = res * 256 + parseInt(c, 16)));
+            return res;
+        }
+        else if (len === 0xff) {
+            [...(this.read(8).match(/.{1,2}/g) ?? [])]
+                .reverse()
+                .forEach((c) => (res = res * 256 + parseInt(c, 16)));
+            return res;
+        }
+        return len;
+    }
+    readVarString() {
+        const len = this.readVarInt();
+        if (len == 0)
+            return '';
+        return this.readStringBytes(len);
+    }
+    readVmObject() {
+        const type = this.readByte();
+        switch (type) {
+            case index_js_3.VMType.String:
+                return this.readString();
+            case index_js_3.VMType.Number:
+                return this.readBigIntAccurate();
+            case index_js_3.VMType.Bool:
+                return this.readByte() != 0;
+            case index_js_3.VMType.Struct:
+                const numFields = this.readVarInt();
+                const res = {};
+                for (let i = 0; i < numFields; ++i) {
+                    const key = String(this.readVmObject());
+                    const value = this.readVmObject();
+                    res[key] = value;
+                }
+                return res;
+            case index_js_3.VMType.Enum:
+                return this.readVarInt();
+            case index_js_3.VMType.Object:
+                const numBytes = this.readVarInt();
+                return this.read(numBytes);
+            default:
+                throw new Error(`read VM object: unsupported type ${type}`);
+        }
+    }
+}
+exports.PBinaryReader = PBinaryReader;

package/dist/cjs/types/extensions/p-binary-writer.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PBinaryWriter = void 0;
+const csharp_binary_stream_1 = require("csharp-binary-stream");
+const index_js_1 = require("../../utils/index.js");
+const index_js_2 = require("../../interfaces/index.js");
+class PBinaryWriter {
+    constructor(arg1) {
+        this.writer = arg1 === undefined ? new csharp_binary_stream_1.BinaryWriter() : new csharp_binary_stream_1.BinaryWriter(arg1);
+    }
+    get length() {
+        return this.writer.length;
+    }
+    get position() {
+        return this.writer.position;
+    }
+    set position(value) {
+        this.writer.position = value;
+    }
+    writeBoolean(value) {
+        this.writer.writeBoolean(value);
+    }
+    writeByte(value) {
+        this.writer.writeByte(value);
+    }
+    writeSameByte(value, repeats) {
+        this.writer.writeSameByte(value, repeats);
+    }
+    writeSignedByte(value) {
+        this.writer.writeSignedByte(value);
+    }
+    writeShort(value) {
+        this.writer.writeShort(value);
+    }
+    writeUnsignedShort(value) {
+        this.writer.writeUnsignedShort(value);
+    }
+    writeInt(value) {
+        this.writer.writeInt(value);
+    }
+    writeUnsignedInt(value) {
+        this.writer.writeUnsignedInt(value);
+    }
+    writeLong(value) {
+        this.writer.writeLong(value);
+    }
+    writeUnsignedLong(value) {
+        this.writer.writeUnsignedLong(value);
+    }
+    writeFloat(value) {
+        this.writer.writeFloat(value);
+    }
+    writeDouble(value) {
+        this.writer.writeDouble(value);
+    }
+    writeChar(character, encoding) {
+        this.writer.writeChar(character, encoding);
+    }
+    writeChars(characters, encoding) {
+        this.writer.writeChars(characters, encoding);
+    }
+    clear() {
+        this.writer.clear();
+    }
+    toArray() {
+        return this.writer.toArray();
+    }
+    toUint8Array() {
+        return this.writer.toUint8Array();
+    }
+    appendByte(value) {
+        this.writeByte(value);
+        return this;
+    }
+    appendBytes(bytes) {
+        for (let i = 0; i < bytes.length; i++) {
+            this.appendByte(bytes[i]);
+        }
+    }
+    writeEnum(value) {
+        const bytes = new Uint8Array(4);
+        for (let i = 0; i < bytes.length; i++) {
+            const byte = value & 0xff;
+            bytes[i] = byte;
+            value = (value - byte) / 256;
+        }
+        this.appendBytes(bytes);
+        return this;
+    }
+    writeBytes(bytes) {
+        for (let i = 0; i < bytes.length; i++)
+            this.appendByte(bytes[i]);
+        // writer.Write(bytes);
+        return this;
+    }
+    writeVarInt(value) {
+        if (value < 0)
+            throw new Error('negative value invalid');
+        if (value < 0xfd) {
+            this.appendByte(value);
+        }
+        else if (value <= 0xffff) {
+            const B = (value & 0x0000ff00) >> 8;
+            const A = value & 0x000000ff;
+            // VM variable integers append the least significant byte first.
+            this.appendByte(0xfd);
+            this.appendByte(A);
+            this.appendByte(B);
+        }
+        else if (value <= 0xffffffff) {
+            const C = (value & 0x00ff0000) >> 16;
+            const B = (value & 0x0000ff00) >> 8;
+            const A = value & 0x000000ff;
+            // VM variable integers append the least significant byte first.
+            this.appendByte(0xfe);
+            this.appendByte(A);
+            this.appendByte(B);
+            this.appendByte(C);
+        }
+        else {
+            const D = (value & 0xff000000) >> 24;
+            const C = (value & 0x00ff0000) >> 16;
+            const B = (value & 0x0000ff00) >> 8;
+            const A = value & 0x000000ff;
+            // VM variable integers append the least significant byte first.
+            this.appendByte(0xff);
+            this.appendByte(A);
+            this.appendByte(B);
+            this.appendByte(C);
+            this.appendByte(D);
+        }
+        return this;
+    }
+    writeTimestamp(obj) {
+        const num = obj.value;
+        const a = (num & 0xff000000) >> 24;
+        const b = (num & 0x00ff0000) >> 16;
+        const c = (num & 0x0000ff00) >> 8;
+        const d = num & 0x000000ff;
+        const bytes = Uint8Array.from([d, c, b, a]);
+        this.appendBytes(bytes);
+        return this;
+    }
+    writeDateTime(obj) {
+        const num = (obj.getTime() / 1000) | 0;
+        const a = (num & 0xff000000) >> 24;
+        const b = (num & 0x00ff0000) >> 16;
+        const c = (num & 0x0000ff00) >> 8;
+        const d = num & 0x000000ff;
+        const bytes = Uint8Array.from([d, c, b, a]);
+        this.appendBytes(bytes);
+        return this;
+    }
+    rawString(value) {
+        const data = [];
+        for (let i = 0; i < value.length; i++) {
+            data.push(value.charCodeAt(i));
+        }
+        return data;
+    }
+    writeByteArray(bytes) {
+        if (bytes instanceof Uint8Array) {
+            bytes = Array.from(bytes);
+        }
+        this.writeVarInt(bytes.length);
+        this.writeBytes(bytes);
+        return this;
+    }
+    writeString(text) {
+        const bytes = this.rawString(text);
+        this.writeVarInt(bytes.length);
+        this.writeBytes(bytes);
+        return this;
+    }
+    emitUInt32(value) {
+        if (value < 0)
+            throw new Error('negative value invalid');
+        const D = (value & 0xff000000) >> 24;
+        const C = (value & 0x00ff0000) >> 16;
+        const B = (value & 0x0000ff00) >> 8;
+        const A = value & 0x000000ff;
+        // VM integers append the least significant byte first.
+        this.appendByte(0xff);
+        this.appendByte(A);
+        this.appendByte(B);
+        this.appendByte(C);
+        this.appendByte(D);
+        return this;
+    }
+    writeBigInteger(value) {
+        return this.writeBigIntegerString(value.toString());
+    }
+    writeBigIntegerString(value) {
+        let bytes = [];
+        if (value == '0') {
+            bytes = [0];
+        }
+        else if (value.startsWith('-1')) {
+            throw new Error('Unsigned bigint serialization not suppoted');
+        }
+        else {
+            let hex = BigInt(value).toString(16);
+            if (hex.length % 2)
+                hex = '0' + hex;
+            const len = hex.length / 2;
+            let i = 0;
+            let j = 0;
+            while (i < len) {
+                bytes.unshift(parseInt(hex.slice(j, j + 2), 16)); // little endian
+                i += 1;
+                j += 2;
+            }
+            bytes.push(0); // add sign at the end
+        }
+        return this.writeByteArray(bytes);
+    }
+    writeSignature(signature) {
+        if (!signature) {
+            this.writeByte(index_js_2.SignatureKind.None);
+            return this;
+        }
+        this.writeByte(signature.kind);
+        signature.serializeData(this);
+        return this;
+    }
+    appendHexEncoded(bytesHex) {
+        const bytes = (0, index_js_1.hexToBytes)(bytesHex);
+        this.writeVarInt(bytes.length);
+        this.appendBytes(bytes);
+        return this;
+    }
+    /** @deprecated Use `appendHexEncoded` instead. This alias will be removed in v1.0. */
+    AppendHexEncoded(bytesHex) {
+        return this.appendHexEncoded(bytesHex);
+    }
+}
+exports.PBinaryWriter = PBinaryWriter;

package/dist/cjs/types/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./carbon/index.js"), exports);
+__exportStar(require("./carbon-serialization.js"), exports);
+__exportStar(require("./consensus.js"), exports);
+__exportStar(require("./timestamp.js"), exports);
+__exportStar(require("./stack.js"), exports);
+__exportStar(require("./address.js"), exports);
+__exportStar(require("./contract.js"), exports);
+__exportStar(require("./ed25519-signature.js"), exports);
+__exportStar(require("./phantasma-keys.js"), exports);
+__exportStar(require("./domain-settings.js"), exports);
+__exportStar(require("./entropy.js"), exports);
+__exportStar(require("./extensions/index.js"), exports);
+__exportStar(require("./serialization.js"), exports);

package/dist/cjs/types/phantasma-big-int-serialization.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Phantasma BigInt serialization (VarBytes-style)
+ *
+ * This module implements Phantasma serialization for signed big integers (bigint):
+ * - Representation is two's complement, little-endian (LE)
+ * - On the wire it follows the historical Phantasma/C# behavior:
+ *   1) Build a C#-compatible LE byte array for the integer (two's complement)
+ *      * Positive numbers get a leading 0x00 guard byte at the most significant side if needed
+ *      * Negative numbers get a two's complement form with MSB sign bit set (0x80) at the most significant byte
+ *   2) Apply Phantasma-specific trailing rule (aka tail guard):
+ *      * For positives: append 0x00 if the last byte is not already 0x00
+ *      * For negatives: append 0xFF to preserve sign extension (for -1 expects [FF,FF,FF])
+ *
+ * Reading (deserialization) reverses the process:
+ * - Decode two's complement from LE payload
+ * - For positives: treat the payload as a plain LE magnitude
+ * - For negatives: invert and add 1, then negate the resulting magnitude
+ *
+ * Notes
+ * - Little-endian (LE) means the least-significant byte comes first
+ * - Two's complement guarantees a unique representation for zero and correct ordering for negatives
+ * - This file intentionally mirrors Go/C# reference behavior for byte-for-byte compatibility
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bigIntToCsharpLE = bigIntToCsharpLE;
+exports.bigIntToTwosComplementLE_phantasma = bigIntToTwosComplementLE_phantasma;
+exports.bigIntFromTwosComplementLE_phantasma = bigIntFromTwosComplementLE_phantasma;
+/**
+ * Build a C#-compatible two's complement (LE) byte array for a signed bigint
+ * Steps:
+ * 1) Handle zero early as [0x00]
+ * 2) For positives:
+ *    - Extract magnitude bytes in LE order
+ *    - If the most significant byte (MSB) would imply a negative (bit 7 set), append 0x00 guard
+ * 3) For negatives:
+ *    - Start from magnitude of |n|, invert all bytes and add 1 (two's complement in LE)
+ *    - Ensure MSB has sign bit set (append 0xFF if needed)
+ * Result: a minimal LE two's complement array compatible with C# BigInteger byte layout
+ */
+function bigIntToCsharpLE(n) {
+    // Zero has a single-byte canonical representation in C# BigInteger: [0x00]
+    if (n === 0n) {
+        return new Uint8Array([0x00]);
+    }
+    // Determine the sign once; all subsequent steps depend on it
+    const negative = n < 0n;
+    // Work with magnitude |n|; two’s complement for negative values will be applied later
+    let x = negative ? -n : n;
+    const bytes = [];
+    // Extract magnitude in little-endian order: push least-significant byte first
+    while (x > 0n) {
+        bytes.push(Number(x & 0xffn));
+        x >>= 8n;
+    }
+    // Positive value path
+    if (!negative) {
+        // Ensure non-negative sign
+        // If MSB would set the sign bit, append 0x00 so the value stays non-negative in two’s complement
+        if ((bytes[bytes.length - 1] & 0x80) !== 0) {
+            bytes.push(0x00);
+        }
+        return Uint8Array.from(bytes);
+    }
+    // Negative value path: build two’s complement directly in little-endian representation
+    // Two's complement in LE
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = ~bytes[i] & 0xff;
+    }
+    // Step 2: add 1 to complete two’s complement (propagate carry across bytes)
+    // Step 2: add 1 to obtain the magnitude in LE (two’s complement reversal)
+    let carry = 1;
+    for (let i = 0; i < bytes.length; i++) {
+        const s = bytes[i] + carry;
+        bytes[i] = s & 0xff;
+        carry = s >> 8;
+        if (!carry)
+            break;
+    }
+    // If an extra carry remains, append it as a new most-significant byte
+    if (carry) {
+        bytes.push(carry);
+    }
+    // Ensure negative sign bit at MSB
+    // Ensure the resulting most-significant byte has the sign bit set to mark the value as negative
+    if ((bytes[bytes.length - 1] & 0x80) === 0) {
+        bytes.push(0xff);
+    }
+    return Uint8Array.from(bytes);
+}
+/**
+ * Serialize bigint to Phantasma byte array (LE two's complement with trailing tail guard)
+ * Process:
+ * - First, build the C#-style two's complement bytes (LE) via toCsharpLE
+ * - Then apply Phantasma tail rule:
+ *   * Positive: ensure the last byte is 0x00 by appending one if necessary
+ *   * Negative: append 0xFF to keep sign-extension stable; for -1 specifically
+ *     expectation is [FF, FF, FF] (single-byte 0xFF followed by two 0xFF guard bytes)
+ * The resulting array matches historical Go/C# Phantasma serialization byte-for-byte
+ */
+// Serialize to Phantasma wire format: start from C# bytes then apply trailing-byte rule
+function bigIntToTwosComplementLE_phantasma(n) {
+    // 1) Build C#-compatible bytes (LE + sign-guard)
+    // Build C#-style LE two’s complement bytes first (minimal, sign-correct)
+    const cs = Array.from(bigIntToCsharpLE(n));
+    // 2) Apply Phantasma tail rules
+    // Phantasma trailing rule for negative values
+    if (n < 0n) {
+        // Historical special-case: single-byte negative values (like -1) must be extended to [FF, FF, FF] on the wire
+        if (cs.length === 1) {
+            cs.push(0xff, 0xff); // -1 → [FF,FF,FF]
+        }
+        else if (cs[cs.length - 1] === 0xff) {
+            cs.push(0xff);
+        }
+        // Phantasma trailing rule for non-negative values
+    }
+    else {
+        // Ensure a terminating 0x00 guard exists at the most-significant side for positives
+        if (cs[cs.length - 1] !== 0x00) {
+            cs.push(0x00);
+        }
+    }
+    return Uint8Array.from(cs);
+}
+/**
+ * Deserialize Phantasma two's complement (LE) byte array back to bigint
+ * Logic:
+ * - Determine sign from the most significant byte's sign bit (bit 7)
+ * - For non-negative payloads:
+ *   * Interpret as a plain LE magnitude (ignore trailing 0x00 guard if present)
+ * - For negative payloads:
+ *   * Compute two's complement back in LE (invert bytes, add 1) and negate the magnitude
+ * This matches Go/C# reader behavior and roundtrips values produced by the serializer
+ */
+// Deserialize from Phantasma wire format: interpret two’s complement in LE
+function bigIntFromTwosComplementLE_phantasma(data) {
+    if (data.length === 0)
+        return 0n;
+    // Sign is determined by the most significant byte’s bit 7 (1 → negative)
+    const neg = (data[data.length - 1] & 0x80) !== 0;
+    // Positive path: interpret as plain little-endian magnitude; trailing 0x00 is benign
+    if (!neg) {
+        // positive: plain LE magnitude (leading zero bytes are fine)
+        let x = 0n;
+        // Reconstruct BigInt by shifting left 8 and OR-ing each byte from MSB to LSB
+        for (let i = data.length - 1; i >= 0; i--) {
+            x = (x << 8n) | BigInt(data[i]);
+        }
+        return x;
+    }
+    // Negative path: compute two’s complement back (invert and add 1), then negate the magnitude
+    // negative: two's complement back (LE)
+    const a = new Uint8Array(data);
+    for (let i = 0; i < a.length; i++)
+        a[i] = ~a[i] & 0xff;
+    let carry = 1;
+    for (let i = 0; i < a.length; i++) {
+        const s = a[i] + carry;
+        a[i] = s & 0xff;
+        carry = s >> 8;
+        if (!carry)
+            break;
+    }
+    let x = 0n;
+    // Fold bytes back into a positive magnitude and then apply the negative sign
+    for (let i = a.length - 1; i >= 0; i--) {
+        x = (x << 8n) | BigInt(a[i]);
+    }
+    return -x;
+}