Monitoring your smart contract activity just got easier

We're excited to introduce Event Monitoring for Circle’s Smart Contract Platform. This new feature empowers developers to:

1. Subscribe to events emitted on Ethereum Virtual Machine (EVM) blockchains
2. Receive real-time notifications via webhooks
3. Take programmatic action based on these events.

With Event Monitoring, developers can now track activities on any smart contract or smart contract account in real-time. Developers can subscribe to the events that matter to their use case most or get notified when unusual or unexpected events happen.

Event Monitoring opens up new possibilities for building more dynamic, responsive, and secure on-chain apps. Whether you're managing an ecommerce marketplace, DeFi protocol, or any other smart contract-based app, this feature provides the real-time activity insights you need to stay ahead.

What is Event Monitoring?

Event Monitoring lets you track on-chain events—such as transactions and state changes—in smart contracts. By monitoring these events, developers can take timely actions off-chain. For instance, developers can monitor Circle's Cross-Chain Transfer Protocol (CCTP) smart contracts and subscribe to events whenever someone initiates a USDC transfer across different blockchains. This enables the creation of apps that automatically update transaction statuses, notify users of successful transfers, or trigger additional workflows like updating app interfaces.

For more information on CCTP, see the CCTP Quickstart.

Another example is that developers can set up notifications for unusual or unauthorized activities, such as unexpected transfers or admin function executions, changes in contract state, or failed transactions. Event Monitoring provides immediate notifications for developers to intervene quickly, enhancing app security and reliability.

How do events work on EVM blockchains?

There are a few terms we need to understand when talking about events.

• Event Signatures: The event signature is used to describe the event's name and its parameter types. It's created by hashing the event using the keccak256 hashing function. For example, when wallet A transfers 20 USDC to wallet B, an event of `Transfer(address indexed from, address indexed to, uint256 value)` emits, and its event signature would be:

keccak256("Transfer(address, address, uint256");

• Event Log: An event log records events emitted by smart contracts during their execution. These logs are stored in the blockchain and can be accessed by external applications to track changes or actions that occur in a contract. Each event log consists of two elements: topics and data.
• Topics: Topics are indexed parameters of the logs that are used for filtering logs. Each event emitted can have up to four indexed parameters, with the first topic typically being the event signature. The rest of the topics describe the indexed arguments for the event function In the example above, the first and second parameters are indexed, so they are saved as TOPIC1 and TOPIC2, so developers can filter events by the sending and receiving address. The last parameter isn't indexed and will be saved as data in the event log.‍
• Data: While topics have size limitations, data doesn't and can be used to store the value of other parameters and complex data. In the example above, the amount of USDC being transferred will be stored as a hex string in the data section of the event log.

Below is a sample event log from a Transfer event. TOPIC0 is the eventSignatureHash, the from and to address are TOPIC1 and 2, respectively. The amount of USDC transferred is in the data field.

{
    "blockchain": "ARB-SEPOLIA",
    "txHash": "0x4352e2fcc3559c17aae2e7345fd5d8247a59346a49c1bd50de4df57c63ae8555",
    "logIndex": "1",
    "blockHash": "0x03e16252da7462b2e0460ac6cbdfb2c235305f0aa5028485ec925cfdec490a23",
    "blockHeight": 95030247,
    "contractAddress": "0x6bc50ff08414717f000431558c0b585332c2a53d",
    "eventSignature": "Transfer(address,address,uint256)",
    "eventSignatureHash": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    "topics": [
    	"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x0000000000000000000000000000000000000000000000000000000000000000",
        "0x0000000000000000000000009d7fb3144729fff819fc1aa812d0a261ed8c8676"
    ],
    "data": "0x0000000000000000000000000000000000000000000000000000001cbe991a83",
    "userOpHash": "0xdb5982a91f41ef97ed84c364bc050bbe227f2ce5bd970493755c65c9e7a5abe5",
    "firstConfirmDate": "2024-11-06T23:33:07Z",
}

A sample API response from Get Event Logs.

How to Use Event Monitoring

It only takes three simple steps to setup event notifications:

1. Create a webhook in the Circle Console.

‍

2. Import the smart contract you wish to monitor in the Circle Console or by importing it directly.

‍

3. Subscribe to the events of interest in the Circle Console or by adding event monitors.

‍

That's it! You're all set to start receiving notifications via the webhook.

Once you subscribe to events, you may visit the Monitoring section in the Circle Console to manage all subscriptions and view the event history.

‍

All subscribed events can be viewed and managed in one place

Want to set up Event Monitoring via API? Visit our quickstart guide for a detailed step-by-step tutorial with code snippets.

Use cases

Event monitoring is useful in many ways, including:

Cross-chain USDC transfer tracking

• Event: User initiates USDC transfer from Ethereum to Solana via CCTP
• Action: Update user’s dashboard with transfer progress and send confirmation notification upon completion, providing transparency and assurance to the user.

Instant USDC transfer notifications

• Event: User initiates USDC transfer
• Action: Send automated email/SMS and push notification to the user, ensuring they are immediately aware of the transaction status.

Real-time app portfolio updates

• Event: User receives USDC
• Action: Update user’s portfolio dashboard in real-time, informing users immediately without needing to manually refresh or check multiple platforms.

Unusual activity detection

• Event: Large or unusual USDC transfer detected
• Action: Alert the security team, send a verification request to their user, and temporarily flag the account for review, preventing further transactions until the activity is verified by the user as legitimate.

‍

What’s next?

With the introduction of Event Monitoring, developers can connect on-chain activities to inform off-chain actions. Start integrating with our API and receive real-time notifications that matter to your business.

Don't forget to apply for the Circle Credits Program to receive up to 1,000 credits to cover your mainnet gas fees!

‍

Reviewed by Antony Fleischer, Andrew Klein, Corey Cooper, and Alokik Bhasin.

‍

‍