trac-msb 0.2.26 → 0.3.0-beta.1

package/src/messages/consensus/v1/ConsensusMessageBuilder.js

@@ -0,0 +1,368 @@
+import b4a from 'b4a';
+import { appendSignatureData, toAppendIntent } from './epochAppendMessage.js';
+import tracCryptoApi from 'trac-crypto-api';
+import { encodeProofProposalApproval } from '../../../codecs/consensus/v1/consensusV1OperationCodec.js';
+import { addressToBuffer, isAddressValid } from "../../../core/state/utils/address.js";
+import {
+    ConsensusOperationType,
+    ConsensusResultCode
+} from '../../../utils/constants.js';
+import {
+    createMessage,
+    uint16ToBuffer,
+    uint64ToBuffer, uint32ToBuffer
+} from "../../../utils/buffer.js";
+
+class ConsensusMessageBuilder {
+    #wallet;
+    #config;
+    #header;
+    #type;
+    #session_id;
+    #timestamp;
+    #network_id;
+    #epoch;
+    #previous_epoch_record_hash;
+    #proposer;
+    #difficulty;
+    #discriminant_bit_size;
+    #proof;
+    #resultCode;
+    #approver;
+    #body;
+    #payloadKey;
+    #requester_proof_signature;
+    #appendIntent;
+    #appendVote;
+
+    constructor(wallet, config) {
+        this.#config = config;
+        this.#wallet = wallet;
+    }
+
+    #validateBuffer(value, fieldName) {
+        if (!b4a.isBuffer(value)) {
+            throw new Error(`${fieldName} must be a buffer.`);
+        }
+
+        return value;
+    }
+
+    #validateAddress(address, fieldName) {
+        if (typeof address !== 'string' || !isAddressValid(address, this.#config.addressPrefix)) {
+            throw new Error(`${fieldName} must be a valid TRAC address.`);
+        }
+
+        try {
+            const publicKey = tracCryptoApi.address.decode(address);
+            const canonicalAddress = tracCryptoApi.address.encode(this.#config.addressPrefix, publicKey);
+            if (canonicalAddress !== address) {
+                throw new Error('Address is not canonical for configured prefix.');
+            }
+
+            return addressToBuffer(address, this.#config.addressPrefix);
+        } catch {
+            throw new Error(`${fieldName} must be a valid TRAC address.`);
+        }
+    }
+
+    #setHeader() {
+        if (!this.#type) throw new Error('Header requires type to be set');
+        if (!this.#session_id) throw new Error('Header requires session to be set');
+        if (!this.#timestamp) throw new Error('Header requires a timestamp provider');
+
+        this.#header = {
+            type: this.#type,
+            session_id: this.#session_id,
+            timestamp: this.#timestamp,
+        };
+        return this;
+    }
+
+    setType(type) {
+        if (!Object.values(ConsensusOperationType).includes(type) || type === ConsensusOperationType.UNSPECIFIED) {
+            throw new Error(`Invalid consensus operation type: ${type}`);
+        }
+        this.#type = type;
+        return this;
+    }
+
+    setSessionId(sessionId) {
+        if (typeof sessionId !== 'string' || sessionId.length === 0) {
+            throw new Error('Session id must be a non-empty string.');
+        }
+
+        this.#session_id = sessionId;
+        return this;
+    }
+
+    setTimestamp() {
+        this.#timestamp = Date.now();
+        return this;
+    }
+
+    setNetworkId(networkId) {
+        const value = uint16ToBuffer(networkId);
+        if (networkId === 0) {
+            throw new Error('Network id must be greater than zero.');
+        }
+
+        this.#network_id = value;
+        return this;
+    }
+
+    setEpoch(epoch) {
+        const value = uint64ToBuffer(epoch);
+        const epochValue = typeof epoch === 'bigint' ? epoch : BigInt(epoch);
+        if (epochValue === 0n) {
+            throw new Error('Epoch must be greater than zero.');
+        }
+
+        this.#epoch = value;
+        return this;
+    }
+
+    setPreviousEpochRecordHash(previousEpochRecordHash) {
+        this.#previous_epoch_record_hash = this.#validateBuffer(
+            previousEpochRecordHash,
+            'Previous epoch record hash'
+        );
+        return this;
+    }
+
+    setProposer(proposer) {
+        this.#proposer = this.#validateAddress(proposer, 'Proposer');
+        return this;
+    }
+
+    setDifficulty(difficulty) {
+        this.#difficulty = this.#validateBuffer(difficulty, 'Difficulty');
+        return this;
+
+    }
+
+    setDiscriminantBitSize(discriminantBitSize) {
+        this.#discriminant_bit_size = this.#validateBuffer(discriminantBitSize, 'Discriminant bit size');
+        return this;
+    }
+
+    setProof(proof) {
+        this.#proof = this.#validateBuffer(proof, 'Proof');
+        return this;
+    }
+
+
+    setResultCode(code) {
+        if (!Object.values(ConsensusResultCode).includes(code)) {
+            throw new Error(`Invalid consensus result code: ${code}`);
+        }
+
+        this.#resultCode = code;
+        return this;
+    }
+
+    setApprover(approver) {
+        this.#approver = this.#validateAddress(approver, 'Approver');
+        return this;
+    }
+
+    setRequesterProofSignature(proofSignature) {
+        this.#requester_proof_signature = this.#validateBuffer(
+            proofSignature,
+            'Requester proof signature'
+        );
+        return this;
+    }
+
+    #buildUnsignedProofProposal() {
+        return {
+            network_id: this.#validateBuffer(this.#network_id, 'Network id'),
+            epoch: this.#validateBuffer(this.#epoch, 'Epoch'),
+            previous_epoch_record_hash: this.#validateBuffer(this.#previous_epoch_record_hash, 'Previous epoch record hash'),
+            proposer: this.#validateBuffer(this.#proposer, 'Proposer'),
+            difficulty: this.#validateBuffer(this.#difficulty, 'Difficulty'),
+            discriminant_bit_size: this.#validateBuffer(this.#discriminant_bit_size, 'Discriminant bit size'),
+            proof: this.#validateBuffer(this.#proof, 'Proof')
+        };
+    }
+
+    #getResultCode() {
+        if (this.#resultCode === undefined) {
+            throw new Error('Result code must be set before build.');
+        }
+
+        return this.#resultCode;
+    }
+
+    #getApprover() {
+        return this.#validateBuffer(this.#approver, 'Approver');
+    }
+
+    #getRequesterProofSignature() {
+        return this.#validateBuffer(
+            this.#requester_proof_signature,
+            'Requester proof signature'
+        );
+    }
+
+    async #hashProofProposal(proofProposal) {
+        return await tracCryptoApi.hash.blake3(createMessage(
+            proofProposal.network_id,
+            proofProposal.epoch,
+            proofProposal.previous_epoch_record_hash,
+            proofProposal.proposer,
+            proofProposal.difficulty,
+            proofProposal.discriminant_bit_size,
+            proofProposal.proof
+        ));
+    }
+
+    async #hashProofProposalApproval(proofProposal, approver, requesterProofSignature) {
+        return await tracCryptoApi.hash.blake3(createMessage(
+            proofProposal.network_id,
+            proofProposal.epoch,
+            proofProposal.previous_epoch_record_hash,
+            proofProposal.proposer,
+            proofProposal.difficulty,
+            proofProposal.discriminant_bit_size,
+            proofProposal.proof,
+            approver,
+            requesterProofSignature
+        ));
+    }
+
+    async #hashProofProposalResponse(resultCode, proofProposalApproval) {
+        const resultCodeBuffer = uint32ToBuffer(resultCode);
+        const message = proofProposalApproval
+            ? createMessage(resultCodeBuffer, encodeProofProposalApproval(proofProposalApproval))
+            : createMessage(resultCodeBuffer);
+
+        return await tracCryptoApi.hash.blake3(message);
+    }
+
+    async #signProofProposal(proofProposal) {
+        return this.#wallet.sign(await this.#hashProofProposal(proofProposal));
+    }
+
+    async #buildProofProposalApproval(proofProposal, approver, requesterProofSignature) {
+        const hashApproval = await this.#hashProofProposalApproval(
+            proofProposal,
+            approver,
+            requesterProofSignature
+        );
+
+        return {
+            approver,
+            approval_sig: this.#wallet.sign(hashApproval),
+        };
+    }
+
+    async #signProofProposalResponse(resultCode, proofProposalApproval) {
+        return this.#wallet.sign(
+            await this.#hashProofProposalResponse(resultCode, proofProposalApproval)
+        );
+    }
+
+    #setPayload(payloadKey, body) {
+        this.#payloadKey = payloadKey;
+        this.#body = body;
+    }
+
+    async #buildProofProposalPayload() {
+        const proofProposal = this.#buildUnsignedProofProposal();
+        const signature = await this.#signProofProposal(proofProposal);
+        this.#setPayload('proof_proposal', {
+            ...proofProposal,
+            signature: signature,
+        });
+    }
+
+    async #buildProofProposalResponsePayload() {
+        const resultCode = this.#getResultCode();
+        let proofProposalApproval = null;
+
+        if (resultCode === ConsensusResultCode.OK) {
+            const proofProposal = this.#buildUnsignedProofProposal();
+            const approver = this.#getApprover();
+            const requesterProofSignature = this.#getRequesterProofSignature();
+            proofProposalApproval = await this.#buildProofProposalApproval(
+                proofProposal,
+                approver,
+                requesterProofSignature
+            );
+        }
+
+        const responseSig = await this.#signProofProposalResponse(resultCode, proofProposalApproval);
+
+        const response = {
+            result: resultCode,
+            response_sig: responseSig,
+        };
+
+        if (proofProposalApproval) {
+            response.approval = proofProposalApproval;
+        }
+
+        this.#setPayload('proof_proposal_response', response);
+    }
+
+
+    async buildPayload() {
+        this.#setHeader();
+
+        switch (this.#type) {
+            case ConsensusOperationType.REQUEST:
+            case ConsensusOperationType.REPLY: {
+                await this.#buildAppendPayload();
+                break;
+            }
+            case ConsensusOperationType.PROOF_PROPOSAL: {
+                await this.#buildProofProposalPayload();
+                break;
+            }
+            case ConsensusOperationType.PROOF_PROPOSAL_APPROVAL: {
+                await this.#buildProofProposalResponsePayload();
+                break;
+            }
+            default:
+                throw new Error(`Unsupported consensus type ${this.#type}`);
+        }
+    }
+
+    getResult() {
+        if (!this.#header || !this.#payloadKey || !this.#body) {
+            throw new Error('Header or payload not set before getResult');
+        }
+
+        return {
+            ...this.#header,
+            [this.#payloadKey]: this.#body
+        };
+    }
+
+    setAppendIntent(request) {
+        this.#appendIntent = toAppendIntent(request);
+        this.#appendVote = request.vote ? {
+            vote_status: request.voteStatus,
+            observed_counter: uint64ToBuffer(request.observedCounter),
+            vote: toAppendIntent(request.vote),
+        } : null;
+        return this;
+    }
+
+    async #buildAppendPayload() {
+        const payloadKey = this.#type === ConsensusOperationType.REQUEST ? 'request' : 'reply';
+        const body = { intent: this.#appendIntent };
+        if (this.#type === ConsensusOperationType.REPLY) {
+            if (!this.#appendVote) throw new Error('An appender reply requires a persisted vote decision');
+            body.responder = tracCryptoApi.address.decode(this.#wallet.address);
+            Object.assign(body, this.#appendVote);
+        }
+        const signatureData = appendSignatureData({ ...this.#header, [payloadKey]: body });
+        const hash = await tracCryptoApi.hash.blake3(signatureData);
+        body.signature = this.#wallet.sign(hash);
+        this.#setPayload(payloadKey, body);
+    }
+}
+
+export default ConsensusMessageBuilder;

package/src/messages/consensus/v1/ConsensusMessageDirector.js

@@ -0,0 +1,142 @@
+import {ConsensusOperationType} from '../../../utils/constants.js';
+
+/**
+ * Director for v1 consensus protocol messages.
+ */
+
+class ConsensusMessageDirector {
+    #builder;
+
+    /**
+     * @param {ConsensusMessageBuilder} builderInstance
+     */
+    constructor(builderInstance) {
+        this.#builder = builderInstance;
+    }
+
+
+    /**
+     * Build a proof proposal message.
+     * @param {string} sessionId
+     * @param {number} networkId
+     * @param {number} epoch
+     * @param {Buffer} previousEpochRecordHash
+     * @param {string} proposer
+     * @param {Buffer} difficulty
+     * @param {Buffer} discriminantBitSize
+     * @param {Buffer} proof
+     * @returns {Promise<object>}
+     */
+    async buildProofProposal(
+        sessionId,
+        networkId,
+        epoch,
+        previousEpochRecordHash,
+        proposer,
+        difficulty,
+        discriminantBitSize,
+        proof
+    ) {
+        await this.#builder
+            .setType(ConsensusOperationType.PROOF_PROPOSAL)
+            .setSessionId(sessionId)
+            .setTimestamp()
+            .setNetworkId(networkId)
+            .setEpoch(epoch)
+            .setPreviousEpochRecordHash(previousEpochRecordHash)
+            .setProposer(proposer)
+            .setDifficulty(difficulty)
+            .setDiscriminantBitSize(discriminantBitSize)
+            .setProof(proof)
+            .buildPayload();
+
+        return this.#builder.getResult();
+    }
+
+    /**
+     * Build a proof proposal response message.
+     * @param {string} sessionId
+     * @param {number} networkId
+     * @param {number} epoch
+     * @param {Buffer} previousEpochRecordHash
+     * @param {string} proposer
+     * @param {Buffer} difficulty
+     * @param {Buffer} discriminantBitSize
+     * @param {Buffer} proof
+     * @param {Buffer} requesterProofSignature
+     * @param {number} consensusResultCode
+     * @param {string} approver
+     * @returns {Promise<object>}
+     */
+    async buildProofProposalResponse(
+        sessionId,
+        networkId,
+        epoch,
+        previousEpochRecordHash,
+        proposer,
+        difficulty,
+        discriminantBitSize,
+        proof,
+        requesterProofSignature,
+        consensusResultCode,
+        approver
+    ) {
+        await this.#builder
+            .setType(ConsensusOperationType.PROOF_PROPOSAL_APPROVAL)
+            .setSessionId(sessionId)
+            .setTimestamp()
+            .setNetworkId(networkId)
+            .setEpoch(epoch)
+            .setPreviousEpochRecordHash(previousEpochRecordHash)
+            .setProposer(proposer)
+            .setDifficulty(difficulty)
+            .setDiscriminantBitSize(discriminantBitSize)
+            .setProof(proof)
+            .setRequesterProofSignature(requesterProofSignature)
+            .setResultCode(consensusResultCode)
+            .setApprover(approver)
+            .buildPayload();
+
+        return this.#builder.getResult();
+    }
+
+    /**
+     * Build a non-OK proof proposal response without requiring proof proposal fields.
+     * @param {string} sessionId
+     * @param {number} consensusResultCode
+     * @returns {Promise<object>}
+     */
+    async buildProofProposalRejectionResponse(sessionId, consensusResultCode) {
+        await this.#builder
+            .setType(ConsensusOperationType.PROOF_PROPOSAL_APPROVAL)
+            .setSessionId(sessionId)
+            .setTimestamp()
+            .setResultCode(consensusResultCode)
+            .buildPayload();
+
+        return this.#builder.getResult();
+    }
+
+
+    /** Build a signed arbitration REQUEST for the exact publication intent. */
+    async buildRequest(sessionId, request) {
+        return this.#buildAppendMessage(ConsensusOperationType.REQUEST, sessionId, request);
+    }
+
+    /** Build a signed REPLY bound to the original request and RPC session. */
+    async buildReply(sessionId, request) {
+        return this.#buildAppendMessage(ConsensusOperationType.REPLY, sessionId, request);
+    }
+
+    async #buildAppendMessage(type, sessionId, request) {
+        await this.#builder
+            .setType(type)
+            .setSessionId(sessionId)
+            .setTimestamp()
+            .setAppendIntent(request)
+            .buildPayload();
+        return this.#builder.getResult();
+    }
+}
+
+export default ConsensusMessageDirector;

package/src/messages/consensus/v1/consensusMessageFactory.js

@@ -0,0 +1,12 @@
+import ConsensusMessageDirector from "./ConsensusMessageDirector.js";
+import ConsensusMessageBuilder from "./ConsensusMessageBuilder.js";
+
+/**
+ * Factory helper to create a director with a fresh builder instance.
+ * @param {IWallet} wallet
+ * @param {object} config
+ * @returns {ConsensusMessageDirector}
+ */
+export const consensusMessageFactory = (wallet, config) => {
+    return new ConsensusMessageDirector(new ConsensusMessageBuilder(wallet, config))
+}

package/src/messages/consensus/v1/epochAppendMessage.js

@@ -0,0 +1,58 @@
+import b4a from 'b4a';
+import { encodeEpochAppendIntent } from '../../../codecs/consensus/v1/consensusV1OperationCodec.js';
+import { uint16ToBuffer, uint32ToBuffer, uint64ToBuffer } from '../../../utils/buffer.js';
+import { ConsensusOperationType } from '../../../utils/constants.js';
+import { EPOCH_APPENDER_SELECTION_VERSION } from '../../../core/consensus/epochAppenderSelection/epochAppenderSelectionState.js';
+
+/** Convert the signed request identity to protobuf fields without serializing local membership. */
+export function toAppendIntent(request) {
+    return {
+        network_id: uint16ToBuffer(request.networkId),
+        bootstrap: b4a.from(request.bootstrap, 'hex'),
+        epoch: uint64ToBuffer(BigInt(request.targetEpoch)),
+        parent_hash: b4a.from(request.parentHash, 'hex'),
+        membership_context: b4a.from(request.membershipContext, 'hex'),
+        config_hash: b4a.from(request.configHash, 'hex'),
+        request_id: request.requestId,
+        payload_hash: b4a.from(request.payloadHash, 'hex'),
+        logical_counter: uint64ToBuffer(request.logicalCounter),
+        requester: b4a.from(request.requester, 'hex'),
+        selection_version: request.selectionVersion ?? EPOCH_APPENDER_SELECTION_VERSION,
+    };
+}
+
+/** Restore the wire identity; validators resolve membership separately from signed state. */
+export function fromAppendIntent(intent) {
+    return {
+        networkId: intent.network_id.readUInt16BE(0),
+        bootstrap: b4a.toString(intent.bootstrap, 'hex'),
+        targetEpoch: intent.epoch.readBigUInt64BE(0).toString(),
+        parentHash: b4a.toString(intent.parent_hash, 'hex'),
+        membershipContext: b4a.toString(intent.membership_context, 'hex'),
+        configHash: b4a.toString(intent.config_hash, 'hex'),
+        requestId: intent.request_id,
+        payloadHash: b4a.toString(intent.payload_hash, 'hex'),
+        logicalCounter: intent.logical_counter.readBigUInt64BE(0),
+        requester: b4a.toString(intent.requester, 'hex'),
+        selectionVersion: intent.selection_version,
+    };
+}
+
+/** Domain separation and length framing bind the entire header, intent and responder. */
+export function appendSignatureData(message) {
+    const body = message.type === ConsensusOperationType.REQUEST ? message.request : message.reply;
+    const session = b4a.from(message.session_id);
+    const parts = [
+        b4a.from('msb/epoch-appender-election/v2\0'),
+        uint32ToBuffer(message.type),
+        uint32ToBuffer(session.length),
+        session,
+        uint64ToBuffer(BigInt(message.timestamp)),
+        encodeEpochAppendIntent(body.intent),
+        body.responder ?? b4a.alloc(0),
+    ];
+    if (message.type === ConsensusOperationType.REPLY) {
+        parts.push(uint32ToBuffer(body.vote_status), body.observed_counter, encodeEpochAppendIntent(body.vote));
+    }
+    return b4a.concat(parts);
+}

package/src/messages/network/v1/NetworkMessageBuilder.js

@@ -1,7 +1,12 @@
 import tracCryptoApi from 'trac-crypto-api';
 import b4a from 'b4a';
-import {createMessage, safeWriteUInt32BE, idToBuffer, timestampToBuffer} from "../../../utils/buffer.js";
-import {NetworkOperationType, ResultCode} from '../../../utils/constants.js';
+import {
+    createMessage,
+    idToBuffer,
+    timestampToBuffer,
+    uint32ToBuffer
+} from "../../../utils/buffer.js";
+import {NetworkOperationType, NetworkResultCode} from '../../../utils/constants.js';
 import {isAddressValid} from "../../../core/state/utils/address.js";
 import {encodeCapabilities} from "../../../utils/buffer.js";
 
@@ -42,6 +47,9 @@ class NetworkMessageBuilder {
     }
 
     setId(id) {
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new Error('Session id must be a non-empty string.');
+        }
         this.#id = id;
         return this;
     }
@@ -69,7 +77,7 @@ class NetworkMessageBuilder {
     }
 
     setResultCode(code) {
-        if (!Object.values(ResultCode).includes(code)) {
+        if (!Object.values(NetworkResultCode).includes(code)) {
             throw new Error(`Invalid network result code: ${code}`);
         }
 
@@ -161,7 +169,7 @@ class NetworkMessageBuilder {
             idBuf,
             tsBuf,
             nonce,
-            safeWriteUInt32BE(this.#resultCode, 0),
+            uint32ToBuffer(this.#resultCode),
             encodeCapabilities(this.#capabilities),
         );
         const hash = await tracCryptoApi.hash.blake3(message);
@@ -213,11 +221,11 @@ class NetworkMessageBuilder {
         const timestamp = Number.isSafeInteger(this.#timestamp_ledger) ? this.#timestamp_ledger : 0;
         const hasTimestamp = timestamp > 0;
 
-        if (this.#resultCode === ResultCode.OK) {
+        if (this.#resultCode === NetworkResultCode.OK) {
             if (!hasProof || !hasTimestamp) {
                 throw new Error('Result code OK requires non-empty proof and timestamp > 0.');
             }
-        } else if (this.#resultCode === ResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE) {
+        } else if (this.#resultCode === NetworkResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE) {
             if (hasProof) {
                 throw new Error('Result code TX_ACCEPTED_PROOF_UNAVAILABLE requires empty proof.');
             }
@@ -240,7 +248,7 @@ class NetworkMessageBuilder {
             nonce,
             proof,
             timestampToBuffer(timestamp),
-            safeWriteUInt32BE(this.#resultCode, 0),
+            uint32ToBuffer(this.#resultCode),
             encodeCapabilities(this.#capabilities),
         );