eth_subscribe
Caduceus follows the EVM specification, so API should be the same as the API for Ethereum or other compliant evm blockchains. A good place to see the full documentation is on the Alchemy eth-subscribe documentation. But continue reading to understand the most important parts.
eth_subscribe takes an array value params which accepts two items in the array. The first is the subscription name and the second is an optional data payload.
- subscription name - string - The type of event you want to subscribe to (i.e., newHeads, logs, pendingTransactions, newPendingTransactions). This method supports the following subscription types:
- newHeads - It fires a notification each time a new header is appended to the chain, including chain reorganizations
- logs - It returns logs that are included in new imported blocks and match the given filter criteria
- pendingTransactions - It returns full transactions that are sent to the network, marked as pending, and are sent from or to a certain address
- newPendingTransactions - It returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node
- data - object - (optional) The arguments such as an address, multiple addresses, and topics. Note, only logs that are created from these addresses or match the specified topics will return logs
Returns:
- result - The hex encoded subscription ID. This ID will be attached to all received events and can also be used to cancel the subscription using eth_unsubscribe
The newHeads subscription type emits an event any time a new header (block) is added to the chain, including during a chain reorganization.
setting the subscription name to logs is a great way to listen to events on a particular smart contract. It however needs the following data field to be set. It is an object with the following fields:
- address
- topics: an array of topic specifiers.
- Each topic specifier is either
- For every non null topic, a log will be emitted when activity associated with that topic occurs.
- []
- : Any topics allowed.
- [A]
- : A in first position (and anything after).
- [null, B]
- : Anything in first position and B in second position (and anything after).
- [A, B]
- : A in first position and B in second position (and anything after).
- [[A, B], [A, B]]
- : (A or B) in first position and (A or B) in second position (and anything after).
To understand more about topics we suggest you read the api documentation of Alchemy which explain it very well.
Below you can find the explanation for individual properties of the response:
- jsonrpc: The jsonrpc property specifies the version of the JSON-RPC protocol that is being used, which in this case is "2.0".
- method: The method property specifies the method that was called, which in this case is eth_subscription.
- params: The params property contains the parameters of the method call. In this case, it contains a subscription property, which specifies the subscription identifier, and a result property, which contains the result of the subscription.
- result: The result property contains information about a specific transaction on the Ethereum blockchain.
- address: The address property specifies the address from which this log originated.
- blockhash: The blockHash property specifies the hash of the block in which the transaction was included.
- blockNumber: The blockNumber property specifies the number of the block in which the transaction was included. It is encoded as a hexadecimal string.
- data: Contains one or more 32 Bytes non-indexed arguments of the log.
- logIndex: The logIndex property specifies the index or position of the log entry within the block. It is encoded as a hexadecimal string.
- topics: The topics property is an array of 0 to 4 32 bytes topic hashes of indexed log arguments.
- transactionHash: The transactionHash property specifies the hash of the transaction.
- transactionIndex: The transactionIndex property specifies the index or position of the transaction within the block. It is encoded as a hexadecimal string.
