trac-msb 0.2.24 → 0.3.0-beta.1

package/src/messages/state/ApplyStateMessageDirector.js

@@ -1,4 +1,6 @@
-import { OperationType } from '../../utils/constants.js';
+import { ConsensusVersion, OperationType } from '../../utils/constants.js';
+import { encodeEpochProofV1 } from '../../codecs/apply/applyOperationCodec.js';
+import { uint8ToBuffer } from '../../utils/buffer.js';
 
 /**
  * Director that orchestrates ApplyStateMessageBuilder for partial and complete messages.
@@ -511,6 +513,263 @@ class ApplyStateMessageDirector {
             .build();
         return this.#builder.getPayload();
     }
-}
 
+    /**
+     * Build a complete set epoch payload.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} proofData
+     * @param {Array<string|Buffer>} approvals
+     * @returns {Promise<object>}
+     */
+    async buildCompleteSetEpochMessage(invokerAddress, proofData, approvals) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        const schemaVersion = uint8ToBuffer(ConsensusVersion.VDF_V1);
+        const epochData = encodeEpochProofV1({ pd: proofData, app: approvals });
+
+        await this.#builder
+            .setPhase('complete')
+            .setOutput('buffer')
+            .setOperationType(OperationType.SET_EPOCH)
+            .setAddress(invokerAddress)
+            .setEpochData(schemaVersion, epochData)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Build a complete set genesis epoch payload.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} txValidity
+     * @param {Buffer} encodedConsensusConfig
+     * @returns {Promise<object>}
+     */
+    async buildCompleteSetGenesisEpochMessage(invokerAddress, txValidity, encodedConsensusConfig) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('complete')
+            .setOutput('buffer')
+            .setOperationType(OperationType.SET_GENESIS_EPOCH)
+            .setAddress(invokerAddress)
+            .setTxValidity(txValidity)
+            .setConsensusConfig(encodedConsensusConfig)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Build a complete set consensus config payload.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} txValidity
+     * @param {Buffer} encodedConsensusConfig
+     * @returns {Promise<object>}
+     */
+    async buildCompleteSetConsensusConfigMessage(invokerAddress, txValidity, encodedConsensusConfig) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('complete')
+            .setOutput('buffer')
+            .setOperationType(OperationType.SET_CONSENSUS_CONFIG)
+            .setAddress(invokerAddress)
+            .setTxValidity(txValidity)
+            .setConsensusConfig(encodedConsensusConfig)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Build a partial HTLC lock operation.
+     * The transaction hash produced by the builder is the lock identifier.
+     *
+     * @param {string|Buffer} invokerAddress Locker address.
+     * @param {string|Buffer} txValidity Current transaction-validity value.
+     * @param {object} lock Canonical HTLC lock terms and authorizations.
+     * @param {string|Buffer} [lock.metadata] Opaque application bytes (1–1024 bytes), or their hex representation.
+     * @param {'json'|'buffer'} output Output format.
+     * @returns {Promise<object>}
+     */
+    async buildPartialHtlcLockOperationMessage(invokerAddress, txValidity, lock, output = 'buffer') {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        const {
+            claimAddress,
+            refundAddress,
+            amount,
+            feeAmount,
+            feeRecipient,
+            hashLock,
+            refundEpoch,
+            metadata,
+            signerSet,
+            threshold,
+            cosignerSignatures = [],
+            nonce
+        } = lock ?? {};
+
+        const builder = this.#builder
+            .setPhase('partial')
+            .setOutput(output)
+            .setOperationType(OperationType.HTLC_LOCK)
+            .setAddress(invokerAddress)
+            .setTxValidity(txValidity)
+            .setAmount(amount)
+            .setHtlcClaimAddress(claimAddress)
+            .setHtlcRefundAddress(refundAddress)
+            .setHtlcFeeAmount(feeAmount)
+            .setHtlcFeeRecipient(feeRecipient)
+            .setHtlcHashLock(hashLock)
+            .setHtlcRefundEpoch(refundEpoch)
+            .setHtlcMetadata(metadata)
+            .setHtlcSignerSet(signerSet)
+            .setHtlcThreshold(threshold)
+            .setHtlcCosignerSignatures(cosignerSignatures);
+
+        if (nonce !== undefined) builder.setNonce(nonce);
+        await builder.build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Build a signed partial HTLC claim payload.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} txValidity
+     * @param {string|Buffer} lockId
+     * @param {string|Buffer} preimage
+     * @returns {Promise<object>}
+     */
+    async buildPartialHtlcClaimOperationMessage(invokerAddress, txValidity, lockId, preimage) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('partial')
+            .setOutput('buffer')
+            .setOperationType(OperationType.HTLC_CLAIM)
+            .setAddress(invokerAddress)
+            .setTxValidity(txValidity)
+            .setHtlcLockId(lockId)
+            .setHtlcPreimage(preimage)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Add validator metadata to an already validated partial HTLC lock operation.
+     *
+     * @param {string|Buffer} invokerAddress Locker address.
+     * @param {object} operation Decoded partial hlo payload.
+     * @returns {Promise<object>}
+     */
+    async buildCompleteHtlcLockOperationMessage(invokerAddress, operation) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('complete')
+            .setOutput('buffer')
+            .setOperationType(OperationType.HTLC_LOCK)
+            .setAddress(invokerAddress)
+            .setTxHash(operation?.tx)
+            .setTxValidity(operation?.txv)
+            .setAmount(operation?.am)
+            .setHtlcClaimAddress(operation?.ca)
+            .setHtlcRefundAddress(operation?.ra)
+            .setHtlcFeeAmount(operation?.fa)
+            .setHtlcFeeRecipient(operation?.fr)
+            .setHtlcHashLock(operation?.hl)
+            .setHtlcRefundEpoch(operation?.re)
+            .setHtlcMetadata(operation?.md)
+            .setHtlcSignerSet(operation?.ss)
+            .setHtlcThreshold(operation?.th)
+            .setHtlcCosignerSignatures(operation?.cs)
+            .setIncomingNonce(operation?.in)
+            .setIncomingSignature(operation?.is)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Complete a submitter-signed HTLC claim with validator metadata.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} transactionHash
+     * @param {string|Buffer} txValidity
+     * @param {string|Buffer} lockId
+     * @param {string|Buffer} preimage
+     * @param {string|Buffer} incomingNonce
+     * @param {string|Buffer} incomingSignature
+     * @returns {Promise<object>}
+     */
+    async buildCompleteHtlcClaimOperationMessage(
+        invokerAddress,
+        transactionHash,
+        txValidity,
+        lockId,
+        preimage,
+        incomingNonce,
+        incomingSignature
+    ) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('complete')
+            .setOutput('buffer')
+            .setOperationType(OperationType.HTLC_CLAIM)
+            .setAddress(invokerAddress)
+            .setTxHash(transactionHash)
+            .setTxValidity(txValidity)
+            .setHtlcLockId(lockId)
+            .setHtlcPreimage(preimage)
+            .setIncomingNonce(incomingNonce)
+            .setIncomingSignature(incomingSignature)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Build a signed partial HTLC refund payload.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} txValidity
+     * @param {string|Buffer} lockId
+     * @param {'json'|'buffer'} output
+     * @returns {Promise<object>}
+     */
+    async buildPartialHtlcRefundOperationMessage(invokerAddress, txValidity, lockId, output = 'buffer') {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('partial')
+            .setOutput(output)
+            .setOperationType(OperationType.HTLC_REFUND)
+            .setAddress(invokerAddress)
+            .setTxValidity(txValidity)
+            .setHtlcLockId(lockId)
+            .build();
+        return this.#builder.getPayload();
+    }
+
+    /**
+     * Add validator metadata to a validated, submitter-signed HTLC refund.
+     * @param {string|Buffer} invokerAddress
+     * @param {string|Buffer} transactionHash
+     * @param {string|Buffer} txValidity
+     * @param {string|Buffer} lockId
+     * @param {string|Buffer} incomingNonce
+     * @param {string|Buffer} incomingSignature
+     * @returns {Promise<object>}
+     */
+    async buildCompleteHtlcRefundOperationMessage(
+        invokerAddress,
+        transactionHash,
+        txValidity,
+        lockId,
+        incomingNonce,
+        incomingSignature
+    ) {
+        if (!this.#builder) throw new Error('Builder has not been set.');
+        await this.#builder
+            .setPhase('complete')
+            .setOutput('buffer')
+            .setOperationType(OperationType.HTLC_REFUND)
+            .setAddress(invokerAddress)
+            .setTxHash(transactionHash)
+            .setTxValidity(txValidity)
+            .setHtlcLockId(lockId)
+            .setIncomingNonce(incomingNonce)
+            .setIncomingSignature(incomingSignature)
+            .build();
+        return this.#builder.getPayload();
+    }
+}
 export default ApplyStateMessageDirector;

package/src/utils/StateMachine.js

@@ -0,0 +1,125 @@
+import ReadyResource from 'ready-resource';
+
+const READY_RESOURCE_EVENTS = ['ready', 'close'];
+
+export class StateMachine extends ReadyResource {
+    #state;
+    #context = {};
+    #discardState;
+    #listeners = new Map();
+    #transitions;
+    #handlers;
+    #transition = null;
+
+    constructor(transitions, initialState, discardState, handlers = {}) {
+        super();
+        if (!transitions) throw new Error('StateMachine: transitions is required');
+        if (!initialState) throw new Error('StateMachine: initialState is required');
+        if (discardState === undefined) throw new Error('StateMachine: discardState is required (pass null to disable context clearing)');
+
+        this.#transitions = transitions;
+        this.#state = initialState;
+        this.#discardState = discardState;
+        this.#handlers = handlers;
+    }
+
+    async _close() {
+        this.clearListeners();
+    }
+
+    get state() {
+        return this.#state;
+    }
+
+    get context() {
+        return this.#context;
+    }
+
+    appendContext(payload = {}) {
+        Object.assign(this.#context, payload);
+        return this.#context;
+    }
+
+    shouldRun() {
+        return this.closing === null && !this.closed;
+    }
+
+    async send(event, payload = {}) {
+        if (!this.shouldRun()) return false;
+
+        const next = this.#transitions[this.#state]?.[event];
+        if (!next) return false;
+
+        this.appendContext(payload);
+
+        const prev = this.#state;
+        const transition = { machine: this, prev, next, context: this.#context };
+        this.#transition = transition;
+        this.#state = next;
+        await this.#emit(event, transition);
+
+        // Another transition may have run while an event listener was awaited.
+        if (!this.shouldRun() || this.#transition !== transition) return false;
+
+        if (this.#discardState !== null && next === this.#discardState) {
+            this.#context = {};
+        }
+
+        await this.#dispatch(next);
+
+        return transition;
+    }
+
+    // The initial state is assigned directly in the constructor, not reached via send(),
+    // so its handler never fires on its own - nothing ever "transitions into" it. This
+    // dispatches to the current state's handler once, the same way any other transition
+    // does, so callers never need to know which state that is.
+    async enter(payload = {}) {
+        if (!this.shouldRun()) return false;
+
+        this.appendContext(payload);
+
+        const transition = { machine: this, prev: null, next: this.#state, context: this.#context };
+        this.#transition = transition;
+        await this.#emit('ENTER', transition);
+
+        if (!this.shouldRun() || this.#transition !== transition) return false;
+
+        await this.#dispatch(transition.next);
+
+        return transition;
+    }
+
+    async #dispatch(state) {
+        const handler = this.#handlers[state];
+        if (handler) await handler(this.#context, this);
+    }
+
+    on(event, fn) {
+        if (READY_RESOURCE_EVENTS.includes(event)) {
+            super.on(event, fn);
+            return this;
+        }
+
+        if (!this.#listeners.has(event)) this.#listeners.set(event, []);
+
+        this.#listeners.get(event).push(fn);
+        return this;
+    }
+
+    clearListeners() {
+        this.#listeners.clear();
+        return this;
+    }
+
+    async #emit(event, data) {
+        for (const fn of this.#listeners.get(event) ?? []) {
+            if (!this.shouldRun() || this.#transition !== data) return;
+            await fn(data);
+        }
+        for (const fn of this.#listeners.get('*') ?? []) {
+            if (!this.shouldRun() || this.#transition !== data) return;
+            await fn({ event, ...data });
+        }
+    }
+}

package/src/utils/applyOperations.js

@@ -48,6 +48,26 @@ const isBalanceInitialization = type => {
     ].includes(type);
 }
 
+const isHtlc = type => {
+    return [
+        OperationType.HTLC_LOCK,
+        OperationType.HTLC_CLAIM,
+        OperationType.HTLC_REFUND
+    ].includes(type);
+}
+const isSetEpoch = type => {
+    return [
+        OperationType.SET_EPOCH
+    ].includes(type);
+}
+
+const isConsensusControl = type => {
+    return [
+        OperationType.SET_GENESIS_EPOCH,
+        OperationType.SET_CONSENSUS_CONFIG
+    ].includes(type);
+}
+
 const operationToPayload = type => {
     const fromTo = [
         {
@@ -77,6 +97,26 @@ const operationToPayload = type => {
         {
             condition: isBalanceInitialization,
             jsonPath: 'bio'
+        },
+        {
+            condition: type => type === OperationType.HTLC_LOCK,
+            jsonPath: 'hlo'
+        },
+        {
+            condition: type => type === OperationType.HTLC_CLAIM,
+            jsonPath: 'hco'
+        },
+        {
+            condition: type => type === OperationType.HTLC_REFUND,
+            jsonPath: 'hro'
+        },
+        {
+            condition: isSetEpoch,
+            jsonPath: 'seo'
+        },
+        {
+            condition: isConsensusControl,
+            jsonPath: 'cco'
         }
     ]
     const match = fromTo.find(entry => !!entry.condition(type))
@@ -91,5 +131,8 @@ export {
     isBootstrapDeployment,
     operationToPayload,
     isTransfer,
-    isBalanceInitialization
-}
+    isBalanceInitialization,
+    isHtlc,
+    isSetEpoch,
+    isConsensusControl
+}