Oracles

An oracle is a push-based off-chain system that observes GitHub's state and publishes an attestation of the observed information on-chain.

Users must trigger the sampling process by providing the oracle the expected value to be attested. This approach prevents oversampling of GitHub and ensures the oracle is directly compensated for its service.

Oracles serve as information sources referenced in vetting minting transactions. Oracles minting policies themselves will happily require the presence of other oracles attestations.

In particular, identity attestations are prerequisites for publisher attestations. Similarly, both publisher and identity attestations are required to obtain release attestations.

Token dependency graph

flowchart TD
    A[Identity attestation] --> B[Publisher attestation]
    A --> C[Release attestation]
    B --> C
    A --> D[Vetting declaration]
    C --> D

As always, trusting the oracle is crucial to ensure data accuracy. Since the sampled data is public, strategies like deploying multiple oracles for cross- verification can enhance trustworthiness.

Common oracle structures and operational rules

All oracles instances expose a common basic behavior.

Behavior

Each oracle:

Exposes a script address where a user place the request for an attestation.
Exposes a minting policy that will identify the oracle attestations.
Requires a predefined attestation fee for a request to execute.
It consumes the fee without attesting if the attestation fee is less than the oracle predefined one.
Samples the source of truth (GitHub) to verify requests content.
Mints an attestation token for the request content, validated by an oracle specific minting policy.
Swaps the request with its attestation token, if the content was verified and the oracle is able to satisfy the minting requirements.
Swaps the request with a declination token, if the requests cannot be satified after consuming a part of the attestation fee. (Maybe better to require a )

Request structure

Requests to oracles share some common structure:

A attestment fee value in lovelace.
A restitution address where the oracle will send the rejection token if the request is rejected.
An oracle-specific set of parameters that will be used to instantiate the verification process against the source of truth.

Attestation creation

sequenceDiagram
actor User
participant OracleAddress
actor Oracle
participant GitHub

User->>OracleAddress: Submit request for attestation
OracleAddress->>Oracle: Observe request content
alt Fee is sufficient
    Oracle->>Github: Verify request content
    alt Request content is verified
        Oracle->>OracleAddress: Swap request with attestation
    else Request content is invalid
        Oracle->>OracleAddress: Consume rejection fee
        OracleAddress->>User: Reimburse a rejection token
    end
else Fee is insufficient
    OracleAddress->>Oracle: Consume attestation fee
end

Identity oracle

The identity oracle attests the relation between GitHub usernames and their associated Ed25519 public keys.

It generates identity attestations that can later be referred from transactions to validate user signatures, lifting a declaration from a public key to a declaration from a GitHub username.

Identity swap contract permissions

The identity swap contract allows for:

The oracle swapping the request with an attestation of it.
The oracle swapping the request and an already present attestation for the same user with a new attestation for the request.
The owner of a public key burning an attestation for his public key.

Identity attestation request

To invoke the identity oracle, users must provide an Ada token containing:

request parameters
- A GitHub username.
expected values
- An Ed25519 public key.

Publisher oracle

The publisher oracle attests the relation between a GitHub user and a repository in which the user has permissions to publish releases.

It generates publisher attestations that can later be referred from transactions to validate the user's permissions in the repository to mint release attestations.

Publisher swap contract permissions

The publisher swap contract allows for:

The oracle swapping the request with an attestation of it. An identity attestation must be present for the user.
The oracle swapping the request and an already present attestation for the same user and repository with a new attestation for a different request. An identity attestation must be present for the user.
The oracle burning an attestation as requested for the user and repository when the user is no longer a publisher to the repository.
The publisher mentioned in an attestation burning the attestation. An identity attestation must be present for the publisher signature to be verified

Publisher attestation request

To invoke the publisher oracle, users must provide a token containing:

A GitHub username.
A GitHub repository name.

Release oracle

The release oracle attests the relation between a release and a hash commit in a repository.

It generates release tokens that are referenced in transactions that declare about a release.

The oracle should refuse to attest two times the same release tag for the same repository.

Release swap contract permissions

The release swap contract allows for:

The oracle swapping the request with an attestation of it only if:
- The signature in the request is valid.
- An identity attestation is present for the user.
- A publisher attestation is present for the user and repository.

Release attestation request

To invoke the release oracle, users must provide a token containing:

A GitHub username.
A GitHub repository name.
A release tag.
A commit hash.
An optional BOMs semantic IPFS link.
A signature from that user of the above.

Vettings

Vettings are self-attesting GitHub users that want to publish their work when reviewing a release of code in a GitHub repository. They do it by minting a vetting declaration.

Vetting declaration

A vetting is a declaration minted by identified GitHub users that contains:

A vetting index:
- A GitHub username.
- A GitHub repository name.
- A from release tag.
- A to release tag.
The vetting for the index:
- A vetting value (green, yellow, red).
- Free-semantic IPFS link (optional).

Vetting transaction

A vetting transaction is a minting transaction that refers to:

One identity and
Two release attestations for the same repository.

It validates the existence of an index of vetting declaration and the authenticity of the GitHub user signing the transaction.

Vetting declarations minting requirements

All transaction attestations must come from predefined oracles.
Both release attestations must reference the same repository.
The repository name in the declaration must match the one in the release attestations.
The username in the declaration must match the one in the identity attestation.
The repository and release tags in the declaration must align with those in the release attestations.
The vetting declaration must be signed by the user associated with the identity attestation.

paolino/Distributed Vetting.md