get_transaction_status

Instructions

Implementation Reference

• src/services/status.ts:54-102 (handler)

  Core handler function implementing the logic to fetch transaction status from source chain, handle simulated transactions, query bridge status, and return formatted TransactionStatus.

  async getTransactionStatus(
    transactionHash: string,
    fromChainId: SupportedChainId,
    toChainId: SupportedChainId
  ): Promise<TransactionStatus> {
    const fromChainIdTyped = fromChainId as SupportedChainId;
    const toChainIdTyped = toChainId as SupportedChainId;
  
    try {
      // Get transaction details from source chain
      const sourceTransaction = await this.getSourceTransactionDetails(
        transactionHash,
        fromChainIdTyped
      );
  
      // Check if this is a simulated transaction
      if (transactionHash.startsWith('simulated-')) {
        return this.getSimulatedTransactionStatus(
          transactionHash,
          fromChainIdTyped,
          toChainIdTyped
        );
      }
  
      // Get bridge transaction status
      const bridgeStatus = await this.getBridgeTransactionStatus(
        transactionHash,
        fromChainIdTyped,
        toChainIdTyped
      );
  
      return bridgeStatus;
    } catch (error) {
      return {
        transactionHash,
        fromChainId: fromChainIdTyped,
        toChainId: toChainIdTyped,
        status: 'failed',
        steps: [
          {
            name: 'Transaction Query',
            status: 'failed',
            timestamp: Date.now(),
          },
        ],
        errorMessage: error instanceof Error ? error.message : String(error),
      };
    }
  }

• src/index.ts:237-264 (registration)

  Registration of the get_transaction_status tool in the MCP server's tool list, including description and input schema.

    name: 'get_transaction_status',
    description: 'Get the status of a bridge transaction',
    inputSchema: {
      type: 'object',
      properties: {
        transactionHash: {
          type: 'string',
          description: 'Transaction hash to check status for',
        },
        fromChainId: {
          oneOf: [
            { type: 'number' },
            { type: 'string' },
          ],
          description: 'Source chain ID',
        },
        toChainId: {
          oneOf: [
            { type: 'number' },
            { type: 'string' },
          ],
          description: 'Destination chain ID',
        },
      },
      required: ['transactionHash', 'fromChainId', 'toChainId'],
      additionalProperties: false,
    },
  },

• src/index.ts:430-445 (handler)

  MCP server-side handler that processes tool call arguments, delegates to StatusService, and formats the response.

  private async getTransactionStatus(args: any): Promise<MCPToolResult> {
    try {
      const { transactionHash, fromChainId, toChainId } = args;
      const result = await this.statusService.getTransactionStatus(
        transactionHash,
        fromChainId,
        toChainId
      );
      return createSuccessResponse(result);
    } catch (error) {
      return createErrorResponse(
        error instanceof Error ? error.message : String(error),
        'STATUS_ERROR'
      );
    }
  }

• src/index.ts:239-263 (schema)

  Input schema definition for the get_transaction_status tool validating transactionHash, fromChainId, and toChainId.

  inputSchema: {
    type: 'object',
    properties: {
      transactionHash: {
        type: 'string',
        description: 'Transaction hash to check status for',
      },
      fromChainId: {
        oneOf: [
          { type: 'number' },
          { type: 'string' },
        ],
        description: 'Source chain ID',
      },
      toChainId: {
        oneOf: [
          { type: 'number' },
          { type: 'string' },
        ],
        description: 'Destination chain ID',
      },
    },
    required: ['transactionHash', 'fromChainId', 'toChainId'],
    additionalProperties: false,
  },

• src/services/status.ts:197-238 (helper)

  Helper function that generates simulated bridge transaction status with progress steps.

  private async getBridgeTransactionStatus(
    transactionHash: string,
    fromChainId: SupportedChainId,
    toChainId: SupportedChainId
  ): Promise<TransactionStatus> {
    // This would typically query the bridge service API
    // For now, we'll simulate the bridge status
  
    const steps = [
      {
        name: 'Source Transaction',
        status: 'completed' as const,
        transactionHash,
        timestamp: Date.now() - 300000, // 5 minutes ago
      },
      {
        name: 'Bridge Scanning',
        status: 'completed' as const,
        timestamp: Date.now() - 240000, // 4 minutes ago
      },
      {
        name: 'Circle Attestation',
        status: 'completed' as const,
        timestamp: Date.now() - 180000, // 3 minutes ago
      },
      {
        name: 'Destination Minting',
        status: 'processing' as const,
        timestamp: Date.now() - 60000, // 1 minute ago
      },
    ];
  
    return {
      transactionHash,
      fromChainId,
      toChainId,
      status: 'attesting',
      steps,
      fromTxHash: transactionHash,
      toTxHash: undefined, // Will be populated when minting completes
    };
  }