Contract Events

Ralph contracts emit events to record activity on-chain. Events are immutable, indexed by the explorer, and queryable via the API without running contract code.

How events work in Ralph

Events are declared at the contract level and emitted inside functions:

Contract TokenFaucet(...) {
  event Withdraw(to: Address, amount: U256)
  event Deposit(from: Address, amount: U256)

  pub fn withdraw(to: Address, amount: U256) -> () {
    // ... logic ...
    emit Withdraw(to, amount)
  }
}

Each emit writes an event to the chain. The event fields are stored in order and typed exactly as declared.

Get events for a contract

curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}?start=0&limit=20" \
  -H "Authorization: Bearer API_KEY"

{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        { "type": "Address", "value": "1DrDyTr9..." },
        { "type": "U256", "value": "1000000000000000000" }
      ]
    }
  ],
  "nextStart": 20
}

eventIndex maps to the declaration order in the contract source. 0 is the first declared event, 1 is the second, and so on. Use it to tell Withdraw events apart from Deposit events. nextStart is the offset to pass on the next request. Always use it rather than calculating start + limit yourself the indexer may have gaps.

Get the total event count

Before paginating check how many events exist:

curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}/current-count" \
  -H "Authorization: Bearer API_KEY"

{
  "count": 384
}

To read the most recent 20 events set start to count - 20.

Get events for a specific transaction

curl "https://rpc.ralphstudio.xyz/{slug}/events/tx-id/{txId}" \
  -H "Authorization: Bearer API_KEY"

{
  "events": [
    {
      "blockHash": "00000000ab3c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [
        { "type": "Address", "value": "1DrDyTr9..." },
        { "type": "U256", "value": "1000000000000000000" }
      ]
    }
  ]
}

Useful for confirming exactly which events a transaction emitted after submission.

Get events for a block

curl "https://rpc.ralphstudio.xyz/{slug}/events/block-hash/{blockHash}" \
  -H "Authorization: Bearer API_KEY"

{
  "events": [
    {
      "txId": "503a2c...",
      "contractAddress": "27Gsc5...",
      "eventIndex": 0,
      "fields": [...]
    }
  ]
}

Use this when processing blocks sequentially fetch all events in a block in one request rather than per-transaction.

Decode event fields

Fields are returned as typed values in declaration order. Map them back to your event definition:

event Withdraw(to: Address, amount: U256)

"fields": [
  { "type": "Address", "value": "1DrDyTr9..." },
  { "type": "U256",    "value": "1000000000000000000" }
]

Field 0 → to, Field 1 → amount. There are no field names in the API response order is the only mapping.

Polling for new events

To watch for new events from a contract poll the count endpoint and fetch new events when it increases:

# Get current count
curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}/current-count" \
  -H "Authorization: Bearer API_KEY"

Store the count. On the next poll if the count has increased fetch from your last nextStart:

curl "https://rpc.ralphstudio.xyz/{slug}/events/contract/{contract-address}?start={lastStart}&limit=20" \
  -H "Authorization: Bearer API_KEY"

Poll no faster than once per 16 seconds that is the average block time per chain.

Parameters reference

Parameter	Type	Description
contract-address	string	Base58 address of the deployed contract
txId	string	Transaction hash to fetch events for
blockHash	string	Block hash to fetch events for
start	integer	Pagination offset (use `nextStart` from previous response)
limit	integer	Results per page (max 100)

Smart Contracts

How events work in Ralph

Get events for a contract

Get the total event count

Get events for a specific transaction

Get events for a block

Decode event fields

Polling for new events

Parameters reference

Next steps

Interacting with contracts

Reading contracts via API

​How events work in Ralph

​Get events for a contract

​Get the total event count

​Get events for a specific transaction

​Get events for a block

​Decode event fields

​Polling for new events

​Parameters reference

​Next steps

Interacting with contracts

Reading contracts via API

How events work in Ralph

Get events for a contract

Get the total event count

Get events for a specific transaction

Get events for a block

Decode event fields

Polling for new events

Parameters reference

Next steps