Subscribe

Subscribes to smart contract events in real-time, monitoring the blockchain for specific events and triggering automation when they occur.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• Client ID - The client ID from the Create Client node.
• Contract Address - The smart contract address to monitor.
• ABI - The ABI ID from the Parse ABI node.
• Event Name - The name of the event to subscribe to (e.g., "Transfer", "Approval").

Output

This node has 2 outputs:

• Output 1 (default) - Not used
• Output 2 (event) - Triggered when the event is emitted, contains the event data

Options

• Event Parameters - Optional array of parameter values to filter events.
• Once - If enabled, emits only once then stops the subscription.

How It Works

The Subscribe node monitors blockchain events in real-time. When executed, the node:

1. Connects to the blockchain via WebSocket
2. Sets up filters based on event signature and parameters
3. Subscribes to the contract's event logs
4. Waits for matching events
5. When an event occurs, processes it and emits on output 2
6. Continues monitoring until flow stops (unless "Once" is enabled)

Requirements

• A WebSocket RPC endpoint (wss://)
• Valid Client ID and contract address
• Parsed ABI with the event definition
• Correct event name matching the ABI

Error Handling

The node will return errors for:

• Invalid Client ID or connection failure
• Invalid contract address
• ABI not found or event not in ABI
• WebSocket connection errors
• Invalid event parameters

Event Filtering

No filters: Receives all occurrences of the event.

With parameters: Only receives events matching specified indexed parameters.

Parameter format:

// Single value
["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"]

// Multiple values (OR condition)
[
  ["0x742d35...", "0x1234..."],  // Match either address
  "0xabcd..."                     // And this value
]

Usage Notes

• Requires WebSocket connection (not HTTP)
• Subscription persists until flow stops
• Events are emitted on output 2
• Use "Once" option for single-event triggers
• Multiple subscriptions can run simultaneously
• Events are delivered in near real-time (seconds delay)
• Only indexed parameters can be filtered

Example

Monitoring ERC20 transfers:

Inputs:

• Client ID: 7e8f9a0b-1c2d-3e4f-5a6b-7c8d9e0f1a2b (with wss:// endpoint)
• Contract Address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC)
• ABI: a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6
• Event Name: Transfer

Options:

• Event Parameters: (empty for all transfers)
• Once: false (continuous monitoring)

Event data received on output 2:

{
  "id": "...",
  "log": {
    "address": "0xA0b869...",
    "topics": [
      "0xddf252ad...",  // Transfer event signature
      "0x000...742d",   // from address (indexed)
      "0x000...1234"    // to address (indexed)
    ],
    "data": "0x...05f5e100",  // amount (non-indexed)
    "blockNumber": 15123456,
    "transactionHash": "0x...",
    "transactionIndex": 45,
    "blockHash": "0x...",
    "logIndex": 67
  }
}

Monitoring specific address:

Options:

• Event Parameters:

  [
    null,  // Any from address
    "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"  // Specific to address
  ]

Common Use Cases

Transfer Monitoring: Watch for token transfers to/from specific addresses.

Approval Tracking: Monitor token approval events for security.

NFT Events: Track minting, transfers, or sales of NFTs.

DeFi Automation: Respond to events from lending, staking, or DEX contracts.

Oracle Updates: Monitor price feed updates from oracle contracts.

Governance Events: Track proposal creation, voting, and execution.

Event Structure

ERC20 Transfer Event:

event Transfer(
  address indexed from,
  address indexed to,
  uint256 value
)

In the log:

• topics[0] - Event signature hash
• topics[1] - from address (indexed)
• topics[2] - to address (indexed)
• data - value amount (not indexed)

Processing Event Data

Extract log data:

eventLog = message.log

contractAddress = eventLog.address
blockNumber = eventLog.blockNumber
transactionHash = eventLog.transactionHash

// Decode using Decode node
from = topics[1]  // Remove padding
to = topics[2]    // Remove padding
amount = decodeData(data)

Subscription Patterns

Continuous monitoring:

Subscribe → Process Event → Store/Alert → (repeat)

One-time trigger:

Subscribe (Once=true) → Event → Trigger Action → Stop

Filtered monitoring:

Subscribe (with filters) → Specific Events → Conditional Logic

Multiple Subscriptions

Monitor different events:

Flow:
  Subscribe (Transfer) → Process Transfers
  Subscribe (Approval) → Process Approvals
  Subscribe (Swap) → Process Swaps

Monitor multiple contracts:

Flow:
  Subscribe (Contract A) → Process A Events
  Subscribe (Contract B) → Process B Events

WebSocket Requirements

RPC endpoint must support:

• WebSocket protocol (wss://)
• eth_subscribe method
• Event log subscriptions

Providers with WebSocket:

• Infura: wss://mainnet.infura.io/ws/v3/YOUR_KEY
• Alchemy: wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
• QuickNode: Custom WebSocket endpoint

Performance Considerations

Subscription overhead:

• WebSocket connection stays open
• Continuous network traffic
• Memory for buffering events
• Processing time for each event

Optimization:

• Use specific filters to reduce events
• Process events asynchronously
• Batch similar events when possible
• Close subscriptions when not needed

Reliability

Connection management:

• Subscription persists during flow execution
• Auto-reconnection not guaranteed
• Lost events during disconnection
• Manual restart needed after errors

Best practices:

• Monitor subscription health
• Store processed event block numbers
• Can replay missed events by querying logs
• Have fallback for connection failures

Event Filtering Examples

Any transfer to specific address:

[
  null,  // From: any
  "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"  // To: specific
]

Transfers between two specific addresses:

[
  "0x1111111111111111111111111111111111111111",  // From
  "0x2222222222222222222222222222222222222222"   // To
]

Multiple possible values (OR):

[
  ["0x1111...", "0x2222...", "0x3333..."],  // From: any of these
  null  // To: any
]

Decoding Events

After receiving an event, decode the data:

1. Extract Topics - Get indexed parameters
2. Extract Data - Get non-indexed parameters
3. Decode Node - Parse using ABI
4. Process - Use decoded values

Example flow:

Subscribe → Extract Log → Decode Event Data → Process Values

Error Handling

Connection errors:

try {
  subscribe(event)
} catch (error) {
  // Log error
  // Attempt reconnection
  // Alert monitoring system
}

Processing errors:

onEvent((log) => {
  try {
    processEvent(log)
  } catch (error) {
    // Log failed event
    // Store for manual review
    // Continue with next event
  }
})

Real-Time Automation Examples

Payment confirmation:

Subscribe (Transfer to your address)
  → Verify amount
  → Update order status
  → Send confirmation email

NFT sale bot:

Subscribe (NFT sale event)
  → Check price
  → Evaluate opportunity
  → Execute purchase transaction

Price alert:

Subscribe (PriceUpdated event)
  → Extract new price
  → Compare to threshold
  → Send notification

tip

Use WebSocket RPC endpoints for Subscribe nodes. HTTP endpoints don't support real-time event subscriptions.

warning

Subscriptions consume resources continuously. Use specific event filters to reduce unnecessary processing and network usage.

info

Events are delivered in the order they appear on the blockchain, but there may be a few seconds delay from transaction confirmation to event delivery.

Testing Subscriptions

Test with known events:

1. Subscribe to popular contract
2. Generate test event (token transfer)
3. Verify event is received
4. Check event data is correct
5. Test filtering works as expected

Testnet testing:

• Use testnet contracts
• Generate events yourself
• Cheaper and safer than mainnet
• Faster confirmation times

Subscription Lifecycle

States:

1. Initialize - Connect to WebSocket
2. Subscribed - Listening for events
3. Event Received - Process and emit
4. Active - Continue listening (unless Once=true)
5. Closed - Flow stopped or Once triggered