Oracles

Smart contracts on Cardano frequently need access to real-world data: asset prices, exchange rates, index values, and other signals that originate outside the chain. Delivering this data reliably is the oracle problem. With a small extension to the deposit utxo datum, a Gummiworm head can serve as a publication channel for oracle data, using the existing deposit and transaction request mechanisms with no new infrastructure required.

Mechanism

The deposit utxo datum is extended to carry an optional arbitrary data payload alongside the standard refund instructions:

case class DepositUtxoDatum (
  refundInstructions: RefundInstructions,
  oraclePayload: Option[Data]  // NEW
)

An oracle operator publishes data by submitting a deposit transaction to the head with the current oracle data in the oraclePayload field. The deposit utxo sits at the head’s native script address, where any Cardano transaction can reference it as a reference input  to read the oracle data.

Reference window

The deposit utxo’s stability window is a direct consequence of the existing deposit maturity rules. Gummiworm will not absorb a deposit until it is mature — that is, until its absorption start time has passed. During the entire pre-maturity period, the deposit utxo exists on L1 and cannot be spent by anyone: the native script requires head and coil signatures, and Gummiworm will not sign a settlement that absorbs it too early.

This makes the maturity window a guaranteed stability window. Cardano transactions can reference the oracle utxo freely during this period without any risk of contention with an absorbing settlement transaction. With the suggested maturity duration of one hour, an oracle deposit provides at least one hour of stable, referenceable data after it appears on L1.

Refresh

When the head absorbs the deposit in a settlement, the oracle data is no longer available on L1. To refresh the oracle, the operator submits a transaction request that produces an L1-bound payout to the head’s native script address, containing the updated oracle data in the datum. The head remits this payout via the settlement transaction, and the resulting deposit utxo at the native script address begins a new stability window.

This refresh mechanism means that ongoing oracle operation does not require repeated external deposit transactions. After the initial deposit, the oracle operator can keep the oracle live by submitting transaction requests from their L2 balance, with the head’s settlement machinery producing each successive oracle deposit on their behalf.

Authentication

A Cardano contract referencing an oracle utxo needs assurance that the data was published by the intended oracle provider, not by an impersonator. The standard Cardano pattern for this is an authentication token: a native or Plutus-based token whose minting policy only permits the oracle provider to mint it. Contracts verify oracle data by checking that the oracle utxo contains one of these tokens.

For a Gummiworm oracle, the provider must bring authentication tokens into the head before they can appear in oracle utxos. This is done via a regular deposit carrying the tokens as part of the deposit’s value. Once inside the head, the tokens reside in the L2 main compartment and are owned by the oracle provider’s L2 account.

When the oracle provider submits a transaction request to refresh the oracle — producing an L1-bound payout to the native script address — they include at least one authentication token in that payout. The resulting deposit utxo on L1 carries both the oraclePayload and the authentication token, allowing consuming contracts to verify its provenance.

The provider must take care not to let authentication tokens escape their control. Any L2 transaction that transfers tokens to another user’s account would give that user the ability to produce oracle utxos that appear authentic. In practice, the oracle provider should hold all authentication tokens in their own L2 account and only route them through oracle utxos.

Security

Because authentication tokens reside inside the head, they are subject to the same custody model as all other head funds. A sufficient coalition of head peers and coil peers — specifically, all head peers together with a threshold of coil peers — could collectively sign an effect that moves the authentication tokens anywhere they choose, including out of the oracle provider’s control. An operator who obtained the tokens in this way could publish oracle data that appears authentic to consuming contracts.

This is not a new vulnerability specific to oracles: it is the same trust model that governs all custody in a Gummiworm head. Users trust the head and coil peers not to collude against them for all assets under management. For most purposes, this trust is well-founded — collusion would compromise the entire head’s reputation and the funds of all its users.

Oracle providers should evaluate this trust assumption in proportion to the sensitivity of their data feed. For high-stakes oracles — those whose data influences large positions or protocol parameters — the provider is effectively appointing the head and coil peers as co-operators of the oracle. A head with a large, diverse, and well-incentivized coil is a stronger trust anchor than one with few coil peers or concentrated control.

Permissionless operation

Oracle provision requires no special privileges. Any user of the head can operate an oracle using only the standard deposit and transaction request interfaces. The oracle operator interacts with the head exactly as any other user does; the head and coil peers need not take any special action beyond their normal deposit absorption and settlement.

This democratizes oracle provision: application developers can publish data for their own contracts without depending on a separate oracle network or negotiating access with head operators.

Streamlining: internal deposits

The oracle deposit produced by a settlement transaction has a structural property that external deposits do not: its existence on L1 is guaranteed. Settlement transactions are chained — each one spends the treasury utxo produced by its predecessor — so the head cannot execute a settlement that absorbs an oracle deposit unless the settlement that produced it has already been confirmed on L1. Gummiworm submits settlements in order and resubmits them as needed until they are confirmed, so by the time the head is ready to absorb the oracle deposit, it already knows the deposit exists.

This makes the maturity check unnecessary for such deposits. The maturity duration exists to give the head confidence that an external deposit has reached sufficient L1 finality before it attempts absorption; for deposits produced by the head’s own settlement transactions, that confidence is structural. The head can absorb them as soon as it decides to, without waiting.

Deposits produced by a settlement and later re-absorbed by a subsequent settlement — internal deposits — can therefore support a refresh window that is shorter than the head’s maturity duration protocol parameter allows for external deposits, giving oracle operators direct control over how frequently they refresh their data.

However, the head should enforce a minimum lifetime for internal deposits before re-absorption. Settlement and rollout transactions are paid for out of the equity compartment, which head peers replenish through fees collected inside the head. An oracle operator who sets an arbitrarily short refresh window could force the head to churn through settlement transactions rapidly, draining equity faster than fees replace it. To prevent this, the head should either enforce a minimum internal deposit lifetime as a protocol parameter, charge a fee for internal deposits commensurate with the settlement cost they generate, or both.

Streamlining further: oracle compartment

Once fragmented treasury support is available — which requires CIP-112 or CIP-118 on mainnet — oracle utxos can be managed as dedicated treasury fragments rather than as deposits.

This introduces an oracle compartment: a set of utxos at the native script address that the head maintains as first-class oracle feeds, entirely separate from the deposit compartments. Instead of the deposit lifecycle — create externally, wait for maturity, absorb, recreate via transaction request — the head updates oracle fragments in-place within a settlement: spending the old oracle fragment and producing an updated one with fresh data in a single atomic step.

The benefits over the internal deposit approach are significant:

• No mingling with deposits. Oracle utxos are recognized as a distinct compartment, not as deposits awaiting absorption. The deposit recognition logic is unaffected.
• No deposit overhead. Oracle fragments carry no refund instructions and are not subject to maturity or absorption timing rules. The stability window is simply the interval between settlements.
• In-place updates. Each settlement can atomically replace an oracle fragment with a fresh one, rather than absorbing it and recreating it in separate steps.
• Simpler fallback handling. Oracle fragments follow the treasury into the rules-based regime alongside all other treasury fragments, with no special-case handling required.