trac-msb 0.2.26 → 0.3.0-beta.1

package/rpc/create_server.js

@@ -45,11 +45,20 @@ export const createServer = (msbInstance, config) => {
             const requestParts = requestPath.split('/');
             const routeParts = routeBase.split('/');
         
-            if (req.method === route.method && 
-            requestParts.length >= routeParts.length &&
-            routeParts.every((part, i) => part === requestParts[i])) {
+            const exact = route.exact || routeParts.some(part => part.startsWith(':'));
+            const params = {};
+            if (req.method === route.method &&
+            (exact ? requestParts.length === routeParts.length : requestParts.length >= routeParts.length) &&
+            routeParts.every((part, i) => {
+                if (part.startsWith(':') && requestParts[i]) {
+                    params[part.slice(1)] = requestParts[i];
+                    return true;
+                }
+                return part === requestParts[i];
+            })) {
             
                 foundRoute = true;
+                req.params = params;
                 try {
                 // This try/catch covers synchronous errors and errors from awaited promises
                 // within the route.handler function.

package/rpc/handlers.js

@@ -13,6 +13,7 @@ import { bufferToBigInt, licenseBufferToBigInt } from "../src/utils/amountSerial
 import { isAddressValid } from "../src/core/state/utils/address.js";
 import { getConfirmedParameter } from "./utils/confirmedParameter.js";
 import { BroadcastError, ValidationError } from "../src/utils/errors.js";
+import { OperationType } from "../src/utils/constants.js";
 
 export async function handleHealth({ msbInstance, respond }) {
     try {
@@ -46,6 +47,108 @@ export async function handleBalance({ req, respond, msbInstance }) {
     respond(200, { address, balance });
 }
 
+function readHtlcPayload(req, respond) {
+    return new Promise(resolve => {
+        let body = '';
+        let bytesRead = 0;
+        let finished = false;
+
+        req.on('data', chunk => {
+            if (finished) return;
+            bytesRead += chunk.length;
+            if (bytesRead > 2_000_000) {
+                finished = true;
+                respond(413, { error: 'Payload too large.' });
+                req.resume();
+                resolve(null);
+                return;
+            }
+            body += chunk.toString();
+        });
+        req.on('end', () => {
+            if (finished) return;
+            finished = true;
+            try {
+                const request = JSON.parse(body);
+                if (!request?.payload) throw new ValidationError('Payload is missing.');
+                if (typeof request.payload !== 'string' || !isBase64(request.payload)) {
+                    throw new ValidationError('Payload must be a valid base64 string.');
+                }
+                const payload = decodeBase64Payload(request.payload);
+                if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+                    throw new ValidationError('Invalid HTLC operation payload.');
+                }
+                resolve(payload);
+            } catch (error) {
+                respond(400, { error: error instanceof ValidationError ? error.message : 'Invalid JSON payload.' });
+                resolve(null);
+            }
+        });
+        req.on('error', () => {
+            if (finished) return;
+            finished = true;
+            respond(500, { error: 'Request stream failed during body transfer.' });
+            resolve(null);
+        });
+        req.on('aborted', () => {
+            finished = true;
+            resolve(null);
+        });
+    });
+}
+
+async function handleHtlcSubmission({ req, msbInstance, respond }, type, operationKey, submit) {
+    const payload = await readHtlcPayload(req, respond);
+    if (!payload) return;
+    if (payload.type !== type || !payload[operationKey] || typeof payload.address !== 'string') {
+        return respond(400, { error: 'Invalid HTLC operation payload.' });
+    }
+    if (type !== OperationType.HTLC_LOCK) {
+        const lockId = req.params?.id;
+        if (!isValidTxHash(lockId) || typeof payload[operationKey].li !== 'string' ||
+            payload[operationKey].li.toLowerCase() !== lockId.toLowerCase()) {
+            return respond(400, { error: 'HTLC lock ID does not match the payload.' });
+        }
+    }
+    try {
+        const result = await submit.call(msbInstance, payload);
+        respond(200, { result: { ...result, message: 'Transaction broadcasted successfully.' } });
+    } catch (error) {
+        if (error instanceof ValidationError) return respond(400, { error: error.message });
+        if (error instanceof BroadcastError) return respond(429, { error: error.message });
+        console.error('Error in HTLC submission:', error);
+        respond(500, { error: 'An error occurred processing the transaction.' });
+    }
+}
+
+export async function handleHtlcLock(context) {
+    return handleHtlcSubmission(context, OperationType.HTLC_LOCK, 'hlo', context.msbInstance.htlcLock);
+}
+
+export async function handleHtlcClaim(context) {
+    return handleHtlcSubmission(context, OperationType.HTLC_CLAIM, 'hco', context.msbInstance.htlcClaim);
+}
+
+export async function handleHtlcRefund(context) {
+    return handleHtlcSubmission(context, OperationType.HTLC_REFUND, 'hro', context.msbInstance.htlcRefund);
+}
+
+export async function handleHtlc({ req, msbInstance, respond }) {
+    const lockId = req.params?.id;
+    if (!isValidTxHash(lockId)) return respond(400, { error: 'Invalid HTLC lock ID.' });
+    const confirmed = getConfirmedParameter(buildRequestUrl(req));
+    if (confirmed === null) {
+        return respond(400, { error: 'Parameter "confirmed" must be exactly "true" or "false"' });
+    }
+    try {
+        const htlc = await msbInstance.getHtlc(lockId, confirmed);
+        if (!htlc) return respond(404, { error: `HTLC ${lockId.toLowerCase()} not found.` });
+        respond(200, { htlc });
+    } catch (error) {
+        console.error('Error in handleHtlc:', error);
+        respond(500, { error: 'An error occurred processing the request.' });
+    }
+}
 export async function handleTxv({ msbInstance, respond }) {
     const txv = await msbInstance.getTxv();
     respond(200, { txv });

package/rpc/routes/v1.js

@@ -11,6 +11,10 @@ import {
     handleFetchBulkTxPayloads,
     handleTransactionExtendedDetails,
     handleAccountDetails,
+    handleHtlcLock,
+    handleHtlcClaim,
+    handleHtlcRefund,
+    handleHtlc,
 } from '../handlers.js';
 
 export const v1Routes = [
@@ -22,6 +26,10 @@ export const v1Routes = [
     { method: 'POST', path: '/broadcast-transaction', handler: handleBroadcastTransaction },
     { method: 'GET', path: '/tx-hashes/', handler: handleTxHashes },
     { method: 'GET', path: '/unconfirmed-length', handler: handleUnconfirmedLength },
+    { method: 'POST', path: '/htlc', exact: true, handler: handleHtlcLock },
+    { method: 'POST', path: '/htlc/:id/claim', handler: handleHtlcClaim },
+    { method: 'POST', path: '/htlc/:id/refund', handler: handleHtlcRefund },
+    { method: 'GET', path: '/htlc/:id', handler: handleHtlc },
     { method: 'GET', path: '/tx', handler: handleTransactionDetails },
     { method: 'POST', path: '/tx-payloads-bulk', handler: handleFetchBulkTxPayloads },
     { method: 'GET', path: '/tx/details', handler: handleTransactionExtendedDetails },

package/src/codecs/apply/applyOperationCodec.js

@@ -0,0 +1,334 @@
+import b4a from 'b4a';
+import applyOperationsGenerated from './applyOperations.generated.cjs';
+import consensusV1Generated from '../consensus/v1/consensusV1.generated.cjs';
+import _ from 'lodash';
+const { Operation, SetEpochOperation, ConsensusControlOperation } = applyOperationsGenerated.apply.operations;
+const { EpochProofV1 } = consensusV1Generated.common.consensus;
+
+// Options for converting protobuf messages to plain objects, ensuring that bytes are returned as Buffers and enums as numbers.
+const APPLY_TO_OBJECT_OPTIONS = Object.freeze({
+    enums: Number,
+    longs: Number,
+    defaults: false,
+    arrays: true,
+    oneofs: false
+});
+
+const normalizeDecodedApplyOperation = operation => {
+    const payload = operation.tro || operation.rao || operation.bdo || operation.txo || operation.hlo;
+    if (!payload) return operation;
+
+    payload.va ??= null;
+    payload.vn ??= null;
+    payload.vs ??= null;
+
+    return operation;
+}
+
+export const encodeApplyOperation = (payload) => {
+    const error = Operation.verify(payload);
+    if (error) throw new Error(error);
+    return b4a.from(Operation.encode(payload).finish());
+}
+
+const decodeApplyOperation = (payload) => {
+    return normalizeDecodedApplyOperation(
+        Operation.toObject(
+            Operation.decode(payload),
+            APPLY_TO_OBJECT_OPTIONS
+        )
+    );
+}
+
+/**
+ * Safely encodes an operation using the generated apply Operation encoder.
+ * If the encoding fails (e.g., due to an invalid payload), returns an empty Buffer.
+ *
+ * @param {*} payload - Any input that should conform to the `applyOperation` schema.
+ * @returns {Buffer} - Encoded Buffer if successful, otherwise an empty Buffer (`b4a.alloc(0)`).
+ */
+export const safeEncodeApplyOperation = (payload) => {
+    try {
+        const result = encodeApplyOperation(payload);
+        if (b4a.isBuffer(result)) return result
+    } catch (error) {
+        console.log("safeEncodeApplyOperation error:", error.message);
+    }
+    return b4a.alloc(0);
+}
+
+/**
+ * Safely decodes a Buffer into an `Operation` object using the generated apply Operation decoder.
+ * Returns `null` if decoding fails or the input is invalid.
+ *
+ * @param {Buffer} payload - A buffer containing encoded data.
+ * @returns {Object|null} - Decoded `applyOperation` object on success, or `null` on failure.
+ */
+export const safeDecodeApplyOperation = (payload) => {
+    try {
+        if (!b4a.isBuffer(payload)) return null;
+        return decodeApplyOperation(payload);
+    } catch (error) {
+        console.log(error);
+    }
+    return null;
+}
+
+export const unsafeDecodeApplyOperation= (payload) => {
+    return decodeApplyOperation(payload);
+}
+
+export const unsafeEncodeApplyOperation = (payload) => {
+    return encodeApplyOperation(payload);
+}
+
+export const normalizeIncomingMessage = (message) => {
+    if (!message) return null;
+    if (b4a.isBuffer(message)) {
+        return decodeApplyOperation(message);
+    }
+
+    if (message.type === 'Buffer' && Array.isArray(message.data)) {
+        const buffer = b4a.from(message.data);
+        return decodeApplyOperation(buffer);
+    }
+
+    return null;
+};
+
+const validateEpochRecord = (payload) => {
+    if (!_.isPlainObject(payload)) {
+        throw new Error('Epoch record must be an object.');
+    }
+
+    const { sv, data } = payload;
+    if (!b4a.isBuffer(sv) || sv.length !== 1 || sv[0] === 0) {
+        throw new Error('Epoch record schema version must be a non-zero one-byte buffer.');
+    }
+    if (!b4a.isBuffer(data) || data.length === 0) {
+        throw new Error('Epoch record data must be a non-empty buffer.');
+    }
+
+    return { sv, data };
+};
+
+/**
+ * Encodes an epoch record using the SET_EPOCH payload wire format, not a full operation.
+ * The versioned data stays opaque; consensus validation belongs to apply.
+ *
+ * @param {{sv: Buffer, data: Buffer}} payload Epoch record.
+ * @returns {Buffer} Canonically encoded epoch record.
+ */
+export const encodeEpochRecord = (payload) => {
+    const epochRecord = validateEpochRecord(payload);
+    const error = SetEpochOperation.verify(epochRecord);
+    if (error) throw new Error(error);
+    return b4a.from(SetEpochOperation.encode(epochRecord).finish());
+};
+
+/**
+ * Decodes an epoch record independently of the currently active consensus.
+ *
+ * @param {Buffer} payload Encoded epoch record.
+ * @returns {{sv: Buffer, data: Buffer}} Epoch record with opaque versioned data.
+ */
+export const decodeEpochRecord = (payload) => {
+    if (!b4a.isBuffer(payload)) {
+        throw new Error('Encoded epoch record must be a buffer.');
+    }
+
+    return validateEpochRecord(
+        SetEpochOperation.toObject(
+            SetEpochOperation.decode(payload),
+            APPLY_TO_OBJECT_OPTIONS
+        )
+    );
+};
+
+/**
+ * @param {*} payload Epoch record to encode.
+ * @returns {Buffer} Encoded epoch record, or an empty buffer on failure.
+ */
+export const safeEncodeEpochRecord = (payload) => {
+    try {
+        return encodeEpochRecord(payload);
+    } catch {
+        return b4a.alloc(0);
+    }
+};
+
+/**
+ * @param {*} payload Encoded epoch record.
+ * @returns {{sv: Buffer, data: Buffer}|null} Epoch record, or null on failure.
+ */
+export const safeDecodeEpochRecord = (payload) => {
+    try {
+        return decodeEpochRecord(payload);
+    } catch {
+        return null;
+    }
+};
+
+const validateEpochProofV1 = (payload) => {
+    if (!_.isPlainObject(payload)) {
+        throw new Error('EpochProofV1 payload must be an object.');
+    }
+
+    const { pd, app } = payload;
+
+    if (!b4a.isBuffer(pd) || pd.length === 0) {
+        throw new Error('EpochProofV1 pd must be a non-empty buffer.');
+    }
+
+    if (!Array.isArray(app)) {
+        throw new Error('EpochProofV1 app must be an array.');
+    }
+
+    for (const [index, approval] of app.entries()) {
+        if (!b4a.isBuffer(approval) || approval.length === 0) {
+            throw new Error(`EpochProofV1 app ${index} must be a non-empty buffer.`);
+        }
+    }
+
+    return { pd, app };
+}
+
+/**
+ * Encodes an EpochProofV1.
+ *
+ * @param {{pd: Buffer, app: Buffer[]}} payload - Epoch proof payload.
+ * @returns {Buffer} Encoded EpochProofV1.
+ */
+export const encodeEpochProofV1 = (payload) => {
+    const epochProof = validateEpochProofV1(payload);
+    const error = EpochProofV1.verify(epochProof);
+    if (error) throw new Error(error);
+    return b4a.from(EpochProofV1.encode(epochProof).finish());
+}
+
+/**
+ * Decodes an EpochProofV1.
+ *
+ * @param {Buffer} payload - Encoded EpochProofV1 buffer.
+ * @returns {{pd: Buffer, app: Buffer[]}} Decoded EpochProofV1.
+ */
+export const decodeEpochProofV1 = (payload) => {
+    return validateEpochProofV1(
+        EpochProofV1.toObject(
+            EpochProofV1.decode(payload),
+            APPLY_TO_OBJECT_OPTIONS
+        )
+    );
+}
+
+/**
+ * Safely encodes an EpochProofV1. Returns an empty buffer when the payload is invalid.
+ *
+ * @param {*} payload - Input expected to match EpochProofV1.
+ * @returns {Buffer} Encoded EpochProofV1 or an empty buffer.
+ */
+export const safeEncodeEpochProofV1 = (payload) => {
+    try {
+        return encodeEpochProofV1(payload);
+    } catch (error) {
+        console.log("safeEncodeEpochProofV1 error:", error.message);
+    }
+
+    return b4a.alloc(0);
+}
+
+/**
+ * Safely decodes an EpochProofV1. Returns null when the input is invalid.
+ *
+ * @param {*} payload - Encoded EpochProofV1 buffer.
+ * @returns {{pd: Buffer, app: Buffer[]}|null} Decoded EpochProofV1 or null.
+ */
+export const safeDecodeEpochProofV1 = (payload) => {
+    try {
+        if (!b4a.isBuffer(payload)) return null;
+        return decodeEpochProofV1(payload);
+    } catch (error) {
+        console.log("safeDecodeEpochProofV1 error:", error.message);
+    }
+
+    return null;
+}
+
+const getValidatedConsensusConfigPayload = (payload) => {
+    if (!_.isPlainObject(payload)) {
+        throw new Error('ConsensusConfig payload must be an object.');
+    }
+
+    const { sv, cd} = payload;
+
+    if (!b4a.isBuffer(sv) || sv.length !== 1) {
+        throw new Error('Schema version must be a one-byte buffer.');
+    }
+
+    if (!b4a.isBuffer(cd)) {
+        throw new Error('ConsensusConfig configData must be a buffer.');
+    }
+
+    return { sv, cd };
+}
+
+/**
+ * Encodes a ConsensusConfig using the ConsensusControlOperation wire format.
+ *
+ * @param {{sv: Buffer, cd: Buffer}} payload - Consensus config payload.
+ * @returns {Buffer} Encoded ConsensusConfig.
+ */
+export const encodeConsensusConfig = (payload) => {
+    const consensusConfigPayload = getValidatedConsensusConfigPayload(payload);
+    const consensusControlPayload = { cc: consensusConfigPayload };
+    const error = ConsensusControlOperation.verify(consensusControlPayload);
+    if (error) throw new Error(error);
+    return b4a.from(ConsensusControlOperation.encode(consensusControlPayload).finish());
+}
+
+/**
+ * Decodes a ConsensusConfig encoded with the ConsensusControlOperation wire format.
+ *
+ * @param {Buffer} payload - Encoded ConsensusConfig buffer.
+ * @returns {{sv: Buffer, cd: Buffer}} Decoded ConsensusConfig.
+ */
+export const decodeConsensusConfig = (payload) => {
+    if (!b4a.isBuffer(payload)) {
+        throw new Error('Encoded ConsensusConfig must be a buffer.');
+    }
+
+    const consensusControlPayload = ConsensusControlOperation.toObject(
+        ConsensusControlOperation.decode(payload),
+        APPLY_TO_OBJECT_OPTIONS
+    );
+
+    return getValidatedConsensusConfigPayload(consensusControlPayload.cc);
+}
+
+/**
+ * Safely encodes a ConsensusConfig. Returns an empty buffer when the payload is invalid.
+ *
+ * @param {*} payload - Input expected to match ConsensusConfig.
+ * @returns {Buffer} Encoded ConsensusConfig or an empty buffer.
+ */
+export const safeEncodeConsensusConfig = (payload) => {
+    try {
+        return encodeConsensusConfig(payload);
+    } catch {
+        return b4a.alloc(0);
+    }
+}
+
+/**
+ * Safely decodes a ConsensusConfig. Returns null when the input is invalid.
+ *
+ * @param {*} payload - Encoded ConsensusConfig buffer.
+ * @returns {{sv: Buffer, cd: Buffer}|null} Decoded ConsensusConfig or null.
+ */
+export const safeDecodeConsensusConfig = (payload) => {
+    try {
+        return decodeConsensusConfig(payload);
+    } catch {
+        return null;
+    }
+}