trac-msb 0.2.26 → 0.3.0-beta.1

package/src/core/state/StateEventQueue.js

@@ -0,0 +1,69 @@
+/**
+ * IMPORTANT
+ * Manages events created by network contracts in the apply function.
+ *
+ * When a valid operation creates an event, the event is stored in this queue
+ * together with the signed length required to publish it. On every Autobase
+ * update, the current signed length is compared with the required signed length.
+ * The event is emitted only when the indexers have signed the related state.
+ *
+ * This makes sure that an event created during apply is not emitted before
+ * its state changes are confirmed by the indexers.
+ *
+ * Currently, only configuration-change events are supported, which is safe
+ * with the expected event volume.
+ *
+ * TODO: Investigate whether other types of events can be safely supported.
+ * Verify that bursts or frequent events (for example, many nodes removing a
+ * writer at the same time) cannot cause excessive memory usage while queued.
+ */
+
+export class StateEventQueue {
+    #pendingBatches = [];
+
+    /**
+     * Adds events created by a successful apply batch.
+     *
+     * @param {Array<{type: string, args?: unknown[]}>} events events to publish
+     * @param {number} requiredSignedLength view length containing the applied changes
+     */
+    enqueue(events, requiredSignedLength) {
+        if (events.length === 0) return;
+
+        const batch = {
+            events,
+            requiredSignedLength,
+        };
+
+        this.#pendingBatches.push(batch);
+    }
+
+    /**
+     * Publishes batches which are already present in the signed view.
+     *
+     * @param {number} signedLength current signed view length
+     * @param {(type: string, ...args: unknown[]) => void} emit event emitter
+     */
+    flush(signedLength, emit) {
+        const waitingBatches = [];
+
+        for (const batch of this.#pendingBatches) {
+            if (batch.requiredSignedLength > signedLength) {
+                waitingBatches.push(batch);
+                continue;
+            }
+
+            for (const event of batch.events) {
+                const args = event.args || [];
+                emit(event.type, ...args);
+            }
+        }
+
+        this.#pendingBatches = waitingBatches;
+    }
+
+    /** Removes events which have not been published yet. */
+    clear() {
+        this.#pendingBatches = [];
+    }
+}

package/src/core/state/utils/address.js

@@ -4,26 +4,28 @@ import _ from 'lodash'
 
 /**
  * Checks if a given address is a valid TRAC bech32m address.
- * Note that we only check the format and length, not the checksum.
- * So, it is possible that even if an address is considered valid,
- * it may not be a real address on the network.
+ * Checks the format, length, and bech32m checksum.
  * @param {string | Buffer} address - The address to validate.
  * @param {string} hrp - The HRP of the bech32m address.
  * @returns {boolean} True if the address is valid, false otherwise.
  */
 export function isAddressValid(address, hrp) {
     if (b4a.isBuffer(address)) {
-        address = address.toString('ascii');
+        const decodedAddress = address.toString('ascii');
+        if (!b4a.equals(address, b4a.from(decodedAddress, 'ascii'))) {
+            return false;
+        }
+        address = decodedAddress;
     }
 
     const res = _.attempt(() => 
-        addressApi.size(hrp) === address.length && address.startsWith(`${hrp}1`) && addressApi.isValid(address)
+        addressApi.size(hrp) === address.length && address.startsWith(`${hrp}1`) &&
+        addressApi.isValid(address) && addressApi.canDecode(address)
     );
 
     return !_.isError(res) && res
 }
 
-
 /**
  * Converts a valid bech32m address string to a buffer.
  * @param {string} bech32mAddress - The bech32m address to convert.
@@ -52,7 +54,9 @@ export function addressToBuffer(bech32mAddress, hrp) {
 // TODO: Do we really need to try-catch here? Maybe we should only validate the input buffer.
 export function bufferToAddress(dataBuffer, hrp) {
     try {
+        if (!b4a.isBuffer(dataBuffer)) return null;
         const address = dataBuffer.toString('ascii');
+        if (!b4a.equals(dataBuffer, b4a.from(address, 'ascii'))) return null;
         if (!isAddressValid(address, hrp)) return null;
         return address;
     } catch (error) {

package/src/core/state/utils/epochProof.js

@@ -0,0 +1,109 @@
+import b4a from 'b4a';
+
+import {
+    HASH_BYTE_LENGTH,
+    SIGNATURE_BYTE_LENGTH,
+    VDF_PROOF_BYTE_LENGTHS,
+    ConsensusVersion
+} from '../../../utils/constants.js';
+import {
+    safeDecodeConsensusConfig,
+    safeEncodeEpochProofV1,
+    safeEncodeEpochRecord
+} from '../../../codecs/apply/applyOperationCodec.js';
+import {safeDecodeVdfConfig} from '../../../codecs/consensus/v1/vdfConfigCodec.js';
+import {safeEncodeProofProposal} from '../../../codecs/consensus/v1/consensusV1OperationCodec.js';
+import {addressToBuffer} from './address.js';
+import {safeUint16ToBuffer} from '../../../utils/buffer.js';
+
+// Apply-only genesis formats. Preserve existing factories for historical replay.
+const GENESIS_EPOCH_FACTORIES = Object.freeze({
+    [ConsensusVersion.VDF_V1]: createVdfV1GenesisEpochProof,
+});
+
+/**
+ * Creates epoch zero using the initial config carried by SET_GENESIS_EPOCH,
+ * not the latest signed config. SET_CONSENSUS_CONFIG must not recreate genesis.
+ *
+ * @param {string} proposerAddress Genesis proposer address.
+ * @param {Buffer} encodedConsensusConfig Encoded initial consensus config.
+ * @param {Config} config Application configuration.
+ * @returns {Promise<Buffer|null>} Encoded { sv, data } genesis epoch record or null on failure.
+ */
+export async function createGenesisEpochProof(proposerAddress, encodedConsensusConfig, config) {
+    const consensusConfig = safeDecodeConsensusConfig(encodedConsensusConfig);
+    if (consensusConfig === null) {
+        return null;
+    }
+
+    const createForSchema = GENESIS_EPOCH_FACTORIES[consensusConfig.sv.readUInt8(0)];
+    if (typeof createForSchema !== 'function') {
+        return null;
+    }
+
+    const genesisData = await createForSchema(config, proposerAddress, consensusConfig.cd);
+    if (!b4a.isBuffer(genesisData) || genesisData.length === 0) {
+        return null;
+    }
+
+    const genesisRecord = safeEncodeEpochRecord({ sv: consensusConfig.sv, data: genesisData });
+    return genesisRecord.length > 0 ? genesisRecord : null;
+}
+
+
+/**
+ * Creates the VDF v1 representation of epoch zero.
+ * The caller wraps these bytes in the versioned epoch record before hashing.
+ *
+ * @param {Config} config Application configuration.
+ * @param {string} proposerAddress Genesis proposer address.
+ * @param {Buffer} encodedConfigData Encoded VDF v1 config.
+ * @returns {Promise<Buffer|null>} Encoded epoch proof or null on validation failure.
+ */
+export async function createVdfV1GenesisEpochProof(config, proposerAddress, encodedConfigData) {
+    const configData = safeDecodeVdfConfig(encodedConfigData);
+    if (configData === null) return null;
+
+    const proposer = addressToBuffer(proposerAddress, config.addressPrefix);
+    if (proposer.length === 0) {
+        return null;
+    }
+
+    const networkId = safeUint16ToBuffer(config.networkId);
+    const { difficulty, discriminantBitSize } = configData;
+    const proofByteLength = VDF_PROOF_BYTE_LENGTHS[discriminantBitSize.readUInt16BE(0)];
+    if (
+        networkId.length === 0 ||
+        !Number.isInteger(proofByteLength)
+    ) {
+        return null;
+    }
+
+    const proofData = {
+        network_id: networkId,
+        epoch: b4a.alloc(8, 0),
+        previous_epoch_record_hash: b4a.alloc(HASH_BYTE_LENGTH, 0),
+        proposer,
+        difficulty,
+        discriminant_bit_size: discriminantBitSize,
+        proof: b4a.alloc(proofByteLength, 0),
+        signature: b4a.alloc(SIGNATURE_BYTE_LENGTH, 0),
+    };
+
+    const encodedProof = safeEncodeProofProposal(proofData);
+    if (encodedProof.length === 0) {
+        return null;
+    }
+
+    const genesisEpochProof = {
+        pd: encodedProof,
+        app: []
+    }
+
+    const encodedEpochProof = safeEncodeEpochProofV1(genesisEpochProof);
+    if (encodedEpochProof.length === 0) {
+        return null;
+    }
+
+    return encodedEpochProof;
+}

package/src/core/state/utils/escrowEntry.js

@@ -0,0 +1,178 @@
+import b4a from 'b4a';
+import tracCryptoApi from 'trac-crypto-api';
+import stateGenerated from '../../../codecs/state/state.generated.cjs';
+import {safeDecodeEscrowEntry, safeEncodeEscrowEntry} from '../../../codecs/state/escrowEntryCodec.js';
+
+import {
+    BALANCE_BYTE_LENGTH,
+    EPOCH_BYTE_LENGTH,
+    HASH_BYTE_LENGTH,
+    HTLC_LOCK_ID_BYTE_LENGTH,
+    HTLC_METADATA_MAX_BYTE_LENGTH,
+    HTLC_PREIMAGE_BYTE_LENGTH,
+    PUBLIC_KEY_LENGTH,
+} from '../../../utils/constants.js';
+import {isBufferValid, isZeroBuffer, NULL_BUFFER} from '../../../utils/buffer.js';
+import {toBalance} from './balance.js';
+import {bufferToAddress} from './address.js';
+
+const {EscrowStatus} = stateGenerated.state;
+
+export const ESCROW_ENTRY_VERSION = 3;
+
+export const Status = Object.freeze({
+    PENDING: EscrowStatus.PENDING,
+    CLAIMED: EscrowStatus.CLAIMED,
+    REFUNDED: EscrowStatus.REFUNDED,
+});
+
+function isRequiredBuffer(value, size) {
+    return isBufferValid(value, size) && !isZeroBuffer(value);
+}
+
+function isSettlementAddress(value, hrp) {
+    const address = bufferToAddress(value, hrp);
+    const publicKey = address && tracCryptoApi.address.decodeSafe(address);
+    return isRequiredBuffer(publicKey, PUBLIC_KEY_LENGTH);
+}
+
+function hasValidSettlementFields({
+    lockId,
+    lockerAddress,
+    claimRecipientAddress,
+    refundRecipientAddress,
+    amount,
+    additionalFeeAmount,
+    additionalFeeRecipientAddress,
+    hashLock,
+    refundEpoch,
+    metadata,
+}, hrp) {
+    const feeIsZero = isBufferValid(additionalFeeAmount, BALANCE_BYTE_LENGTH) && isZeroBuffer(additionalFeeAmount);
+    const requiredFieldsAreValid =
+        isRequiredBuffer(lockId, HTLC_LOCK_ID_BYTE_LENGTH) &&
+        isSettlementAddress(lockerAddress, hrp) &&
+        isSettlementAddress(claimRecipientAddress, hrp) &&
+        isSettlementAddress(refundRecipientAddress, hrp) &&
+        isRequiredBuffer(amount, BALANCE_BYTE_LENGTH) &&
+        isBufferValid(additionalFeeAmount, BALANCE_BYTE_LENGTH) &&
+        isRequiredBuffer(hashLock, HASH_BYTE_LENGTH) &&
+        isRequiredBuffer(refundEpoch, EPOCH_BYTE_LENGTH);
+    const feeFieldsAreValid = feeIsZero
+        ? additionalFeeRecipientAddress === undefined
+        : isSettlementAddress(additionalFeeRecipientAddress, hrp);
+    const metadataIsValid = metadata === undefined || (
+        b4a.isBuffer(metadata) && metadata.length > 0 && metadata.length <= HTLC_METADATA_MAX_BYTE_LENGTH
+    );
+
+    if (!requiredFieldsAreValid || !feeFieldsAreValid || !metadataIsValid) return false;
+
+    const totalLockedAmount = toBalance(amount).add(toBalance(additionalFeeAmount));
+    return totalLockedAmount !== null;
+}
+
+/**
+ * Encodes settlement state using canonical addresses for the configured prefix.
+ * Nonce, signer set, threshold, and signatures remain in the lock transaction.
+ */
+export function init({
+    lockId,
+    lockerAddress,
+    claimRecipientAddress,
+    refundRecipientAddress,
+    amount,
+    additionalFeeAmount,
+    additionalFeeRecipientAddress,
+    hashLock,
+    refundEpoch,
+    metadata,
+} = {}, hrp) {
+    const entry = {
+        version: ESCROW_ENTRY_VERSION,
+        status: Status.PENDING,
+        lockId,
+        lockerAddress,
+        claimRecipientAddress,
+        refundRecipientAddress,
+        amount,
+        additionalFeeAmount,
+        additionalFeeRecipientAddress,
+        hashLock,
+        refundEpoch,
+        metadata,
+    };
+    if (!hasValidSettlementFields(entry, hrp)) return NULL_BUFFER;
+    return safeEncodeEscrowEntry(entry);
+}
+
+export function decode(entry, hrp) {
+    try {
+        const decoded = safeDecodeEscrowEntry(entry);
+        if (
+            !decoded ||
+            decoded.version !== ESCROW_ENTRY_VERSION ||
+            !Object.values(Status).includes(decoded.status) ||
+            !hasValidSettlementFields(decoded, hrp) ||
+            (decoded.preimage !== undefined && !isRequiredBuffer(decoded.preimage, HTLC_PREIMAGE_BYTE_LENGTH)) ||
+            ((decoded.status === Status.CLAIMED) !== (decoded.preimage !== undefined))
+        ) {
+            return null;
+        }
+
+        decoded.additionalFeeRecipientAddress ??= null;
+        decoded.preimage ??= null;
+        decoded.metadata ??= null;
+        return decoded;
+    } catch {
+        return null;
+    }
+}
+
+// Pure escrow transitions; network claim admission and refund application are not wired here.
+export function makeClaim(escrowBuffer, preimage, currentEpoch, hrp) {
+    const escrow = decode(escrowBuffer, hrp);
+    if (
+        !escrow ||
+        escrow.status !== Status.PENDING ||
+        !isRequiredBuffer(preimage, HTLC_PREIMAGE_BYTE_LENGTH) ||
+        !isBufferValid(currentEpoch, EPOCH_BYTE_LENGTH) ||
+        b4a.compare(currentEpoch, escrow.refundEpoch) >= 0 ||
+        !b4a.equals(tracCryptoApi.hash.sha256(preimage), escrow.hashLock)
+    ) {
+        return null;
+    }
+
+    const claimedEntry = safeEncodeEscrowEntry({...escrow, status: Status.CLAIMED, preimage});
+    if (claimedEntry.length === 0) return null;
+
+    return {
+        address: escrow.claimRecipientAddress,
+        amount: toBalance(escrow.amount),
+        additionalFeeRecipientAddress: escrow.additionalFeeRecipientAddress,
+        additionalFeeAmount: toBalance(escrow.additionalFeeAmount),
+        claimedEscrowEntry: claimedEntry,
+    };
+}
+
+export function makeRefund(escrowBuffer, currentEpoch, hrp) {
+    const escrow = decode(escrowBuffer, hrp);
+    if (
+        !escrow ||
+        escrow.status !== Status.PENDING ||
+        !isBufferValid(currentEpoch, EPOCH_BYTE_LENGTH) ||
+        b4a.compare(currentEpoch, escrow.refundEpoch) < 0
+    ) {
+        return null;
+    }
+
+    const refundAmount = toBalance(escrow.amount)?.add(toBalance(escrow.additionalFeeAmount));
+    if (!refundAmount) return null;
+    const refundedEscrowEntry = safeEncodeEscrowEntry({...escrow, status: Status.REFUNDED});
+    if (refundedEscrowEntry.length === 0) return null;
+
+    return {
+        address: escrow.refundRecipientAddress,
+        amount: refundAmount,
+        refundedEscrowEntry,
+    };
+}