Arbitrum MCP Server

Instructions

Implementation Reference

• src/index.ts:740-757 (handler)

  MCP tool handler for 'assertion_status': resolves RPC URL or chain name, instantiates ArbitrumChainClient, calls getAssertionStatus with parentRpcUrl and rollupAddress, returns JSON-stringified result.

  case "assertion_status": {
    const rpcUrl = await this.resolveRpcUrl(
      (args.rpcUrl as string) || (args.chainName as string)
    );
    const chainDataClient = new ArbitrumChainClient(rpcUrl);
    const status = await chainDataClient.getAssertionStatus(
      args.parentRpcUrl as string,
      args.rollupAddress as string
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(status, null, 2),
        },
      ],
    };
  }

• src/index.ts:1591-1619 (registration)

  Tool registration entry in getAvailableTools(): defines name 'assertion_status', detailed description, and inputSchema requiring parentRpcUrl and rollupAddress.

  {
    name: "assertion_status",
    description:
      "Monitor assertion creation and confirmation activity. Tracks NodeCreated vs NodeConfirmed events to understand rollup validation status. Critical for PM and support teams to monitor chain security and finality.",
    inputSchema: {
      type: "object" as const,
      properties: {
        rpcUrl: {
          type: "string",
          description:
            "The RPC URL of the Arbitrum chain (optional if default is set)",
        },
        chainName: {
          type: "string",
          description:
            "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL",
        },
        parentRpcUrl: {
          type: "string",
          description: "Parent chain RPC URL (e.g., Ethereum mainnet RPC)",
        },
        rollupAddress: {
          type: "string",
          description: "Rollup contract address",
        },
      },
      required: ["parentRpcUrl", "rollupAddress"],
    },
  },

• src/clients/arbitrum-chain-client.ts:14-19 (schema)

  TypeScript interface AssertionStatus defining the structure of the tool's output: latest created/confirmed assertions, gap between them, and summary.

  export interface AssertionStatus {
    latestCreatedAssertion: string | null;
    latestConfirmedAssertion: string | null;
    creationConfirmationGap: string;
    summary: string;
  }

• src/clients/arbitrum-chain-client.ts:167-245 (helper)

  Helper method getAssertionStatus in ArbitrumChainClient: fetches recent logs for NodeCreated and NodeConfirmed events from rollupAddress on parentRpcUrl, computes latest assertions and confirmation gap.

  async getAssertionStatus(
    parentRpcUrl: string,
    rollupAddress: string
  ): Promise<AssertionStatus> {
    try {
      const parentClient = createPublicClient({
        transport: http(parentRpcUrl),
      });
  
      const nodeCreatedEventAbi = {
        anonymous: false,
        inputs: [
          { indexed: true, name: "nodeNum", type: "uint64" },
          { indexed: true, name: "parentNodeHash", type: "bytes32" },
          { indexed: true, name: "nodeHash", type: "bytes32" },
          { indexed: false, name: "executionHash", type: "bytes32" },
        ],
        name: "NodeCreated",
        type: "event",
      } as const;
  
      const nodeConfirmedEventAbi = {
        anonymous: false,
        inputs: [
          { indexed: true, name: "nodeNum", type: "uint64" },
          { indexed: false, name: "blockHash", type: "bytes32" },
          { indexed: false, name: "sendRoot", type: "bytes32" },
        ],
        name: "NodeConfirmed",
        type: "event",
      } as const;
  
      const latestBlockNumber = await parentClient.getBlockNumber();
      const fromBlock = latestBlockNumber - BigInt(50000);
  
      const [createdLogs, confirmedLogs] = await Promise.all([
        parentClient.getLogs({
          address: rollupAddress as `0x${string}`,
          event: nodeCreatedEventAbi,
          fromBlock,
          toBlock: latestBlockNumber,
        }),
        parentClient.getLogs({
          address: rollupAddress as `0x${string}`,
          event: nodeConfirmedEventAbi,
          fromBlock,
          toBlock: latestBlockNumber,
        })
      ]);
  
      const latestCreatedAssertion = createdLogs.length > 0 
        ? createdLogs[createdLogs.length - 1].args?.nodeNum || null
        : null;
  
      const latestConfirmedAssertion = confirmedLogs.length > 0 
        ? confirmedLogs[confirmedLogs.length - 1].args?.nodeNum || null
        : null;
  
      const creationConfirmationGap = (latestCreatedAssertion && latestConfirmedAssertion) 
        ? latestCreatedAssertion - latestConfirmedAssertion 
        : 0n;
  
      const summary = `Latest created assertion: ${latestCreatedAssertion || 'None'}, Latest confirmed: ${latestConfirmedAssertion || 'None'}. Gap: ${creationConfirmationGap}`;
  
      return {
        latestCreatedAssertion: latestCreatedAssertion ? latestCreatedAssertion.toString() : null,
        latestConfirmedAssertion: latestConfirmedAssertion ? latestConfirmedAssertion.toString() : null,
        creationConfirmationGap: creationConfirmationGap.toString(),
        summary
      };
    } catch (error) {
      return {
        latestCreatedAssertion: null,
        latestConfirmedAssertion: null,
        creationConfirmationGap: "0",
        summary: `Error checking assertions: ${error instanceof Error ? error.message : 'Unknown error'}`
      };
    }
  }