Skip to content

Latest commit

 

History

History
142 lines (90 loc) · 5.35 KB

README.md

File metadata and controls

142 lines (90 loc) · 5.35 KB
Raw

seda-protocol

SEDA Request Starter Kit

This starter kit helps you create Data Requests (also known as Oracle Programs) on the SEDA network using AssemblyScript. It showcases a basic project setup and serves as a foundation for building more complex projects.

Requirements

  • Bun: Install Bun for package management and building.
  • Alternatively, use the devcontainer for a pre-configured environment.

Getting Started

A Data Request execution involves two phases executed in a WASM VM:

  1. Execution Phase: The phase where non-deterministic operations occur. It can access public data via http_fetch or proxy_http_fetch calls. Multiple executor nodes run this phase and submit their reports to the SEDA network.

  2. Tally Phase: Aggregates reports from the execution phase using custom logic to determine a final result.

Note

This starter kit uses the same binary for both phases, but you can specify different binaries and add branching logic if needed.

Building

To build the Data Request binary, run the following (builds using the release profile by default):

bun run build

To build the binary with the debug profile, run:

bun run build:debug

Local Testing

To test the binary, this project uses @seda-protocol/vm and @seda-protocol/dev-tools. These tools help run the binary in a local WASM VM and test different scenarios.

This project uses Bun's built-in test runner, but other JavaScript/TypeScript testing frameworks should also work.

Warning

The @seda-protocol/vm package might not work properly in Node.js. Try setting the environment variable NODE_OPTIONS=--experimental-vm-modules before running the test command.

bun run test

Implement your Data Requests

Use these key components to create and define your Data Requests. The starter kit provides a base for building Oracle Programs on the SEDA network:

  • assembly/index.ts: The entry point that coordinates both the execution and tally phases of your Data Request.

  • assembly/execution-phase.ts: Manages the fetching and processing of price data from APIs. This phase involves non-deterministic operations as it can access public data via http_fetch and proxy_http_fetch calls. Multiple Executor Nodes run this phase, each producing a report that is sent to the SEDA network.

  • assembly/tally-phase.ts: Aggregates results from multiple Executor reports and calculates the final output using consensus data. This phase is deterministic, combining results from Executor Nodes to reach a consensus.

Utilities and Functions

The following are some of the key utilities and functions from the @seda-protocol/as-sdk/assembly library used in the example provided in this starter kit. These tools help you build and define your Data Requests. While these are a few important ones, the SDK offers additional utilities to explore:

  • Process: Manages inputs and outputs, allowing interaction with the WASM VM.
  • http_fetch: Fetches data from public APIs.
  • Console: Provides logging capabilities to debug and track the execution of your code.
  • JSON: Facilitates parsing and handling JSON data.
  • Bytes: Assists in working with byte arrays, useful for encoding and decoding data.

These components and utilities serve as a foundation for developing your Data Request logic. For a complete list of utilities and advanced usage, refer to the official documentation.

Interacting with SEDA Networks

You can upload Data Requests and interact with the SEDA network using the CLI tools provided by @seda-protocol/dev-tools.

Uploading a Data Request

To upload a Data Request WASM binary, run:

bun run deploy

Important

This command requires RPC_SEDA_ENDPOINT and MNEMONIC environment variables.

Alternatively, you can directly use the CLI to upload a WASM binary and list existing binaries.

List existing binaries (requires RPC_SEDA_ENDPOINT environment variable):

# With .env file
bunx seda-sdk wasm list
# With flag
bunx seda-sdk wasm list --rpc https://rpc.devnet.seda.xyz

Upload a WASM binary (requires RPC_SEDA_ENDPOINT and MNEMONIC environment variables):

bunx seda-sdk wasm upload PATH_TO_BUILD

Submitting a Data Request

@seda-protocol/dev-tools exposes functions that make it easy to create scripts that submit Data Requests to the SEDA network and await the result. The scripts directory shows an example.

Submitting a Data Request to the SEDA network, run:

bun run post-dr

This will post a transaction and wait till there is an result.

Important

Make sure you have the all environment variables set in .env file.

Example of an .env file:

# RPC for the SEDA network you want to interact with
SEDA_RPC_ENDPOINT=https://rpc.devnet.seda.xyz

# Your SEDA chain mnemonic, fill this in to upload binaries or interact with data requests directly
SEDA_MNEMONIC=

# Used for posting data request on the seda chain and configuring the consumer contract
# You can get this by running `bunx seda-sdk wasm upload PATH_TO_BUILD`
ORACLE_PROGRAM_ID=

License

Contents of this repository are open source under MIT License.