Protocol Lookup Skill

Use this skill when investigating blockchain protocols, contracts, or events using Herd MCP tools. This skill helps navigate protocol architectures and find the data you need.

When to Use

• •User asks about a DeFi protocol's contracts or events
• •User needs to find event schemas for indexing
• •User wants sample transaction data from a protocol
• •User is exploring an unfamiliar protocol's architecture

Workflow

Step 1: Check Protocol Registry (Optional Acceleration)

First, check if the protocol is in our curated registry:

Read .context/protocol-registry.json

If the protocol exists in the registry:

• •Use pre-computed addresses and event keccak hashes
• •Skip discovery steps
• •Go directly to querying events

If NOT in registry, proceed with discovery workflow below.

Step 2: Discovery Workflow (Generic)

For any protocol, follow this pattern:

2a. Identify Entry Point Contract

Common patterns:

Use mcp__herd__contractMetadataTool on the entry point:

{
  "contractAddress": "<entry_point_address>",
  "blockchain": "<chain>"
}

2b. Understand Architecture

From the contract metadata, identify:

1. •Events emitted - Look in the abi array for type: "event"
2. •Factory functions - Functions that create child contracts (e.g., createPool, createPair, deployVault)
3. •Child contract patterns - Events like PoolCreated, PairCreated, VaultDeployed

2c. Navigate to Child Contracts (if Factory pattern)

If the protocol uses Factory→Child pattern:

1. •Get the child-creation event keccak from the Factory ABI
2. •Query recent child creation events:

{
  "tool": "mcp__herd__getLatestTransactionsTool",
  "params": {
    "type": "event",
    "signature": "<child_created_event_keccak>",
    "contractAddress": "<factory_address>",
    "blockchain": "<chain>"
  }
}

1. •Extract a child contract address from the event output
2. •Query the child contract for its events

2d. Get Target Event Schema

Once you have the contract that emits your target event:

1. •Use contractMetadataTool to get the full ABI
2. •Find the event in the ABI, note its:
   • •keccak_hash (for querying)
   • •inputs (field names, types, indexed status)

Step 3: Get Sample Data

With the event keccak and contract address:

{
  "tool": "mcp__herd__getLatestTransactionsTool",
  "params": {
    "type": "event",
    "signature": "<event_keccak>",
    "contractAddress": "<contract_address>",
    "blockchain": "<chain>"
  }
}

For detailed transaction analysis:

{
  "tool": "mcp__herd__queryTransactionTool",
  "params": {
    "txHash": "<tx_from_previous_query>",
    "returnAllData": true,
    "includeRawData": false
  }
}

Output Format

Always provide:

1. •Contract Addresses - All relevant addresses discovered
2. •Event Schema - Fields, types, indexed status
3. •Event Keccak - For use in pipelines/queries
4. •Sample Data - At least one decoded event
5. •Architecture Notes - How contracts relate to each other

Example output:

## Protocol: [Name]
Chain: [chain]

### Architecture
[Factory/Singleton/etc] pattern
Entry point: [address]
Child contracts: [if applicable]

### Event: [EventName]
Keccak: 0x...
Emitted by: [contract type]

| Field | Type | Indexed |
|-------|------|---------|
| ... | ... | ... |

### Sample Transaction
TX: 0x...
Block: ...
[Decoded event data]

### Key Addresses
- Factory: 0x...
- [Other relevant contracts]

Registry Schema

When adding new protocols to .context/protocol-registry.json:

{
  "protocol-name": {
    "description": "Brief description",
    "chains": {
      "chain-name": {
        "factory": "0x...",           // or "main" for singleton
        "factoryStartBlock": 12345,
        "knownPools": {},              // optional, for popular instances
        "tokens": {}                   // optional, common tokens
      }
    },
    "events": {
      "EventName": {
        "keccak": "0x...",
        "signature": "EventName(type1 name1, ...)",
        "emittedBy": "Factory|Pool|Main"
      }
    },
    "architecture": {
      "pattern": "Factory|Singleton|Registry|Proxy",
      "note": "Brief explanation"
    }
  }
}

Common Protocol Patterns

DEX (Uniswap-style)

• •Factory creates Pools
• •Pools emit: Swap, Mint, Burn
• •Factory emits: PoolCreated, PairCreated

Lending (Aave-style)

• •Single Pool contract
• •Pool emits: Supply, Borrow, Repay, Liquidation
• •May have separate incentives controller

Bridges

• •Often use Lock/Unlock or Burn/Mint events
• •May have relayer contracts

NFT Marketplaces

• •OrderFulfilled, Sale, Bid events
• •Often proxy patterns

Troubleshooting

Can't find events on a contract?

• •Check if it's a proxy - get implementation address
• •Contract may be unverified - limited ABI available

Events not decoding?

• •Verify keccak hash is correct
• •Check if contract uses non-standard event signatures

No recent transactions?

• •Try a different/more active contract instance
• •Check if protocol is active on this chain

Registry out of date?

• •Use discovery workflow to get fresh data
• •Update registry with new findings