Oracle

Chopin Framework's oracle allows you to bring non-deterministic data into your app. This includes data from third-party APIs, websites, and more. It also allows you to use the current timestamp and random numbers.

How it works

When a request is being executed on the server, the sequencer is listening for "context" from the request handler. If context is reported to the sequencer, it is added onchain alongside the request in the order that it was received. In order to report context to the sequencer, the destination server reads the x-callback-url header added to the request by the reverse proxy. This header contains the URL of the server that will report the context to the sequencer.

When a non-deterministic value is generated, it should be sent to the sequencer via a POST request to the _chopin/report-context endpoint. The body of this request is a string that represents the value to be reported. When the request is replayed, the value can and should be retrieved from the sequencer instead of generating a new value.

Usage

In Next.js apps

Simply install the @chopinframework/next package and use the Oracle module to retrieve the user's address on the server side.

import { Oracle } from "@chopinframework/next";
 
// Fetch example
const result = await Oracle.fetch("https://example.com");
 
// Random number example
const randomNumber = await Oracle.random();
 
// Timestamp example
const timestamp = await Oracle.now();

In order to use the oracle module with an arbitrary non-deterministic value, you can use the Oracle.notarize function.

import { Oracle } from "@chopinframework/next";
 
const result = await Oracle.notarize(() => {
    return "Hello, world!";
});

In other frameworks

A more comprehensive guide is coming soon, but check out this implementation which requires the x-callback-url header to be set manually. When handling the request, extraxt the header and use it in this class. However, please note the library linked is still under development.

Security