trac-msb 0.2.17 → 0.2.19

package/src/core/network/protocols/v1/handlers/V1BroadcastTransactionOperationHandler.js

@@ -0,0 +1,272 @@
+import {networkMessageFactory} from "../../../../../messages/network/v1/networkMessageFactory.js";
+import {
+    NETWORK_CAPABILITIES,
+    ResultCode
+} from "../../../../../utils/constants.js";
+import {
+    getResultCode,
+    V1ProtocolError
+} from "../V1ProtocolError.js";
+import V1BroadcastTransactionRequest from "../validators/V1BroadcastTransactionRequest.js";
+import {
+    unsafeDecodeApplyOperation,
+    unsafeEncodeApplyOperation
+} from "../../../../../utils/protobuf/operationHelpers.js";
+import PartialRoleAccessValidator from "../../shared/validators/PartialRoleAccessValidator.js";
+import PartialBootstrapDeploymentValidator from "../../shared/validators/PartialBootstrapDeploymentValidator.js";
+import PartialTransactionValidator from "../../shared/validators/PartialTransactionValidator.js";
+import PartialTransferValidator from "../../shared/validators/PartialTransferValidator.js";
+import {applyStateMessageFactory} from "../../../../../messages/state/applyStateMessageFactory.js";
+import V1BroadcastTransactionResponse from "../validators/V1BroadcastTransactionResponse.js";
+import V1BaseOperationHandler from "./V1BaseOperationHandler.js";
+import {
+    createBroadcastTransactionOperationStrategies,
+    resolveBroadcastTransactionOperationStrategy
+} from "./broadcastTransaction/BroadcastTransactionOperationStrategies.js";
+import {
+    getTxHashFromDecodedTransaction,
+    sanitizeDecodedPartialTransaction
+} from "./broadcastTransaction/BroadcastTransactionPayloadUtils.js";
+import {
+    mapPendingCommitRegistrationError,
+    mapPendingCommitResolutionError,
+    mapTransactionEnqueueError,
+    mapTxPoolAvailabilityError
+} from "./broadcastTransaction/BroadcastTransactionErrorMapper.js";
+import {shouldEndConnection} from "../../connectionPolicies.js";
+
+class V1BroadcastTransactionOperationHandler extends V1BaseOperationHandler {
+    #state;
+    #wallet;
+    #txPoolService;
+    #broadcastTransactionRequestValidator;
+    #broadcastTransactionResponseValidator;
+    #partialRoleAccessValidator;
+    #partialBootstrapDeploymentValidator;
+    #partialTransactionValidator;
+    #partialTransferValidator;
+    #transactionCommitService;
+    #operationStrategies;
+
+    constructor(state, wallet, rateLimiterService, txPoolService, pendingRequestService, transactionCommitService, config) {
+        super(rateLimiterService, pendingRequestService, config);
+        this.#state = state;
+        this.#wallet = wallet;
+        this.#txPoolService = txPoolService;
+        this.#broadcastTransactionRequestValidator = new V1BroadcastTransactionRequest(config);
+        this.#partialRoleAccessValidator = new PartialRoleAccessValidator(state, this.#wallet.address, config);
+        this.#partialBootstrapDeploymentValidator = new PartialBootstrapDeploymentValidator(state, this.#wallet.address, config);
+        this.#partialTransactionValidator = new PartialTransactionValidator(state, this.#wallet.address, config);
+        this.#partialTransferValidator = new PartialTransferValidator(state, this.#wallet.address, config);
+        this.#broadcastTransactionResponseValidator = new V1BroadcastTransactionResponse(state, config);
+        this.#transactionCommitService = transactionCommitService;
+        this.#operationStrategies = createBroadcastTransactionOperationStrategies({
+            partialRoleAccessValidator: this.#partialRoleAccessValidator,
+            partialBootstrapDeploymentValidator: this.#partialBootstrapDeploymentValidator,
+            partialTransactionValidator: this.#partialTransactionValidator,
+            partialTransferValidator: this.#partialTransferValidator,
+            createApplyStateMessageFactory: () => applyStateMessageFactory(this.#wallet, this.config)
+        });
+    }
+
+    async handleRequest(message, connection) {
+        const outcome = await this.#processBroadcastTransactionRequest(message, connection);
+        await this.#sendBroadcastTransactionResponse(message.id, connection, outcome);
+    }
+
+    async handleResponse(message, connection) {
+        try {
+            this.applyRateLimit(connection);
+            await this.resolvePendingResponse(
+                message,
+                connection,
+                this.#broadcastTransactionResponseValidator,
+                this.#extractBroadcastResultCode,
+            );
+        } catch (error) {
+            this.handlePendingResponseError(
+                message.id,
+                connection,
+                error,
+                "failed to process broadcast transaction response from sender"
+            );
+        }
+    }
+
+    async #buildBroadcastTransactionResponse(id, capabilities, proof, timestamp = null, resultCode) {
+        try {
+            return await networkMessageFactory(this.#wallet, this.config).buildBroadcastTransactionResponse(
+                id,
+                capabilities,
+                resultCode,
+                proof,
+                timestamp
+            );
+        } catch (error) {
+            throw new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, `Failed to build broadcast transaction response: ${error.message}`);
+        }
+    }
+
+    decodeApplyOperation(message) {
+        try {
+            return unsafeDecodeApplyOperation(message);
+        } catch (error) {
+            throw new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, `Failed to decode apply operation from message: ${error.message}`);
+        }
+    }
+
+    async #processBroadcastTransactionRequest(message, connection) {
+        let proof = null;
+        let timestamp = 0;
+
+        try {
+            this.applyRateLimit(connection);
+            await this.#broadcastTransactionRequestValidator.validate(message, connection.remotePublicKey);
+            await this.#validateWriteCapability();
+            this.#validateTxPoolAvailability();
+            const decodedTransaction = this.decodeApplyOperation(message.broadcast_transaction_request.data);
+            sanitizeDecodedPartialTransaction(decodedTransaction);
+            const receipt = await this.dispatchTransaction(decodedTransaction);
+            proof = receipt.proof;
+            timestamp = receipt.timestamp;
+        } catch (error) {
+            return this.#buildFailedRequestOutcome(error, connection);
+        }
+
+        return {
+            endConnection: false,
+            proof,
+            resultCode: ResultCode.OK,
+            timestamp
+        };
+    }
+
+    #buildFailedRequestOutcome(error, connection) {
+        const protocolError = error instanceof V1ProtocolError
+            ? error
+            : new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, error?.message ?? 'Unexpected error');
+        const resultCode = getResultCode(protocolError);
+        let timestamp = 0;
+
+        if (
+            resultCode === ResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE &&
+            Number.isSafeInteger(protocolError.timestamp) &&
+            protocolError.timestamp > 0
+        ) {
+            timestamp = protocolError.timestamp;
+        }
+
+        this.displayError(
+            "failed to process broadcast transaction request from sender",
+            connection.remotePublicKey,
+            protocolError
+        );
+
+        return {
+            endConnection: shouldEndConnection(resultCode),
+            proof: null,
+            resultCode,
+            timestamp
+        };
+    }
+
+    async #sendBroadcastTransactionResponse(messageId, connection, {proof, timestamp, resultCode, endConnection}) {
+        try {
+            const response = await this.#buildBroadcastTransactionResponse(
+                messageId,
+                NETWORK_CAPABILITIES,
+                proof,
+                timestamp,
+                resultCode,
+            );
+
+            await this.sendResponseAndMaybeClose(
+                connection,
+                response,
+                endConnection
+            );
+        } catch (error) {
+            this.displayError(
+                "failed to build/send response to sender",
+                connection.remotePublicKey,
+                error
+            );
+            connection.end();
+        }
+    }
+
+    #validateTxPoolAvailability() {
+        try {
+            this.#txPoolService.validateEnqueue();
+        } catch (error) {
+            throw mapTxPoolAvailabilityError(error);
+        }
+    }
+
+    async #validateWriteCapability() {
+        const isAllowedToValidate = await this.#state.allowedToValidate(this.#wallet.address);
+        const isAdminAllowedToValidate = await this.#state.isAdminAllowedToValidate();
+        const canValidate = isAllowedToValidate || isAdminAllowedToValidate;
+        if (!canValidate) {
+            throw new V1ProtocolError(
+                ResultCode.NODE_HAS_NO_WRITE_ACCESS,
+                'State is not writable or is an indexer without admin privileges.'
+            );
+        }
+    }
+
+    async dispatchTransaction(decodedTransaction) {
+        if (!decodedTransaction || !Number.isInteger(decodedTransaction.type) || decodedTransaction.type === 0) {
+            throw new V1ProtocolError(ResultCode.TX_INVALID_PAYLOAD, 'Decoded transaction type is missing.');
+        }
+        if (!this.#transactionCommitService) {
+            throw new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, 'TransactionCommitService is not configured.');
+        }
+
+        const operationStrategy = resolveBroadcastTransactionOperationStrategy(
+            decodedTransaction.type,
+            this.#operationStrategies
+        );
+        const completeTransactionOperation = await operationStrategy.build(decodedTransaction);
+        const txHash = getTxHashFromDecodedTransaction(decodedTransaction, operationStrategy.payloadKey);
+        const encodedCompleteTransaction = unsafeEncodeApplyOperation(completeTransactionOperation);
+        const pendingCommit = this.#registerPendingCommit(txHash);
+
+        this.#enqueueTransaction(txHash, encodedCompleteTransaction);
+        return this.#resolvePendingCommit(pendingCommit);
+    }
+
+    #registerPendingCommit(txHash) {
+        try {
+            const pendingCommit = this.#transactionCommitService.registerPendingCommit(txHash);
+            pendingCommit.catch(() => {});
+            return pendingCommit;
+        } catch (error) {
+            throw mapPendingCommitRegistrationError(error);
+        }
+    }
+
+    #enqueueTransaction(txHash, encodedCompleteTransaction) {
+        try {
+            this.#txPoolService.addTransaction(txHash, encodedCompleteTransaction);
+        } catch (error) {
+            const mappedError = mapTransactionEnqueueError(error);
+            this.#transactionCommitService.rejectPendingCommit(txHash, mappedError);
+            throw mappedError;
+        }
+    }
+
+    async #resolvePendingCommit(pendingCommit) {
+        try {
+            return await pendingCommit;
+        } catch (error) {
+            throw mapPendingCommitResolutionError(error);
+        }
+    }
+
+    #extractBroadcastResultCode(payload) {
+        return payload.broadcast_transaction_response.result;
+    }
+}
+
+export default V1BroadcastTransactionOperationHandler;

package/src/core/network/protocols/v1/handlers/V1LivenessOperationHandler.js

@@ -0,0 +1,88 @@
+import {networkMessageFactory} from "../../../../../messages/network/v1/networkMessageFactory.js";
+import {NETWORK_CAPABILITIES, ResultCode} from "../../../../../utils/constants.js";
+import V1LivenessRequest from "../validators/V1LivenessRequest.js";
+import {getResultCode, V1ProtocolError} from "../V1ProtocolError.js";
+import V1LivenessResponse from "../validators/V1LivenessResponse.js";
+import V1BaseOperationHandler from "./V1BaseOperationHandler.js";
+import {shouldEndConnection} from "../../connectionPolicies.js"
+
+class V1LivenessOperationHandler extends V1BaseOperationHandler {
+    #wallet;
+    #v1LivenessRequestValidator;
+    #v1LivenessResponseValidator;
+
+    constructor(wallet, rateLimiterService, pendingRequestService, config) {
+        super(rateLimiterService, pendingRequestService, config);
+        this.#wallet = wallet;
+        this.#v1LivenessRequestValidator = new V1LivenessRequest(config);
+        this.#v1LivenessResponseValidator = new V1LivenessResponse(config);
+    }
+
+    async handleRequest(message, connection) {
+        let resultCode = ResultCode.OK;
+        let endConnection = false;
+        try {
+            this.applyRateLimit(connection);
+            await this.#v1LivenessRequestValidator.validate(message, connection.remotePublicKey);
+        } catch (error) {
+            resultCode = getResultCode(error);
+            endConnection = shouldEndConnection(resultCode);
+            this.displayError("failed to process liveness request from sender",
+                connection.remotePublicKey,
+                error
+            );
+        }
+
+        try {
+            const response = await this.#buildLivenessResponsePayload(message.id, NETWORK_CAPABILITIES, resultCode);
+            await this.sendResponseAndMaybeClose(
+                connection,
+                response,
+                endConnection
+            );
+        } catch (error) {
+            this.displayError("failed to build/send response to sender",
+                connection.remotePublicKey,
+                error
+            );
+            connection.end();
+        }
+    }
+
+    async handleResponse(message, connection) {
+        try {
+            this.applyRateLimit(connection);
+            await this.resolvePendingResponse(
+                message,
+                connection,
+                this.#v1LivenessResponseValidator,
+                this.#extractLivenessResultCode
+            );
+        } catch (error) {
+            this.handlePendingResponseError(
+                message.id,
+                connection,
+                error,
+                "Failed to process liveness response from sender"
+            );
+        }
+    }
+
+    async #buildLivenessResponsePayload(id, capabilities, resultCode) {
+        try {
+            return await networkMessageFactory(this.#wallet, this.config).buildLivenessResponse(
+                id,
+                capabilities,
+                resultCode
+            );
+        } catch (error) {
+            throw new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, `Failed to build liveness response: ${error.message}`);
+        }
+    }
+
+    #extractLivenessResultCode(payload) {
+        return payload.liveness_response.result;
+    }
+}
+
+export default V1LivenessOperationHandler;

package/src/core/network/protocols/v1/handlers/broadcastTransaction/BroadcastTransactionErrorMapper.js

@@ -0,0 +1,84 @@
+import {ResultCode} from "../../../../../../utils/constants.js";
+import {V1ProtocolError} from "../../V1ProtocolError.js";
+import {
+    TransactionPoolAlreadyQueuedError,
+    TransactionPoolFullError,
+    TransactionPoolInvalidIncomingDataError,
+    TransactionPoolMissingCommitReceiptError,
+    TransactionPoolProofUnavailableError
+} from "../../../../services/TransactionPoolService.js";
+import {
+    PendingCommitAlreadyExistsError,
+    PendingCommitBufferFullError,
+    PendingCommitInvalidTxHashError,
+    PendingCommitTimeoutError
+} from "../../../../services/TransactionCommitService.js";
+
+export function mapTxPoolAvailabilityError(error) {
+    if (error instanceof TransactionPoolFullError) {
+        return new V1ProtocolError(
+            ResultCode.NODE_OVERLOADED,
+            'Transaction pool is full, ignoring incoming transaction.'
+        );
+    }
+
+    return error;
+}
+
+export function mapPendingCommitRegistrationError(error) {
+    if (error instanceof PendingCommitInvalidTxHashError) {
+        return new V1ProtocolError(ResultCode.TX_HASH_INVALID_FORMAT, error.message);
+    }
+
+    if (error instanceof PendingCommitAlreadyExistsError) {
+        return new V1ProtocolError(ResultCode.TX_ALREADY_PENDING, error.message);
+    }
+
+    if (error instanceof PendingCommitBufferFullError) {
+        return new V1ProtocolError(ResultCode.NODE_OVERLOADED, error.message);
+    }
+
+    return error;
+}
+
+export function mapTransactionEnqueueError(error) {
+    if (error instanceof TransactionPoolFullError) {
+        return new V1ProtocolError(ResultCode.NODE_OVERLOADED, error.message);
+    }
+
+    if (error instanceof TransactionPoolAlreadyQueuedError) {
+        return new V1ProtocolError(ResultCode.TX_ALREADY_PENDING, error.message);
+    }
+
+    if (error instanceof TransactionPoolInvalidIncomingDataError) {
+        return new V1ProtocolError(
+            ResultCode.INTERNAL_ENQUEUE_VALIDATION_FAILED,
+            `Internal enqueue validation failed: ${error.message}`
+        );
+    }
+
+    return error;
+}
+
+export function mapPendingCommitResolutionError(error) {
+    if (error instanceof TransactionPoolProofUnavailableError) {
+        const protocolError = new V1ProtocolError(
+            ResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE,
+            error.message
+        );
+        protocolError.timestamp = Number.isSafeInteger(error.timestamp) && error.timestamp > 0
+            ? error.timestamp
+            : 0;
+        return protocolError;
+    }
+
+    if (error instanceof TransactionPoolMissingCommitReceiptError) {
+        return new V1ProtocolError(ResultCode.TX_COMMITTED_RECEIPT_MISSING, error.message);
+    }
+
+    if (error instanceof PendingCommitTimeoutError) {
+        return new V1ProtocolError(ResultCode.TIMEOUT, error.message);
+    }
+
+    return error;
+}

package/src/core/network/protocols/v1/handlers/broadcastTransaction/BroadcastTransactionOperationStrategies.js

@@ -0,0 +1,128 @@
+import {OperationType, ResultCode} from "../../../../../../utils/constants.js";
+import {V1ProtocolError} from "../../V1ProtocolError.js";
+
+function createOperationStrategy(payloadKey, validator, buildCompleteOperation) {
+    return {
+        payloadKey,
+        async build(decodedTransaction) {
+            await validator.validate(decodedTransaction);
+            return buildCompleteOperation(decodedTransaction);
+        }
+    };
+}
+
+export function createBroadcastTransactionOperationStrategies({
+    partialRoleAccessValidator,
+    partialBootstrapDeploymentValidator,
+    partialTransactionValidator,
+    partialTransferValidator,
+    createApplyStateMessageFactory
+}) {
+    return new Map([
+        [
+            OperationType.ADD_WRITER,
+            createOperationStrategy(
+                'rao',
+                partialRoleAccessValidator,
+                decodedTransaction => createApplyStateMessageFactory().buildCompleteAddWriterMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.rao.tx,
+                    decodedTransaction.rao.txv,
+                    decodedTransaction.rao.iw,
+                    decodedTransaction.rao.in,
+                    decodedTransaction.rao.is
+                )
+            )
+        ],
+        [
+            OperationType.REMOVE_WRITER,
+            createOperationStrategy(
+                'rao',
+                partialRoleAccessValidator,
+                decodedTransaction => createApplyStateMessageFactory().buildCompleteRemoveWriterMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.rao.tx,
+                    decodedTransaction.rao.txv,
+                    decodedTransaction.rao.iw,
+                    decodedTransaction.rao.in,
+                    decodedTransaction.rao.is
+                )
+            )
+        ],
+        [
+            OperationType.ADMIN_RECOVERY,
+            createOperationStrategy(
+                'rao',
+                partialRoleAccessValidator,
+                decodedTransaction => createApplyStateMessageFactory().buildCompleteAdminRecoveryMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.rao.tx,
+                    decodedTransaction.rao.txv,
+                    decodedTransaction.rao.iw,
+                    decodedTransaction.rao.in,
+                    decodedTransaction.rao.is
+                )
+            )
+        ],
+        [
+            OperationType.TX,
+            createOperationStrategy(
+                'txo',
+                partialTransactionValidator,
+                decodedTransaction => createApplyStateMessageFactory().buildCompleteTransactionOperationMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.txo.tx,
+                    decodedTransaction.txo.txv,
+                    decodedTransaction.txo.iw,
+                    decodedTransaction.txo.in,
+                    decodedTransaction.txo.ch,
+                    decodedTransaction.txo.is,
+                    decodedTransaction.txo.bs,
+                    decodedTransaction.txo.mbs
+                )
+            )
+        ],
+        [
+            OperationType.BOOTSTRAP_DEPLOYMENT,
+            createOperationStrategy(
+                'bdo',
+                partialBootstrapDeploymentValidator,
+                decodedTransaction => createApplyStateMessageFactory().buildCompleteBootstrapDeploymentMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.bdo.tx,
+                    decodedTransaction.bdo.txv,
+                    decodedTransaction.bdo.bs,
+                    decodedTransaction.bdo.ic,
+                    decodedTransaction.bdo.in,
+                    decodedTransaction.bdo.is
+                )
+            )
+        ],
+        [
+            OperationType.TRANSFER,
+            createOperationStrategy(
+                'tro',
+                partialTransferValidator,
+                decodedTransaction => createApplyStateMessageFactory().buildCompleteTransferOperationMessage(
+                    decodedTransaction.address,
+                    decodedTransaction.tro.tx,
+                    decodedTransaction.tro.txv,
+                    decodedTransaction.tro.in,
+                    decodedTransaction.tro.to,
+                    decodedTransaction.tro.am,
+                    decodedTransaction.tro.is
+                )
+            )
+        ]
+    ]);
+}
+
+export function resolveBroadcastTransactionOperationStrategy(type, operationStrategies) {
+    const operationStrategy = operationStrategies.get(type);
+
+    if (!operationStrategy) {
+        throw new V1ProtocolError(ResultCode.TX_INVALID_PAYLOAD, `Unsupported transaction type: ${type}`);
+    }
+
+    return operationStrategy;
+}

package/src/core/network/protocols/v1/handlers/broadcastTransaction/BroadcastTransactionPayloadUtils.js

@@ -0,0 +1,26 @@
+import b4a from "b4a";
+
+import { operationToPayload } from "../../../../../../utils/applyOperations.js";
+
+const COMPLETION_FIELDS = ['va', 'vn', 'vs'];
+
+export function sanitizeDecodedPartialTransaction(decodedTransaction) {
+    const operationKey = operationToPayload(decodedTransaction?.type);
+    const operation = decodedTransaction?.[operationKey];
+
+    if (!operation || typeof operation !== 'object') {
+        return;
+    }
+
+    for (const completionField of COMPLETION_FIELDS) {
+        // Protobuf decode sets optional completion fields as null, but partial validators expect those fields to be absent.
+        // Otherwise, the presence of null fields causes validation to fail with "Expected type X but got null" errors.
+        if (operation[completionField] === null) {
+            delete operation[completionField];
+        }
+    }
+}
+
+export function getTxHashFromDecodedTransaction(decodedTransaction, payloadKey = operationToPayload(decodedTransaction?.type)) {
+    return b4a.toString(decodedTransaction[payloadKey].tx, 'hex');
+}