Offchain Oracle Workers
An overview of Offchain Workers and how to use them to streamline user interactions.
Please note that all information and code snippets provided in this section are for educational purposes only and not to be directly deployed in production.
Motivation for Offchain Oracle Workers
When the Creditcoin Oracle provisions data from one chain to another, there are two transactions involved:
The user submits a transaction on the source chain. Usually this would be a source chain smart contract call emitting some event for which we want to transfer data to the execution chain.
The USC contract must be called on the execution chain. This requires generating proofs and calling the USC contract with the proofs and encoded transaction data. The USC contract verifies the proofs synchronously and executes business logic immediately.
The following diagram highlights where these two transactions take place:
The first transaction must always be submitted by the end user. However, the second transaction can be initiated by an off-chain worker on behalf of the user. Using an off-chain worker provides significant UX and technical benefits:
Seamless user experience: Without a worker, users would need to wait for attestation (up to a minute), manually generate proofs, format the proof data correctly, and then submit a second transaction. With a worker, users only need to sign the initial source chain transaction—everything else happens automatically in the background.
Eliminates technical complexity for end users: Proof generation requires calling the Proof Generation API server, waiting for attestation, handling retries, and properly formatting complex proof structures (Merkle proofs, continuity proofs, encoded transactions). Off-chain workers handle all of this complexity transparently, so users don't need to understand the underlying oracle mechanics.
Reduces transaction failures and improves reliability: Workers can implement robust retry logic, handle API failures gracefully, and ensure proper error handling. Users attempting manual proof generation are more likely to encounter failures due to timing issues (submitting before attestation completes), formatting errors, or network problems.
Enables better monitoring and observation: Workers can track processing status, log events, and provide visibility into the cross-chain data flow. This helps DApp teams debug issues and monitor their DApp's health.
Designing an Offchain Oracle Worker
Using an off-chain worker can drastically improve the UX of your Universal DApp by reducing the number of user interactions needed to trigger core business logic on the Creditcoin execution chain.
Worker Transaction Flow
The worker automates the following process:
Monitor source chain: The worker constantly monitors the source chain contract for events (e.g.,
TokensBurnedevents).Wait for attestation: When an event is detected, the worker waits for the block containing the event to be attested on Creditcoin.
Generate proofs: The worker can generate Merkle and continuity proofs via the Proof Generation API server.
Call USC contract: The worker calls the USC contract with the proofs and encoded transaction data. The USC contract verifies the proofs synchronously and executes business logic immediately.
Handle results: The worker can listen for events from the USC contract to confirm successful execution.
All of this happens automatically - the user only needs to sign the initial source chain transaction.
Worker Implementation Considerations
This has just been a starting point designed to introduce you to the use of Offchain Workers. Each DApp builder team will likely want to implement their Worker differently to fit the rest of their technology stack.
Keeping this in mind, the main goal of an Offchain Worker should always be robustness. This includes:
Retaining stored records of events in progress in the event of a Worker shutdown
Catching up with any event that might have been missed as a result of an unexpected shutdown
Avoiding submitting multiple USC calls for the same event (replay protection is handled by the USC contract, but workers should also track processed events)
Following multiple source chain nodes to listen for events in case a node experiences issues
Retrying failed proof generation or USC calls in case they fail. A call can fail for many reasons: for example, the Proof Generation API server might be experiencing downtime or connectivity issues, or the USC contract call might fail due to network issues
Below is an example of the logical flow that a more advanced oracle worker might use
Next Steps
Check out this script for an example of an offchain worker.
Last updated