Prover Contracts as Oracle Interfaces

Provides an overview of prover contracts, describing how they mediate oracle query submission and store query results.

The Creditcoin Public Prover Contracts are the primary entry and exit points for interacting with the Creditcoin Oracle. Prover Contracts provide secure, transparent, and trust-minimizing interfaces for submitting proving queries, paying for their execution, and retrieving verified results.

What is the Public Prover Contract?

Builders and end-users interact with the Creditcoin Public Prover Contract when they want to bridge data from another blockchain into Creditcoin. Oracle users submit queries which are stored on-chain, inside the smart contract storage, and locked with an escrow payment. An off-chain prover worker is then selected to processes the query. This worker:

1. Fetches required data from the source blockchain.

2. Generates a STARK proof for the query.

3. Returns the resulting proof to the Prover Contract.

Only once a proof is verified does the Prover Contract release funds to the prover operator and make oracle results available for consumption.

This design ensures that queries are fairly priced, prover operators are compensated, and users never pay for proofs that cannot be generated or fail verification.

Ownership of The Public Prover Contract

The Public Prover Contract is deployed and owned by a prover operator. Ownership conveys responsibility for setting the financial and operational parameters of the contract. The operator configures the base fee and per-byte fee for queries, collects proceeds from successful proofs, and has the authority to mark queries as invalid when they cannot be constructed and/or verified.

For users and builders, this means that a trusted proving party operates the contract, but its rules for payment, verification, and refunds are fully enforced on-chain.

Roles of the Public Prover Contract

The Public Prover Contract performs four essential roles in the proving lifecycle:

Query Ingress

The Prover Contract serves as the main gateway into the Creditcoin oracle. When a user or a builder contract wants to request a proof for a query, it calls the function submitQuery. This function stores the query details and requires an escrowed payment equal to the estimated cost of the proof. Next, the query enters the Submitted state and is handed over to the Prover Off-Chain Worker where it awaits processing.

Storing Query Results

Once an Off-Chain Worker completes proof generation, the prover operator submits the resulting proof back to the Prover Contract. The proof is then handed over to validator nodes for verification. Once verified, proof data is stored on-chain inside prover smart contract storage. Users or builder contracts can then retrieve it through the getQueryDetails or getQueryResult functions.

Handling Payments

Payments for queries are always put into escrow at the time of submission. If the prover delivers a valid proof then the payment is released to the prover’s proceeds account. Otherwise if the query fails or expires, the original sender can reclaim their funds.

Query Management

The Prover Contract maintains a record of all submitted queries. It retains information for queries that are still pending (unprocessed), completed, invalid, or timed out. It supports refunds, rejection of invalid queries, and resubmission when appropriate.

Key User/Builder Interfaces

From a builder’s perspective, there are three main ways to interact with the Public Prover Contract.

Submitting a Query

This is done by calling the submitQuery function with query parameters and an attached payment. The prover contract enforces basic query validation and ensures that sufficient funds are provided to cover the estimated cost of query proving.

Retrieving Oracle Results

After the prover has submitted and verified a proof, the oracle results can be accessed through the function getQueryDetails which returns all query metadata and oracle result segments. Alternatively, the function getQueryResult can be called to obtain only the result data for a given query.

Managing Funds

If a query fails or times out, the original submitter can reclaim their escrow via reclaimEscrowedPayment. On the other side, the prover operator can withdraw proceeds from successfully processed queries using the function withdrawProceeds.

Public Prover Events

Every important action on the smart contract is accompanied by an event that is emitted afterwards. QuerySubmitted, QueryProofVerified, and EscrowedPaymentReclaimed allow off-chain indexers to track the lifecycle of each query. Fee updates and withdrawals are also transparent through their own events. This event system ensures that the proving process can be monitored externally in real time.