trac-msb 0.2.26 → 0.3.0-beta.1

package/src/utils/buffer.js

@@ -5,110 +5,290 @@ export const ZERO_WK = b4a.alloc(32, 0); // 32 bytes of zeroes, used as a placeh
 export const NULL_BUFFER = b4a.alloc(0) // null buffer (single byte of 0)
 
 const isUInt32 = (n) => { return Number.isInteger(n) && n >= 1 && n <= 0xFFFFFFFF; }
+const MAX_UINT64 = 0xFFFFFFFFFFFFFFFFn;
 
 export function isBufferValid(key, size) {
     return b4a.isBuffer(key) && key.length === size;
 }
 
-export const safeWriteUInt32BE = (value, offset) => {
-    try {
-        const buf = b4a.alloc(4);
-        buf.writeUInt32BE(value, offset);
-        return buf;
-    } catch {
-        return b4a.alloc(4);
+export const bigIntToBuffer = bigIntTo16ByteBuffer
+
+export function deepCopyBuffer(buffer) {
+    if (!buffer) return null;
+    const copy = b4a.alloc(buffer.length);
+    buffer.copy(copy);
+    return copy;
+}
+
+export function timestampToBuffer(timestamp) {
+    return uint64ToBuffer(timestamp);
+}
+
+export function idToBuffer(id) {
+    if (typeof id !== 'string') {
+        throw new Error('id must be a string');
     }
+    return b4a.from(id, 'utf8');
 }
 
-export const createMessage = (...args) => {
 
-    if (args.length === 0) return b4a.alloc(0);
+export function encodeCapabilities(capabilities) {
+    if (!Array.isArray(capabilities)) {
+        throw new Error('Capabilities must be an array');
+    }
+    const validCapabilities = capabilities.map((capability) => {
+        if (typeof capability !== 'string') {
+            throw new Error('Capabilities array must contain only strings');
+        }
+        return capability;
+    });
 
-    const buffers = args.map(arg => {
-        if (b4a.isBuffer(arg)) {
-            return arg;
-        } else if (typeof arg === 'number' && isUInt32(arg)) {
-            return safeWriteUInt32BE(arg, 0);
+    const parts = [];
+    for (const capability of validCapabilities.slice().sort()) {
+        const capabilityBuffer = b4a.from(capability, 'utf8');
+        const bufferLen = b4a.allocUnsafe(2);
+        bufferLen.writeUInt16BE(capabilityBuffer.length, 0);
+        parts.push(bufferLen, capabilityBuffer);
+    }
+
+    return parts.length ? b4a.concat(parts) : NULL_BUFFER;
+}
+
+export function toHex(publicKey) {
+    return b4a.isBuffer(publicKey) ? b4a.toString(publicKey, 'hex') : publicKey;
+}
+
+export function uint8ToBuffer(value, offset = 0) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xFF) {
+        throw new Error(`Value must be an unsigned 8-bit integer.`);
+    }
+
+    const buf = b4a.alloc(1);
+    buf.writeUInt8(value, offset);
+    return buf;
+}
+
+export const safeUint8ToBuffer = (value, offset = 0) => {
+    try {
+        return uint8ToBuffer(value, offset);
+    } catch {
+        return NULL_BUFFER;
+    }
+}
+
+export const safeReadUint8 = (buffer, offset = 0) => {
+    try {
+        if (!b4a.isBuffer(buffer) || buffer.length < offset + 1) {
+            return null;
         }
-    }).filter(buf => b4a.isBuffer(buf));
+        return buffer.readUInt8(offset);
+    } catch {
+        return null;
+    }
+}
 
-    if (buffers.length === 0) return b4a.alloc(0);
-    return b4a.concat(buffers);
+export function uint16ToBuffer(value, offset = 0) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xFFFF) {
+        throw new Error(`Value must be an unsigned 16-bit integer.`);
+    }
+
+    const buf = b4a.alloc(2);
+    buf.writeUInt16BE(value, offset);
+    return buf;
 }
 
-export function normalizeBuffer(message) {
-    if (b4a.isBuffer(message)) {
-        return message;
+export const safeUint16ToBuffer = (value, offset = 0) => {
+    try {
+        return uint16ToBuffer(value, offset);
     }
+    catch {
+        return NULL_BUFFER;
+    }
+}
 
-    if (message.type === 'Buffer' && Array.isArray(message.data)) {
-        return b4a.from(message.data);
+export const safeReadUint16BE = (buffer, offset = 0) => {
+    try {
+        if (!b4a.isBuffer(buffer) || buffer.length < offset + 2) {
+            return null;
+        }
+        return buffer.readUInt16BE(offset)
     }
+    catch {
+        return null;
+    }
+}
 
-    if (typeof message === 'object' && Object.keys(message).every(key => !isNaN(key))) {
-        return b4a.from(Object.values(message));
+export function uint32ToBuffer(value, offset = 0) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xFFFFFFFF) {
+        throw new Error(`Value must be an unsigned 32-bit integer.`);
     }
 
-    return null;
+    const buf = b4a.alloc(4);
+    buf.writeUInt32BE(value, offset);
+    return buf;
 }
 
-export const bigIntToBuffer = bigIntTo16ByteBuffer
+export const safeWriteUInt32BE = (value, offset = 0) => {
+    try {
+        return uint32ToBuffer(value, offset);
+    } catch {
+        return NULL_BUFFER;
+    }
+}
 
-export function deepCopyBuffer(buffer) {
-    if (!buffer) return null;
-    const copy = b4a.alloc(buffer.length);
-    buffer.copy(copy);
-    return copy;
+export const safeReadUint32BE = (buffer, offset = 0) => {
+    try {
+        if (!b4a.isBuffer(buffer) || buffer.length < offset + 4) {
+            return null;
+        }
+        return buffer.readUInt32BE(offset)
+    }
+    catch {
+        return null;
+    }
 }
 
-function uint64ToBuffer(value, fieldName) {
+/**
+ * Use BigInt because uint64 values can be larger than Number.MAX_SAFE_INTEGER.
+ */
+// ATTENTION: It was decided to not use BigInt inside the apply function, so we can have more
+// control over the calculations. This function should not be used inside apply(). Use buffer
+// arithmetic (further down this file) instead.
+export function uint64ToBuffer(value) {
     if (typeof value === 'number') {
         if (!Number.isSafeInteger(value) || value < 0) {
-            throw new Error(`${fieldName} must be a non-negative safe integer`);
+            throw new Error(`Value must be a non-negative safe integer`);
         }
-        value = BigInt(value);
     } else if (typeof value !== 'bigint') {
-        throw new Error(`${fieldName} must be a number or bigint`);
+        throw new Error(`Value must be a number or bigint`);
     }
-    if (value < 0n) {
-        throw new Error(`${fieldName} must be a non-negative integer`);
+
+    const uint64Value = typeof value === 'bigint' ? value : BigInt(value);
+
+    if (uint64Value < 0n) {
+        throw new Error(`Value must be a non-negative integer`);
+    }
+    if (uint64Value > MAX_UINT64) {
+        throw new Error(`Value must be an unsigned 64-bit integer`);
     }
 
     const buf = b4a.alloc(8);
-    buf.writeBigUInt64BE(value);
+    buf.writeBigUInt64BE(uint64Value);
     return buf;
 }
 
-export function timestampToBuffer(timestamp) {
-    return uint64ToBuffer(timestamp, 'timestamp');
+
+export const createMessage = (...args) => {
+
+    if (args.length === 0) return NULL_BUFFER;
+
+    const buffers = args.map(arg => {
+        if (b4a.isBuffer(arg)) {
+            return arg;
+        } else if (typeof arg === 'number' && isUInt32(arg)) {
+            return safeWriteUInt32BE(arg);
+        }
+    }).filter(buf => b4a.isBuffer(buf));
+
+    if (buffers.length === 0) return NULL_BUFFER;
+    return b4a.concat(buffers);
 }
 
-export function idToBuffer(id) {
-    if (typeof id !== 'string') {
-        throw new Error('id must be a string');
+export function isZeroBuffer(buffer) {
+    if (!b4a.isBuffer(buffer)) {
+        return false;
     }
-    return b4a.from(id, 'utf8');
+    return buffer.every(byte => byte === 0);
 }
 
+// Buffer Arithmetic
 
-export function encodeCapabilities(capabilities) {
-    if (!Array.isArray(capabilities)) {
-        throw new Error('Capabilities must be an array');
+/**
+ * Increments a fixed-width big-endian unsigned integer buffer by one.
+ * The input must contain between 1 and 16 bytes and is not mutated.
+ * When enforceLength is provided, the input must contain exactly that
+ * number of bytes. Returns null for invalid input, a length mismatch,
+ * or an increment that would overflow the buffer's fixed width.
+ *
+ * @param {Buffer} buffer - The unsigned integer to increment.
+ * @param {number|null} [enforceLength=null] - Required input length in bytes.
+ * @returns {Buffer|null} A new incremented buffer, or null on failure.
+ */
+export function incrementBuffer(buffer, enforceLength = null) {
+    if (!b4a.isBuffer(buffer) ||
+        (enforceLength !== null && buffer.length !== enforceLength) ||
+        buffer.length === 0 ||
+        buffer.length > 16) {
+        return null;
     }
-    const validCapabilities = capabilities.map((capability) => {
-        if (typeof capability !== 'string') {
-            throw new Error('Capabilities array must contain only strings');
+
+    const result = b4a.from(buffer);
+    for (let i = result.length - 1; i >= 0; i--) {
+        if (result[i] === 0xFF) {
+            result[i] = 0;
+            continue;
         }
-        return capability;
-    });
 
-    const parts = [];
-    for (const capability of validCapabilities.slice().sort()) {
-        const capabilityBuffer = b4a.from(capability, 'utf8');
-        const bufferLen = b4a.allocUnsafe(2);
-        bufferLen.writeUInt16BE(capabilityBuffer.length, 0);
-        parts.push(bufferLen, capabilityBuffer);
+        result[i]++;
+        return result;
     }
 
-    return parts.length ? b4a.concat(parts) : b4a.alloc(0);
+    return null;
+}
+
+/**
+ * Converts a big-endian unsigned integer buffer to a numeric string.
+ * The input must contain between 1 and 16 bytes.
+ *
+ * @param {Buffer} buffer - The unsigned integer to convert.
+ * @param {'decimal'|'hex'} [encoding='decimal'] - Output encoding.
+ * @returns {string} The normalized numeric string.
+ * @throws {TypeError} When the input or encoding is invalid.
+ */
+export function toUIntString(buffer, encoding = 'decimal') {
+    if (!b4a.isBuffer(buffer) || buffer.length === 0 || buffer.length > 16) {
+        throw new TypeError('Input must contain between 1 and 16 bytes.');
+    }
+
+    switch (encoding) {
+        case 'hex':
+            return buffer.toString('hex').replace(/^0+/, '') || '0';
+        case 'decimal': {
+            const digits = [0];
+            for (const byte of buffer) {
+                let carry = byte;
+
+                for (let i = 0; i < digits.length; i++) {
+                    const value = digits[i] * 256 + carry;
+                    digits[i] = value % 10;
+                    carry = Math.floor(value / 10);
+                }
+
+                while (carry > 0) {
+                    digits.push(carry % 10);
+                    carry = Math.floor(carry / 10);
+                }
+            }
+
+            return digits.reverse().join('');
+        }
+        default:
+            throw new TypeError("Unsupported encoding. Use 'hex' or 'decimal'.");
+    }
+}
+
+/**
+ * Safely converts a big-endian unsigned integer buffer to a numeric string.
+ *
+ * @param {Buffer} buffer - The unsigned integer to convert.
+ * @param {'decimal'|'hex'} [encoding='decimal'] - Output encoding.
+ * @returns {string|null} The normalized numeric string, or null for invalid input.
+ */
+export function safeToUIntString(buffer, encoding = 'decimal') {
+    try {
+        return toUIntString(buffer, encoding);
+    }
+    catch {
+        return null;
+    }
 }

package/src/utils/consensusConfig.js

@@ -0,0 +1,76 @@
+import { decodeConsensusConfig } from '../codecs/apply/applyOperationCodec.js';
+import { decodeVdfConfig, safeDecodeVdfConfig } from '../codecs/consensus/v1/vdfConfigCodec.js';
+import {
+    CONSENSUS_CONFIG_SCHEMA_VERSION_BYTE_LENGTH,
+    ConsensusVersion,
+    VDF_PROOF_BYTE_LENGTHS,
+} from './constants.js';
+import { isBufferValid, isZeroBuffer, safeReadUint8 } from './buffer.js';
+
+// Off-chain helpers. Do not use these in apply or delegate to state/utils:
+// changes here must not change historical state replay.
+
+const decodeVdfV1ConfigData = (encodedConfigData) => {
+    const decodedConfigData = decodeVdfConfig(encodedConfigData);
+
+    return {
+        difficulty: decodedConfigData.difficulty.readUInt32BE(0),
+        discriminantBitSize: decodedConfigData.discriminantBitSize.readUInt16BE(0),
+    };
+};
+
+const CONSENSUS_CONFIG_DECODERS = Object.freeze({
+    [ConsensusVersion.VDF_V1]: decodeVdfV1ConfigData,
+});
+
+export const validateConsensusConfig = (consensusConfig) => {
+    if (!isBufferValid(consensusConfig?.sv, CONSENSUS_CONFIG_SCHEMA_VERSION_BYTE_LENGTH)) {
+        return false;
+    }
+
+    switch (safeReadUint8(consensusConfig.sv)) {
+        case ConsensusVersion.VDF_V1: {
+            const configData = safeDecodeVdfConfig(consensusConfig.cd);
+            if (configData === null) return false;
+
+            return !isZeroBuffer(configData.difficulty) &&
+                Object.hasOwn(VDF_PROOF_BYTE_LENGTHS, configData.discriminantBitSize.readUInt16BE(0));
+        }
+        default:
+            return false;
+    }
+};
+
+/**
+ * Decodes a stored consensus config for off-chain consumers.
+ *
+ * @param {Buffer} encodedConsensusConfig Encoded consensus config envelope.
+ * @returns {{schemaVersion: number, configData: object}} Decoded domain config.
+ * @throws {Error} When the envelope, version, or config data is invalid.
+ */
+export const decodeVersionedConsensusConfig = (encodedConsensusConfig) => {
+    const consensusConfig = decodeConsensusConfig(encodedConsensusConfig);
+    const schemaVersion = consensusConfig.sv.readUInt8(0);
+    const decodeConfigData = CONSENSUS_CONFIG_DECODERS[schemaVersion];
+
+    if (typeof decodeConfigData !== 'function') {
+        throw new Error(`Unsupported consensus config schema version: ${schemaVersion}.`);
+    }
+
+    return {
+        schemaVersion,
+        configData: decodeConfigData(consensusConfig.cd),
+    };
+};
+
+/**
+ * @param {*} encodedConsensusConfig Value expected to contain an encoded config.
+ * @returns {{schemaVersion: number, configData: object}|null} Decoded config or null.
+ */
+export const safeDecodeVersionedConsensusConfig = (encodedConsensusConfig) => {
+    try {
+        return decodeVersionedConsensusConfig(encodedConsensusConfig);
+    } catch {
+        return null;
+    }
+};