refactored documentation
- updated IDL and API docs - refactored doc pages to be centered around resource - each resource gets its own top level heading with implementation details and examples wip idl updates fixed permissions idl cleanup wip oracle arch wip wip wip wip fixed metrics command wip fixed README paths fixed broken links cleanup updated docker version cleanup dev resource tables cleanup fixed broken pages
This commit is contained in:
Conner Gallagher
parent
81f9e9d006
commit
a09a20b5b7
|
|
@ -13,6 +13,7 @@ npm install -g @switchboard-xyz/switchboardv2-cli
|
|||
|
||||
<!-- commands -->
|
||||
* [`sbv2 aggregator:add:job AGGREGATORKEY`](#sbv2-aggregatoraddjob-aggregatorkey)
|
||||
* [`sbv2 aggregator:create QUEUEKEY`](#sbv2-aggregatorcreate-queuekey)
|
||||
* [`sbv2 aggregator:create:copy AGGREGATORSOURCE`](#sbv2-aggregatorcreatecopy-aggregatorsource)
|
||||
* [`sbv2 aggregator:create:json DEFINITIONFILE`](#sbv2-aggregatorcreatejson-definitionfile)
|
||||
* [`sbv2 aggregator:lock AGGREGATORKEY`](#sbv2-aggregatorlock-aggregatorkey)
|
||||
|
|
@ -124,6 +125,57 @@ EXAMPLE
|
|||
|
||||
_See code: [src/commands/aggregator/add/job.ts](https://github.com/switchboard-xyz/switchboard-v2/blob/v0.1.21/src/commands/aggregator/add/job.ts)_
|
||||
|
||||
## `sbv2 aggregator:create QUEUEKEY`
|
||||
|
||||
create an aggregator account
|
||||
|
||||
```
|
||||
USAGE
|
||||
$ sbv2 aggregator:create QUEUEKEY
|
||||
|
||||
ARGUMENTS
|
||||
QUEUEKEY public key of the oracle queue account to create aggregator for
|
||||
|
||||
OPTIONS
|
||||
-a, --authority=authority alternate keypair that is the authority for the aggregator
|
||||
-h, --help show CLI help
|
||||
-j, --job=job filesystem path to job definition file
|
||||
|
||||
-k, --keypair=keypair keypair that will pay for onchain transactions. defaults to new account
|
||||
authority if no alternate authority provided
|
||||
|
||||
-s, --silent suppress cli prompts
|
||||
|
||||
-u, --rpcUrl=rpcUrl alternate RPC url
|
||||
|
||||
-v, --verbose log everything
|
||||
|
||||
--batchSize=batchSize number of oracles requested for each open round call
|
||||
|
||||
--force skip job confirmation
|
||||
|
||||
--forceReportPeriod=forceReportPeriod Number of seconds for which, even if the variance threshold is not passed,
|
||||
accept new responses from oracles.
|
||||
|
||||
--mainnetBeta WARNING: use mainnet-beta solana cluster
|
||||
|
||||
--minJobs=minJobs number of jobs that must respond before an oracle responds
|
||||
|
||||
--minOracles=minOracles number of oracles that must respond before a value is accepted on-chain
|
||||
|
||||
--newQueue=newQueue public key of the new oracle queue
|
||||
|
||||
--programId=programId alternative Switchboard program ID to interact with
|
||||
|
||||
--updateInterval=updateInterval set an aggregator's minimum update delay
|
||||
|
||||
--varianceThreshold=varianceThreshold percentage change between a previous accepted result and the next round before
|
||||
an oracle reports a value on-chain. Used to conserve lease cost during low
|
||||
volatility
|
||||
```
|
||||
|
||||
_See code: [src/commands/aggregator/create/index.ts](https://github.com/switchboard-xyz/switchboard-v2/blob/v0.1.21/src/commands/aggregator/create/index.ts)_
|
||||
|
||||
## `sbv2 aggregator:create:copy AGGREGATORSOURCE`
|
||||
|
||||
copy an aggregator account to a new oracle queue
|
||||
|
|
|
|||
|
|
@ -0,0 +1,106 @@
|
|||
import { flags } from "@oclif/command";
|
||||
import { PublicKey } from "@solana/web3.js";
|
||||
import {
|
||||
OracleJob,
|
||||
OracleQueueAccount,
|
||||
programWallet,
|
||||
} from "@switchboard-xyz/switchboard-v2";
|
||||
import fs from "fs";
|
||||
import path from "path";
|
||||
import BaseCommand from "../../../BaseCommand";
|
||||
import { verifyProgramHasPayer } from "../../../utils";
|
||||
|
||||
export default class AggregatorCreate extends BaseCommand {
|
||||
static description = "create an aggregator account";
|
||||
|
||||
static flags = {
|
||||
...BaseCommand.flags,
|
||||
force: flags.boolean({ description: "skip job confirmation" }),
|
||||
authority: flags.string({
|
||||
char: "a",
|
||||
description: "alternate keypair that is the authority for the aggregator",
|
||||
}),
|
||||
forceReportPeriod: flags.string({
|
||||
description:
|
||||
"Number of seconds for which, even if the variance threshold is not passed, accept new responses from oracles.",
|
||||
}),
|
||||
batchSize: flags.string({
|
||||
description: "number of oracles requested for each open round call",
|
||||
}),
|
||||
minJobs: flags.string({
|
||||
description: "number of jobs that must respond before an oracle responds",
|
||||
}),
|
||||
minOracles: flags.string({
|
||||
description:
|
||||
"number of oracles that must respond before a value is accepted on-chain",
|
||||
}),
|
||||
newQueue: flags.string({
|
||||
description: "public key of the new oracle queue",
|
||||
}),
|
||||
updateInterval: flags.string({
|
||||
description: "set an aggregator's minimum update delay",
|
||||
}),
|
||||
varianceThreshold: flags.string({
|
||||
description:
|
||||
"percentage change between a previous accepted result and the next round before an oracle reports a value on-chain. Used to conserve lease cost during low volatility",
|
||||
}),
|
||||
job: flags.string({
|
||||
char: "j",
|
||||
description: "filesystem path to job definition file",
|
||||
multiple: true,
|
||||
}),
|
||||
};
|
||||
|
||||
static args = [
|
||||
{
|
||||
name: "queueKey",
|
||||
required: true,
|
||||
parse: (pubkey: string) => new PublicKey(pubkey),
|
||||
description:
|
||||
"public key of the oracle queue account to create aggregator for",
|
||||
},
|
||||
];
|
||||
|
||||
async run() {
|
||||
verifyProgramHasPayer(this.program);
|
||||
const { args, flags } = this.parse(AggregatorCreate);
|
||||
|
||||
const payerKeypair = programWallet(this.program);
|
||||
|
||||
const queueAccount = new OracleQueueAccount({
|
||||
program: this.program,
|
||||
publicKey: args.queueKey,
|
||||
});
|
||||
const switchTokenMint = await queueAccount.loadMint();
|
||||
const payerTokenWallet = (
|
||||
await switchTokenMint.getOrCreateAssociatedAccountInfo(
|
||||
payerKeypair.publicKey
|
||||
)
|
||||
).address;
|
||||
|
||||
const jobs = flags.job.map((jobDefinition) => {
|
||||
const jobJson = JSON.parse(
|
||||
fs.readFileSync(
|
||||
jobDefinition.startsWith("/")
|
||||
? jobDefinition
|
||||
: path.join(process.cwd(), jobDefinition),
|
||||
"utf8"
|
||||
)
|
||||
);
|
||||
if (!jobJson || !("tasks" in jobJson)) {
|
||||
throw new Error("job definition missing tasks");
|
||||
}
|
||||
const data = Buffer.from(
|
||||
OracleJob.encodeDelimited(
|
||||
OracleJob.create({
|
||||
tasks: jobJson.tasks,
|
||||
})
|
||||
).finish()
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
async catch(error) {
|
||||
super.catch(error, "Failed to create aggregator account");
|
||||
}
|
||||
}
|
||||
|
|
@ -8,6 +8,7 @@ import bs58 from "bs58";
|
|||
import fs from "fs";
|
||||
import path from "path";
|
||||
import BaseCommand from "../../BaseCommand";
|
||||
import { LogProvider } from "../../types";
|
||||
|
||||
export default class MetricsAggregator extends BaseCommand {
|
||||
static description = "get metrics on switchboard aggregators";
|
||||
|
|
@ -259,7 +260,7 @@ async function buildAggregators(
|
|||
.flat();
|
||||
|
||||
// store a map of job pubkeys and their definitions
|
||||
const jobMap = await buildJobMap(program, jobPubkeys);
|
||||
const jobMap = await buildJobMap(this.logger, program, jobPubkeys);
|
||||
|
||||
const aggregators: Aggregator[] = [];
|
||||
for await (const account of aggregatorAccounts) {
|
||||
|
|
@ -286,6 +287,7 @@ async function buildAggregators(
|
|||
}
|
||||
|
||||
async function buildJobMap(
|
||||
logger: LogProvider,
|
||||
program: anchor.Program,
|
||||
pubkeys: PublicKey[],
|
||||
max = 300
|
||||
|
|
@ -312,7 +314,7 @@ async function buildJobMap(
|
|||
// console.log(`jobKey: ${publicKey}, ${JSON.stringify(job)}`);
|
||||
jobMap.set(publicKey.toString(), job);
|
||||
} catch (error) {
|
||||
this.logger.debug(`JobDecodeError: ${error}`);
|
||||
this.logger.debug(`JobDecodeError: ${pubKeyBatch[index]} - ${error}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
node_modules
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
# Switchboard Eslint Config
|
||||
|
||||
## Add to your project
|
||||
|
||||
Create `.eslintrc.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"extends": "@switchboard-xyz"
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
// Google gts eslint-config https://github.com/google/gts/blob/main/.eslintrc.json
|
||||
module.exports = {
|
||||
extends: ["eslint:recommended", "plugin:node/recommended", "prettier"],
|
||||
plugins: ["node", "prettier"],
|
||||
rules: {
|
||||
"prettier/prettier": "error",
|
||||
"block-scoped-var": "error",
|
||||
eqeqeq: "error",
|
||||
"no-var": "error",
|
||||
"prefer-const": "error",
|
||||
"eol-last": "error",
|
||||
"prefer-arrow-callback": "error",
|
||||
"no-trailing-spaces": "error",
|
||||
quotes: ["warn", "single", { avoidEscape: true }],
|
||||
"no-restricted-properties": [
|
||||
"error",
|
||||
{
|
||||
object: "describe",
|
||||
property: "only",
|
||||
},
|
||||
{
|
||||
object: "it",
|
||||
property: "only",
|
||||
},
|
||||
],
|
||||
},
|
||||
overrides: [
|
||||
{
|
||||
files: ["**/*.ts", "**/*.tsx"],
|
||||
parser: "@typescript-eslint/parser",
|
||||
extends: ["plugin:@typescript-eslint/recommended"],
|
||||
rules: {
|
||||
"@typescript-eslint/no-non-null-assertion": "off",
|
||||
"@typescript-eslint/no-use-before-define": "off",
|
||||
"@typescript-eslint/no-warning-comments": "off",
|
||||
"@typescript-eslint/no-empty-function": "off",
|
||||
"@typescript-eslint/no-var-requires": "off",
|
||||
"@typescript-eslint/explicit-function-return-type": "off",
|
||||
"@typescript-eslint/explicit-module-boundary-types": "off",
|
||||
"@typescript-eslint/ban-types": "off",
|
||||
"@typescript-eslint/camelcase": "off",
|
||||
"node/no-missing-import": "off",
|
||||
"node/no-empty-function": "off",
|
||||
"node/no-unsupported-features/es-syntax": "off",
|
||||
"node/no-missing-require": "off",
|
||||
"node/shebang": "off",
|
||||
"no-dupe-class-members": "off",
|
||||
"require-atomic-updates": "off",
|
||||
},
|
||||
parserOptions: {
|
||||
ecmaVersion: 2018,
|
||||
sourceType: "module",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
{
|
||||
"name": "@switchboard-xyz/eslint-config",
|
||||
"version": "0.1.0",
|
||||
"author": "",
|
||||
"license": "MIT",
|
||||
"description": "Switchboard eslint-config",
|
||||
"main": "index.js",
|
||||
"scripts": {
|
||||
"build": "echo \"No build script required for workspace eslint-config\" && exit 0",
|
||||
"test": "echo \"No test script required for workspace eslint-config\" && exit 0"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"eslint": "^6 || ^7.2.0",
|
||||
"prettier": ">= 1.13"
|
||||
},
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"eslint-config-airbnb": "^19.0.4",
|
||||
"eslint-config-prettier": "^8.5.0",
|
||||
"eslint-plugin-import": "^2.26.0",
|
||||
"eslint-plugin-prettier": "^4.0.0"
|
||||
}
|
||||
}
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
{
|
||||
"packages": [
|
||||
"config/*",
|
||||
"libraries/sbv2-lite",
|
||||
"libraries/ts",
|
||||
"libraries/sbv2-utils",
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ import path from "path";
|
|||
import * as sbv2 from "../";
|
||||
import { getIdlAddress, getProgramDataAddress } from "./utils";
|
||||
|
||||
const LATEST_DOCKER_VERSION = "dev-v2-4-12-22h";
|
||||
const LATEST_DOCKER_VERSION = "dev-v2-5-3-22";
|
||||
|
||||
export interface ISwitchboardTestEnvironment {
|
||||
programId: PublicKey;
|
||||
|
|
|
|||
|
|
@ -90,7 +90,7 @@ if [[ -z "${GRAFANA_HOSTNAME}" ]]; then
|
|||
exit 1
|
||||
fi
|
||||
if [[ -z "${GRAFANA_ADMIN_PASSWORD}" ]]; then
|
||||
GRAFANA_ADMIN_PASSWORD="${GRAFANA_ADMIN_PASSWORD:-SbCongraph50!}"
|
||||
GRAFANA_ADMIN_PASSWORD="${GRAFANA_ADMIN_PASSWORD:-Sbv2K8sPassword123@}"
|
||||
fi
|
||||
if [[ -z "${GRAFANA_TLS_CRT}" ]]; then
|
||||
echo "failed to set GRAFANA_TLS_CRT"
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
"description": "switchboard v2 repo containing type definitions, libraries, and examples",
|
||||
"private": true,
|
||||
"workspaces": [
|
||||
"config/*",
|
||||
"libraries/sbv2-lite",
|
||||
"libraries/ts",
|
||||
"libraries/sbv2-utils",
|
||||
|
|
@ -29,6 +30,7 @@
|
|||
"docs:build": "run-s docs:build:ts docs:build:sbv2-lite docs:build:site",
|
||||
"docs:deploy": "yarn workspace website deploy",
|
||||
"gen:idl": "rawrtools gen:anchor SW1TCH7qEPTdLsDHRgPuMQjbQxKdH2aBStViMFnt64f -o website/idl -p /idl",
|
||||
"gen:idl:devnet": "rawrtools gen:anchor --devnet 2TfB33aLaneQb5TNVwyDz3jSZXS6jdW2ARw1Dgf84XCG -o website/idl -p /idl",
|
||||
"nuke": "shx rm -rf {./programs/*,./packages/*,./website,./libraries/*,.}/{node_modules,yarn*.log,build,dist,lib,.anchor,target,Cargo.lock,.docusaurus}"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Switchboard V2 Client Examples
|
||||
|
||||
| Package | Description |
|
||||
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| [feed-parser](./packages/feed-parser) | Typescript example demonstrating how to read an aggregator account. |
|
||||
| [feed-walkthrough](./packages/feed-walkthrough) | Typescript example demonstrating how to create and manage your own oracle queue. |
|
||||
| [lease-observer](./packages/lease-observer) | Typescript example demonstrating how to send PagerDuty alerts when your aggregator lease is low on funds. |
|
||||
| Package | Description |
|
||||
| -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| [feed-parser](./feed-parser) | Typescript example demonstrating how to read an aggregator account. |
|
||||
| [feed-walkthrough](./feed-walkthrough) | Typescript example demonstrating how to create and manage your own oracle queue. |
|
||||
| [lease-observer](./lease-observer) | Typescript example demonstrating how to send PagerDuty alerts when your aggregator lease is low on funds. |
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
### Sbv2 Program Examples
|
||||
|
||||
| Package | Description |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [anchor-feed-parser](./programs/anchor-feed-parser) | Anchor example program demonstrating how to deserialize and read an onchain aggregator. |
|
||||
| [spl-feed-parser](./programs/spl-feed-parser) | Solana Program Library example demonstrating how to deserialize and read an onchain aggregator. |
|
||||
| [anchor-vrf-parser](./programs/anchor-vrf-parser) | Anchor example program demonstrating how to deserialize and read an onchain verifiable randomness function (VRF) account. |
|
||||
| Package | Description |
|
||||
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [anchor-feed-parser](./anchor-feed-parser) | Anchor example program demonstrating how to deserialize and read an onchain aggregator. |
|
||||
| [spl-feed-parser](./spl-feed-parser) | Solana Program Library example demonstrating how to deserialize and read an onchain aggregator. |
|
||||
| [anchor-vrf-parser](./anchor-vrf-parser) | Anchor example program demonstrating how to deserialize and read an onchain verifiable randomness function (VRF) account. |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
// TODO
|
||||
|
||||
// Regex: dev-v2-[0-9]{1,2}-[0-9]{1,2}-[0-9]{1,2}[A-Za-z]?
|
||||
|
|
@ -5,10 +5,11 @@ slug: .
|
|||
title: API Overview
|
||||
---
|
||||
|
||||
import LibraryTable from "/docs/developers/_library_table.mdx";
|
||||
import SDK from "/docs/developers/_sdk.mdx";
|
||||
import IDL from "/docs/developers/_idl.mdx";
|
||||
import ExampleTable from "/docs/developers/_example_table.mdx";
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import { VscGithubInverted } from "react-icons/vsc";
|
||||
|
||||
# Developer Resources
|
||||
|
||||
|
|
@ -16,77 +17,20 @@ import { VscGithubInverted } from "react-icons/vsc";
|
|||
img="/img/Switchboard_v2_Live.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
<hr />
|
||||
|
||||
## SDK
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
The Switchboard-V2 repository contains all of the libraries, examples, and
|
||||
documentation to help you get started integrating Switchboard.
|
||||
</Typography>
|
||||
|
||||
<br />
|
||||
|
||||
<Link to="https://github.com/switchboard-xyz/switchboard-v2">
|
||||
|
||||
<Typography variant="h5" sx={{ textAlign: "center" }}>
|
||||
<VscGithubInverted />
|
||||
@switchboard-xyz/switchboard-v2
|
||||
<VscGithubInverted />
|
||||
</Typography>
|
||||
|
||||
</Link>
|
||||
|
||||
<hr />
|
||||
<SDK />
|
||||
|
||||
## Anchor IDL
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
Switchboard's Anchor IDL contains a detailed description of the program
|
||||
interfaces and schemas.
|
||||
</Typography>
|
||||
<IDL />
|
||||
|
||||
<Link to="/idl">
|
||||
## Libraries
|
||||
|
||||
<Typography variant="h5" sx={{ textAlign: "center" }}>
|
||||
⚓ Anchor IDL ⚓
|
||||
</Typography>
|
||||
<LibraryTable />
|
||||
|
||||
</Link>
|
||||
## Examples
|
||||
|
||||
<hr />
|
||||
|
||||
## APIs
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
Switchboard's APIs provide a client interface to interact with Switchboard V2
|
||||
on-chain.
|
||||
</Typography>
|
||||
|
||||
| Resource | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
|
||||
| <a className="nowrap" href="api/tasks"><VscJson className="devicons" fontSize="large" /> switchboard-tasks</a> | Protobuf definitions for the various supported task definitions to build job definitions from. |
|
||||
| <a className="nowrap" href="api/ts/"><SiTypescript className="devicons" fontSize="large" /> switchboardv2-api</a> | A typescript library of utility functions to interact with the Switchboardv2 program. |
|
||||
| <a className="nowrap" href="api/py"><SiPython className="devicons" fontSize="large" /> switchboardpy</a> | A python library of utility functions to interact with the Switchboardv2 program. |
|
||||
| <a className="nowrap" href="api/cli"><SiPowershell className="devicons" fontSize="large" /> switchboardv2-cli</a> | A Command Line Interface (CLI) to interact with the Switchboardv2 program. |
|
||||
| <a className="nowrap" href="https://docs.rs/switchboard-v2"><SiRust className="devicons" /> switchboard-v2 <GoLinkExternal className="devicons" /></a> | A rust library of utility functions to interact with the Switchboardv2 program on-chain. |
|
||||
|
||||
<hr />
|
||||
|
||||
<!--
|
||||
import { FiType } from "react-icons/fi";
|
||||
import { SiTypescript } from "react-icons/si";
|
||||
import { SiJavascript } from "react-icons/si";
|
||||
import { SiPython } from "react-icons/si";
|
||||
import { SiRust } from "react-icons/si";
|
||||
import { SiPowershell } from "react-icons/si";
|
||||
import { VscJson } from "react-icons/vsc";
|
||||
import { GoLinkExternal } from "react-icons/go";
|
||||
import { SerumIcon } from "/src/components/icons/SerumIcon";
|
||||
|
||||
| Resource | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
|
||||
| <a className="nowrap" href="api/tasks"><VscJson className="devicons" fontSize="large" /> switchboard-tasks</a> | Protobuf definitions for the various supported task definitions to build job definitions from. |
|
||||
| <a className="nowrap" href="api/ts/"><SiTypescript className="devicons" fontSize="large" /> switchboardv2-api</a> | A typescript library of utility functions to interact with the Switchboardv2 program. |
|
||||
| <a className="nowrap" href="api/py"><SiPython className="devicons" fontSize="large" /> switchboardpy</a> | A python library of utility functions to interact with the Switchboardv2 program. |
|
||||
| <a className="nowrap" href="api/cli"><SiPowershell className="devicons" fontSize="large" /> switchboardv2-cli</a> | A Command Line Interface (CLI) to interact with the Switchboardv2 program. |
|
||||
| <a className="nowrap" href="https://docs.rs/switchboard-v2"><SiRust className="devicons" /> switchboard-v2 <GoLinkExternal className="devicons" /></a> | A rust library of utility functions to interact with the Switchboardv2 program on-chain. | -->
|
||||
<ExampleTable />
|
||||
|
|
|
|||
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
id: python-overview
|
||||
title: Python
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
## Examples
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
---
|
||||
id: rust-overview
|
||||
title: Rust
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
## Examples
|
||||
|
|
@ -24,7 +24,7 @@ Switchboard tasks can be divided into the following categories:
|
|||
|
||||
:::tip
|
||||
|
||||
Check out the [**Job Directory**](/job-directory) for examples!
|
||||
Check out the [**Job Directory**](/feed/directory) for examples!
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
id: typescript-overview
|
||||
title: Typescript
|
||||
---
|
||||
|
||||
import { styled, ThemeProvider } from "@mui/system";
|
||||
import { Box, CssBaseline } from "@mui/material";
|
||||
import { FeatureCard } from "/src/components/FeatureCard";
|
||||
import { CardSet } from "/src/components/CardSet";
|
||||
import { theme } from "/src/components/theme";
|
||||
import { Grid, Typography } from "@mui/material";
|
||||
import { useColorMode } from "@docusaurus/theme-common";
|
||||
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
|
||||
import Layout from "@theme/Layout";
|
||||
const LibrariesList = [
|
||||
{
|
||||
title: "switchboard-v2",
|
||||
image: "/img/icons/info.png",
|
||||
description: "Switchboard V2 Typescript client",
|
||||
linkTo: "https://docs.switchboard.xyz/api/ts",
|
||||
},
|
||||
{
|
||||
title: "sbv2-lite",
|
||||
image: "/img/icons/info.png",
|
||||
description: "Switchboard V2 Typescript client",
|
||||
linkTo: "https://docs.switchboard.xyz/api/ts",
|
||||
},
|
||||
];
|
||||
|
||||
## Libraries
|
||||
|
||||
<CardSet items={LibrariesList} />
|
||||
|
||||
## Examples
|
||||
|
|
@ -91,6 +91,6 @@ An aggregator uses a [Lease Contract](/architecture/feeds/lease) to reward oracl
|
|||
- <Link className="link__nocolor" to="/publisher">
|
||||
ℹ️ Publisher
|
||||
</Link>
|
||||
- <Link className="link__nocolor" to="/job-directory">
|
||||
- <Link className="link__nocolor" to="/feed/directory">
|
||||
ℹ️ Job Directory
|
||||
</Link>
|
||||
|
|
@ -72,6 +72,6 @@ The [ValueTask](/api/tasks#ValueTask) is used to return a static value. This is
|
|||
- <Link className="link__nocolor" to="/api/tasks">
|
||||
ℹ️ Task Definitions
|
||||
</Link>
|
||||
- <Link className="link__nocolor" to="/job-directory">
|
||||
- <Link className="link__nocolor" to="/feed/directory">
|
||||
ℹ️ Job Directory
|
||||
</Link>
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
sidebar_position: 80
|
||||
slug: /dao
|
||||
title: Switchboard DAO
|
||||
---
|
||||
|
||||
# Switchboard DAO
|
||||
|
||||
The Switchboard DAO will operate a set of oracle queues and provide the mechanisms for stakeholders to contribute, join, and vote on new proposals. More information coming soon.
|
||||
|
|
@ -8,6 +8,15 @@ import MarkdownImage from "/src/components/MarkdownImage";
|
|||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import { VscGithubInverted } from "react-icons/vsc";
|
||||
import { FiType } from "react-icons/fi";
|
||||
import { SiTypescript } from "react-icons/si";
|
||||
import { SiJavascript } from "react-icons/si";
|
||||
import { SiPython } from "react-icons/si";
|
||||
import { SiRust } from "react-icons/si";
|
||||
import { SiPowershell } from "react-icons/si";
|
||||
import { VscJson } from "react-icons/vsc";
|
||||
import { GoLinkExternal } from "react-icons/go";
|
||||
import { SerumIcon } from "/src/components/icons/SerumIcon";
|
||||
|
||||
# Developer Resources
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
sidebar_position: 20
|
||||
slug: /job-directory
|
||||
slug: /feed/directory
|
||||
---
|
||||
|
||||
# Job Directory
|
||||
|
|
@ -68,7 +68,7 @@ import Link from "@docusaurus/Link";
|
|||
<Link to="/api/tasks">/api/tasks</Link>
|
||||
</li>
|
||||
<li>
|
||||
<Link to="/job-directory">Job Directory</Link>
|
||||
<Link to="/feed/directory">Job Directory</Link>
|
||||
</li>
|
||||
<li>
|
||||
<Link to="https://switchboard.xyz/explorer">
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"label": "Oracles",
|
||||
"position": 20
|
||||
}
|
||||
|
|
@ -24,7 +24,7 @@ import TabItem from "@theme/TabItem";
|
|||
version: "3.3"
|
||||
services:
|
||||
switchboard:
|
||||
image: "switchboardlabs/node:dev-v2"
|
||||
image: "switchboardlabs/node:dev-v2-5-3-22
|
||||
network_mode: host
|
||||
restart: always
|
||||
environment:
|
||||
|
|
@ -47,7 +47,7 @@ secrets:
|
|||
version: "3.3"
|
||||
services:
|
||||
switchboard:
|
||||
image: "switchboardlabs/node:dev-v2"
|
||||
image: "switchboardlabs/node:dev-v2-5-3-22
|
||||
network_mode: host
|
||||
restart: always
|
||||
environment:
|
||||
|
|
@ -10,7 +10,7 @@ import CodeBlock from "@theme/CodeBlock";
|
|||
|
||||
## Create Oracle
|
||||
|
||||
With the [Switchboard V2 CLI](../developers/cli/) installed, run the following command, where
|
||||
With the [Switchboard V2 CLI](../../api/cli/) installed, run the following command, where
|
||||
|
||||
- `QUEUEKEY` is the oracle queue you will be joining. See [Program](../program) for a list of available queues.
|
||||
- `PAYERKEYPAIR` is the filesystem path to your wallet that will pay for the new account. Keypair will default to the oracle authority if authority flag is not provided.
|
||||
|
|
@ -60,7 +60,7 @@ Create a docker-compose file, replacing `ORACLE_KEY`, `RPC_URL`, and `PAYER_KEYP
|
|||
version: "3.3"
|
||||
services:
|
||||
oracle:
|
||||
image: "switchboardlabs/node:dev-v2-3-7-22"
|
||||
image: "switchboardlabs/node:dev-v2-5-3-22"
|
||||
network_mode: host
|
||||
restart: always
|
||||
secrets:
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
sidebar_position: 5
|
||||
slug: /program
|
||||
title: Program
|
||||
---
|
||||
|
||||
import PublicKeyButton from "/src/components/PublicKeyButton";
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import ProgramStateAccountData from "/idl/accounts/SbState.md";
|
||||
import Link from "@docusaurus/Link";
|
||||
|
||||
## Program State
|
||||
|
||||
<Grid container spacing={3} justifyContent="space-around">
|
||||
<Grid item md={6}>
|
||||
<br />
|
||||
<Typography>
|
||||
The program state account governs the Switchboard V2 program and controls the
|
||||
token mint used throughout for oracle rewards, aggregator leases, and
|
||||
other incentives.
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>
|
||||
The Switchboard V2 program can support many oracle queue's, each acting as
|
||||
independent networks with their own oracles, configuration, and security
|
||||
model.
|
||||
</Typography>
|
||||
<br />
|
||||
|
||||
### 📦SbState
|
||||
|
||||
<ProgramStateAccountData />
|
||||
|
||||
</Grid>
|
||||
<Grid item md={5}>
|
||||
<MarkdownImage img="/img/L0_Architecture.png" />
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
## Mainnet-Beta
|
||||
|
||||
Below is a list of public keys used in the Switchboard V2 mainnet deployment.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Account</th>
|
||||
<th>Public Key</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Program ID</b>
|
||||
</td>
|
||||
<td>
|
||||
<PublicKeyButton publicKey="SW1TCH7qEPTdLsDHRgPuMQjbQxKdH2aBStViMFnt64f" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissionless Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="5JYwqvKkqp35w8Nq3ba4z1WYUeJQ1rB36V8XvaGp6zn1" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="BKtF8yyQsj3Ft6jb2nkfpEKzARZVdGgdEPs6mFmZNmbA" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissioned Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="3HBb2DQqDfuMdzWxNk1Eo9RTMkFYmuEAd32RiLKn9pAn" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GdNVLWzcE6h9SPuSbmu69YzxAj8enim9t6mjzuqTXgLd" />
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Devnet
|
||||
|
||||
Below is a list of public keys used in the Switchboard V2 devnet deployment.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Account</th>
|
||||
<th>Public Key</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Program ID</b>
|
||||
</td>
|
||||
<td>
|
||||
<PublicKeyButton publicKey="2TfB33aLaneQb5TNVwyDz3jSZXS6jdW2ARw1Dgf84XCG" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissionless Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="F8ce7MsckeZAbAGmxjJNetxYXQa9mKr9nnrC3qKubyYy" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GN9jjCy2THzZxhYqZETmPM3my8vg4R5JyNkgULddUMa5" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissioned Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GhYg3R1V6DmJbwuc57qZeoYG6gUuvCotUF1zU3WCj98U" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GdNVLWzcE6h9SPuSbmu69YzxAj8enim9t6mjzuqTXgLd" />
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Buffer Relayers",
|
||||
"position": 50,
|
||||
"collapsible": true
|
||||
}
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
# Buffer Relayer Architecture
|
||||
|
||||
TODO
|
||||
|
||||
<!--
|
||||
|
||||
- A single oracle can publish a raw buffer on-chain
|
||||
- Currently limited to 500 bytes, can be expanded to 10Mb
|
||||
- No consensus mechanism, aka not very secure
|
||||
|
||||
## Configuration
|
||||
|
||||
- Job Account
|
||||
- Escrow
|
||||
|
||||
## Update Lifecycle
|
||||
|
||||
- `bufferRelayerOpenRound`
|
||||
- `bufferRelayerSaveResult`
|
||||
|
||||
## Cost
|
||||
|
||||
## More Information
|
||||
-->
|
||||
|
|
@ -1,9 +1,116 @@
|
|||
---
|
||||
sidebar_position: 80
|
||||
slug: /dao
|
||||
title: Switchboard DAO
|
||||
---
|
||||
|
||||
# Switchboard DAO
|
||||
|
||||
The Switchboard DAO will operate a set of oracle queues and provide the mechanisms for stakeholders to contribute, join, and vote on new proposals. More information coming soon.
|
||||
The Switchboard DAO operates a set of oracle queues and provide the mechanisms for stakeholders to contribute, join, and vote on new proposals. More information coming soon.
|
||||
|
||||
import PublicKeyButton from "/src/components/PublicKeyButton";
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import ProgramStateAccountData from "/idl/accounts/SbState.md";
|
||||
import Link from "@docusaurus/Link";
|
||||
|
||||
## Mainnet-Beta
|
||||
|
||||
Below is a list of public keys used in the Switchboard V2 mainnet deployment.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Account</th>
|
||||
<th>Public Key</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Program ID</b>
|
||||
</td>
|
||||
<td>
|
||||
<PublicKeyButton publicKey="SW1TCH7qEPTdLsDHRgPuMQjbQxKdH2aBStViMFnt64f" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissionless Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="5JYwqvKkqp35w8Nq3ba4z1WYUeJQ1rB36V8XvaGp6zn1" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="BKtF8yyQsj3Ft6jb2nkfpEKzARZVdGgdEPs6mFmZNmbA" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissioned Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="3HBb2DQqDfuMdzWxNk1Eo9RTMkFYmuEAd32RiLKn9pAn" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GdNVLWzcE6h9SPuSbmu69YzxAj8enim9t6mjzuqTXgLd" />
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Devnet
|
||||
|
||||
Below is a list of public keys used in the Switchboard V2 devnet deployment.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Account</th>
|
||||
<th>Public Key</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Program ID</b>
|
||||
</td>
|
||||
<td>
|
||||
<PublicKeyButton publicKey="2TfB33aLaneQb5TNVwyDz3jSZXS6jdW2ARw1Dgf84XCG" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissionless Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="F8ce7MsckeZAbAGmxjJNetxYXQa9mKr9nnrC3qKubyYy" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GN9jjCy2THzZxhYqZETmPM3my8vg4R5JyNkgULddUMa5" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissioned Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GhYg3R1V6DmJbwuc57qZeoYG6gUuvCotUF1zU3WCj98U" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GdNVLWzcE6h9SPuSbmu69YzxAj8enim9t6mjzuqTXgLd" />
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Developers",
|
||||
"position": 60,
|
||||
"collapsible": true
|
||||
}
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import { VscGithubInverted } from "react-icons/vsc";
|
||||
import { FiType } from "react-icons/fi";
|
||||
import { SiTypescript } from "react-icons/si";
|
||||
import { SiJavascript } from "react-icons/si";
|
||||
import { SiPython } from "react-icons/si";
|
||||
import { SiRust } from "react-icons/si";
|
||||
import { SiPowershell } from "react-icons/si";
|
||||
import { VscJson } from "react-icons/vsc";
|
||||
import { GoLinkExternal } from "react-icons/go";
|
||||
import { SerumIcon } from "/src/components/icons/SerumIcon";
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
Example repos showing how to integrate Switchboard V2 into your on-chain
|
||||
programs or off-chain applications
|
||||
</Typography>
|
||||
|
||||
| Example | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <Link className="nowrap" to="https://github.com/switchboard-xyz/switchboard-v2/blob/main/programs/programs/anchor-feed-parser"><SiRust className="devicons" /> <SiTypescript className="devicons" fontSize="large" /> anchor-feed-parser <GoLinkExternal className="devicons" /></Link> | Anchor example program demonstrating how to deserialize and read an onchain aggregator. |
|
||||
| <Link className="nowrap" to="https://github.com/switchboard-xyz/switchboard-v2/blob/main/programs/programs/anchor-vrf-parser"><SiRust className="devicons" /> <SiTypescript className="devicons" fontSize="large" /> anchor-vrf-parser <GoLinkExternal className="devicons" /></Link> | Anchor example program demonstrating how to deserialize and read an onchain verifiable randomness function (VRF) account. |
|
||||
| <Link className="nowrap" to="https://github.com/switchboard-xyz/switchboard-v2/blob/main/packages/packages/feed-parser"> <SiTypescript className="devicons" fontSize="large" /> feed-parser <GoLinkExternal className="devicons" /></Link> | Typescript example demonstrating how to read an aggregator account. |
|
||||
| <Link className="nowrap" to="https://github.com/switchboard-xyz/switchboard-v2/blob/main/packages/packages/feed-walkthrough"><SiTypescript className="devicons" fontSize="large" /> feed-walkthrough <GoLinkExternal className="devicons" /></Link> | Typescript example demonstrating how to create and manage your own oracle queue. |
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
Switchboard's Anchor IDL contains a detailed description of the program
|
||||
interfaces and schemas
|
||||
</Typography>
|
||||
|
||||
<Link to="/idl">
|
||||
|
||||
<Typography variant="h5" sx={{ textAlign: "center" }}>
|
||||
⚓ Anchor IDL ⚓
|
||||
</Typography>
|
||||
|
||||
</Link>
|
||||
|
||||
<hr />
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import { VscGithubInverted } from "react-icons/vsc";
|
||||
import { FiType } from "react-icons/fi";
|
||||
import { SiTypescript } from "react-icons/si";
|
||||
import { SiJavascript } from "react-icons/si";
|
||||
import { SiPython } from "react-icons/si";
|
||||
import { SiRust } from "react-icons/si";
|
||||
import { SiPowershell } from "react-icons/si";
|
||||
import { VscJson } from "react-icons/vsc";
|
||||
import { GoLinkExternal } from "react-icons/go";
|
||||
import { SerumIcon } from "/src/components/icons/SerumIcon";
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
Switchboard's libraries provide a client interface to interact with
|
||||
Switchboard V2 on-chain
|
||||
</Typography>
|
||||
|
||||
| Library | Description |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| <Link className="nowrap" to="/api/tasks"><VscJson className="devicons" fontSize="large" /> switchboard-tasks</Link> | Protobuf definitions for the various supported task definitions to build job definitions from. |
|
||||
| <Link className="nowrap" to="/api/cli"><SiPowershell className="devicons" fontSize="large" /> switchboardv2-cli</Link> | A Command Line Interface (CLI) to interact with the Switchboardv2 program. |
|
||||
| <Link className="nowrap" to="/api/ts" target="_blank"><SiTypescript className="devicons" fontSize="large" /> switchboardv2-api <GoLinkExternal className="devicons" /></Link> | A typescript library of utility functions to interact with the Switchboardv2 program. |
|
||||
| <Link className="nowrap" to="/api/ts-lite" target="_blank"><SiTypescript className="devicons" fontSize="large" /> sbv2-lite <GoLinkExternal className="devicons" /></Link> | A typescript "Lite" client to deserialize aggregator accounts. |
|
||||
| <Link className="nowrap" to="/api/py" target="_blank"><SiPython className="devicons" fontSize="large" /> switchboardpy <GoLinkExternal className="devicons" /></Link> | A python library of utility functions to interact with the Switchboardv2 program. |
|
||||
| <Link className="nowrap" to="https://docs.rs/switchboard-v2"><SiRust className="devicons" /> switchboard-v2 <GoLinkExternal className="devicons" /></Link> | A rust library of utility functions to interact with the Switchboardv2 program on-chain. |
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import { VscGithubInverted } from "react-icons/vsc";
|
||||
|
||||
<Typography variant="body2" sx={{ fontSize: "1.5em" }}>
|
||||
The Switchboard-V2 repository contains all of the libraries, examples, and
|
||||
documentation to help you get started integrating Switchboard
|
||||
</Typography>
|
||||
|
||||
<br />
|
||||
|
||||
<Link to="https://github.com/switchboard-xyz/switchboard-v2">
|
||||
|
||||
<Typography variant="h5" sx={{ textAlign: "center" }}>
|
||||
<VscGithubInverted />
|
||||
@switchboard-xyz/switchboard-v2
|
||||
<VscGithubInverted />
|
||||
</Typography>
|
||||
|
||||
</Link>
|
||||
|
||||
<hr />
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
sidebar_position: 50
|
||||
title: Buffer Relayers
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Read a Buffer Relayer
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rust" label="Rust" default>
|
||||
|
||||
```rust
|
||||
// Rust code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Typescript" label="Typescript">
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Create a Buffer Relayer
|
||||
|
||||
- `bufferRelayerInit`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Request a Buffer Relayer Update
|
||||
|
||||
- `bufferRelayerOpenRound`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,192 @@
|
|||
---
|
||||
sidebar_position: 30
|
||||
title: Data Feeds
|
||||
---
|
||||
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
<Typography variant="h4">
|
||||
<Link to="https://github.com/switchboard-xyz/switchboard-v2/tree/main/programs/anchor-feed-parser">
|
||||
# anchor-feed-parser
|
||||
</Link>
|
||||
</Typography>
|
||||
|
||||
## Reading a Data Feed
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rust" label="Rust" default>
|
||||
|
||||
```rust
|
||||
// Rust code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Typescript" label="Typescript">
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Creating a Data Feed
|
||||
|
||||
- `aggregatorInit`
|
||||
- `leaseInit`
|
||||
- `jobInit`
|
||||
- `permissionInit`
|
||||
- `aggregatorAddJob`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Funding a Data Feed
|
||||
|
||||
- `leeaseExtend`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Requesting a Feed Update
|
||||
|
||||
- `openRound`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Push to Crank
|
||||
|
||||
- `crankPush`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Add History Buffer
|
||||
|
||||
- `aggregatorSetHistoryBuffer`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,149 @@
|
|||
---
|
||||
sidebar_position: 5
|
||||
title: Localnet Integration
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
You may wish to run a localnet version of Switchboard to watch how your program reacts to data feed updates. The following will walk through how to create your own Oracle Queue and Oracle and output some helper scripts to quickly load the environment in your tests.
|
||||
|
||||
## Setup Switchboard Test Environment
|
||||
|
||||
The following will create an Oracle Queue and Oracle with the provided keypair as the authority
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="CLI" label="CLI" default>
|
||||
|
||||
```shell
|
||||
sbv2 localnet:env \
|
||||
--keypair "../payer-keypair.json" \
|
||||
--outputDir ".switchboard"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Typescript" label="Typescript">
|
||||
|
||||
```typescript
|
||||
import { SwitchboardTestEnvironment } from "@switchboard-xyz/sbv2-utils";
|
||||
|
||||
const testEnvironment = await SwitchboardTestEnvironment.create(
|
||||
"../payer-keypair.json"
|
||||
);
|
||||
testEnvironment.writeAll(".switchboard");
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
In the specified `outputDir`, you will find:
|
||||
|
||||
- **start-local-validator.sh**: Bash script which starts a local Solana validator with the Switchboard program, IDL, and our devnet environment pre-loaded
|
||||
- **start-oracle.sh**: Bash script which starts a Switchboard oracle and start heartbeating on the localnet queue
|
||||
- **docker-compose.switchboard.yml**: docker file with the Switchboard oracle environment
|
||||
- **switchboard.env**: Env file with your Switchboard account public keys
|
||||
- **switchboard.json**: JSON file with your Switchboard account public keys
|
||||
|
||||
## Switchboard Test Context
|
||||
|
||||
In your tests, you will need to load the `switchboard.env` file to build the SwitchboardTestContext.
|
||||
|
||||
### Starting Test
|
||||
|
||||
Before you run your test you will need a localnet Solana validator running with the Switchboard-V2 program loaded and your Switchboard oracle running and heartbeating.
|
||||
|
||||
**_In Shell #1_**
|
||||
|
||||
```bash
|
||||
./.switchboard/start-local-validator.sh
|
||||
```
|
||||
|
||||
**_In Shell #2_**
|
||||
|
||||
```bash
|
||||
./.switchboard/start-oracle.sh
|
||||
```
|
||||
|
||||
**_In Shell #3_**
|
||||
|
||||
```bash
|
||||
anchor test --skip-local-validator
|
||||
```
|
||||
|
||||
### loadFromEnv
|
||||
|
||||
`SwitchboardTestContext.loadFromEnv` will look for `switchboard.env` or a `.switchboard` directory in the current directory or three levels up before throwing an error.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```typescript
|
||||
import * as anchor from "@project-serum/anchor";
|
||||
import { SwitchboardTestContext } from "@switchboard-xyz/sbv2-utils";
|
||||
import chai from "chai";
|
||||
import "mocha";
|
||||
|
||||
describe("switchboard integration test", async () => {
|
||||
const provider = anchor.AnchorProvider.env();
|
||||
anchor.setProvider(provider);
|
||||
|
||||
let switchboard: SwitchboardTestContext;
|
||||
|
||||
before(async () => {
|
||||
// Optional, attempt to load the switchboard devnet PID
|
||||
// If successful, then we can assume we're on devnet and can use the public permissionless queue
|
||||
try {
|
||||
switchboard = await SwitchboardTestContext.loadDevnetQueue(provider);
|
||||
console.log("devnet detected");
|
||||
return;
|
||||
} catch (error: any) {
|
||||
console.log("Error: SBV2 Devnet - ", error.message);
|
||||
}
|
||||
|
||||
// Attempt to load switchboard.env or .switchboard directory
|
||||
// Will look 3 levels up before failing
|
||||
try {
|
||||
switchboard = await SwitchboardTestContext.loadFromEnv(provider);
|
||||
console.log("localnet detected");
|
||||
return;
|
||||
} catch (error: any) {
|
||||
console.log("Error: SBV2 Localnet - ", error.message);
|
||||
}
|
||||
|
||||
// If fails, throw error
|
||||
throw new Error(
|
||||
"Failed to load the SwitchboardTestContext from devnet or from a switchboard.env file"
|
||||
);
|
||||
});
|
||||
|
||||
it("Your test here", async () => {});
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### createStaticFeed
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```typescript
|
||||
import * as anchor from "@project-serum/anchor";
|
||||
import { SwitchboardTestContext } from "@switchboard-xyz/sbv2-utils";
|
||||
import { AggregatorAccount } from "@switchboard-xyz/switchboard-v2";
|
||||
|
||||
// load the Switchboard env to dictate which queue to create feed for
|
||||
const switchboard = await SwitchboardTestContext.loadFromEnv(
|
||||
anchor.AnchorProvider.env()
|
||||
);
|
||||
|
||||
// create a static feed that will always resolve to 100
|
||||
// then call openRound and wait for the oracle to process the update
|
||||
const aggregatorAccount: AggregatorAccount = await switchboard.createStaticFeed(
|
||||
100
|
||||
);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
sidebar_position: 20
|
||||
title: Oracles
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Create
|
||||
|
||||
- `oracleInit`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Oracle Deposit
|
||||
|
||||
- `tokenTransfer`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Oracle Heartbeat
|
||||
|
||||
- `oracleHeartbeat`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Save Result
|
||||
|
||||
- `aggregatorSaveResult`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Oracle Withdraw
|
||||
|
||||
- `oracleWithdraw`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
title: Oracle Queue
|
||||
---
|
||||
|
||||
<!--
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
|
||||
<Typography variant="h4">
|
||||
<Link to="https://github.com/switchboard-xyz/switchboard-v2/tree/main/programs/anchor-vrf-parser">
|
||||
# anchor-vrf-parser
|
||||
</Link>
|
||||
</Typography>
|
||||
-->
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
## Create an Oracle Queue
|
||||
|
||||
- `oracleQueueInit`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Assign Queue Permissions
|
||||
|
||||
- `permissionSet`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Create a Crank
|
||||
|
||||
- `crankInit`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,106 @@
|
|||
---
|
||||
sidebar_position: 40
|
||||
title: Randomness
|
||||
---
|
||||
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
<Typography variant="h4">
|
||||
<Link to="https://github.com/switchboard-xyz/switchboard-v2/tree/main/programs/anchor-vrf-parser">
|
||||
# anchor-vrf-parser
|
||||
</Link>
|
||||
</Typography>
|
||||
|
||||
## Reading a VRF Account
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rust" label="Rust" default>
|
||||
|
||||
```rust
|
||||
// Rust code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Typescript" label="Typescript">
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Define Callback
|
||||
|
||||
## Creating a VRF Account
|
||||
|
||||
- `vrfInit`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Request Randomness
|
||||
|
||||
- `vrfRequestRandomness`
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Typescript" label="Typescript" default>
|
||||
|
||||
```ts
|
||||
// Typescript code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Python" label="Python">
|
||||
|
||||
```python
|
||||
# Python code
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
```bash
|
||||
# CLI command
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Developer Resources
|
||||
---
|
||||
|
||||
import LibraryTable from "./_library_table.mdx";
|
||||
import SDK from "./_sdk.mdx";
|
||||
import IDL from "./_idl.mdx";
|
||||
import ExampleTable from "./_example_table.mdx";
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
|
||||
# Developer Resources
|
||||
|
||||
<MarkdownImage
|
||||
img="/img/Switchboard_v2_Live.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
<hr />
|
||||
|
||||
## SDK
|
||||
|
||||
<SDK />
|
||||
|
||||
## Anchor IDL
|
||||
|
||||
<IDL />
|
||||
|
||||
## Getting Help
|
||||
|
||||
- [Discord](http://discord.switchboard.xyz/)
|
||||
- [Telegram](https://t.me/switchboardxyz)
|
||||
- [Twitter @switchboard-xyz](https://twitter.com/switchboardxyz)
|
||||
|
||||
<hr />
|
||||
|
||||
## Libraries
|
||||
|
||||
<LibraryTable />
|
||||
|
||||
## Examples
|
||||
|
||||
<ExampleTable />
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Data Feeds",
|
||||
"position": 30,
|
||||
"collapsible": true
|
||||
}
|
||||
|
|
@ -0,0 +1,202 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
# Data Feed Architecture
|
||||
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
|
||||
An aggregator or data feed is what on-chain developers use when building smart contracts. A data feed is a collection of jobs that get aggregated to produce a single, deterministic result. Typically the first task in a job will fetch external data with subsequent tasks responsible for parsing the response and transforming the value into a single data type, like an integer or decimal.
|
||||
|
||||
When an oracle is assigned to process a data feed update, the oracle executes the defined jobs, computes the weighted median of the job responses, and publishes the result on-chain. If sufficient oracles respond, the on-chain program computes the final result as the median of the assigned oracle responses.
|
||||
|
||||
Data feeds published on Solana are public and there is no mechanism to prevent other users from reading and consuming the data. Because of this, Switchboard, by default, treats feeds as public utilities allowing anyone to contribute. This is by design as data feeds should be community controlled. If a program is relying on an oracle and the lease expires, any user is allowed to extend the lease, push on a crank, and keep the feed updating, but only if the feed config allows it. Switchboard envisions data feeds being community governed by the protocols supporting them. As a feed grows in popularity and is used across protocols, the feed maintenance cost can be spread across the protocols to reduce the economic burden on a single entity.
|
||||
|
||||
## Configuration
|
||||
|
||||
<Grid container spacing={3}>
|
||||
<Grid item md={4} sm={12} order={{ xs: 2, sm: 1 }}>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Aggregator: </b>Contains the data feed configuration, dictating how
|
||||
data feed updates get requested, updated, and resolved on-chain.
|
||||
</li>
|
||||
<li>
|
||||
<b>Job Account: </b>Stores the blueprints for how data is fetched
|
||||
off-chain for a particular data source.
|
||||
</li>
|
||||
<li>
|
||||
<b>Permission Account: </b>Permits a data feed to join an oracle queue.
|
||||
</li>
|
||||
<li>
|
||||
<b>Lease Contract: </b>Pre-funded escrow contract to reward oracles for
|
||||
their work.
|
||||
</li>
|
||||
<li>
|
||||
<b>Crank: </b>Optional, owned by the queue and allows a data feed to be
|
||||
updated at a regular interval.
|
||||
</li>
|
||||
<li>
|
||||
<b>History Buffer: </b>Optional, allows a feed to store the last N
|
||||
values.
|
||||
</li>
|
||||
</ul>
|
||||
</Grid>
|
||||
<Grid item md={8} sx={12} order={{ xs: 1, sm: 2 }}>
|
||||
<MarkdownImage
|
||||
img="/img/feeds/Aggregator_Accounts.png"
|
||||
sx={{
|
||||
display: "flex",
|
||||
}}
|
||||
/>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
<hr />
|
||||
|
||||
:::tip
|
||||
|
||||
See [/idl/accounts/AggregatorAccountData](/idl/accounts/AggregatorAccountData) for the full list of an AggregatorAccount's configuration parameters.
|
||||
|
||||
:::
|
||||
|
||||
## Job Definitions
|
||||
|
||||
An Aggregator Account stores a collection of Job Account public keys along with the hashes of the job definitions. This is to prevent malicious RPC nodes from providing incorrect task definitions to oracles before fulfillment.
|
||||
|
||||
A Job Account is a collection of [Switchboard Tasks](/api/tasks) that get executed by an oracle sequentially. Each Job Account typically corresponds to a single data source. A data feed requires at least one job account and at most 16 job accounts. Switchboard Job Accounts can be used to source data from:
|
||||
|
||||
- HTTP endpoints, public or private$^{[1]}$
|
||||
- Websockets
|
||||
- On-Chain data from Solana, Ethereum, etc
|
||||
- Anchor programs
|
||||
- JupiterSwap
|
||||
- Uniswap
|
||||
- SushiSwap
|
||||
- Saber
|
||||
- ... and more
|
||||
|
||||
$^{[1]}$ Endpoints requiring an API key require a [Private Queue](../queue/private-queues.mdx) to prevent leaking the API key on-chain
|
||||
|
||||
### Job Weights
|
||||
|
||||
A data feed can assign job weights to a job account which will be used when the oracle calculates the median across the job responses. This is useful to weight data sources by some metric such as liquidity or a reliability score.
|
||||
|
||||
It is **strongly** recommended to utilize job weights as _not all data sources are created equally_.
|
||||
|
||||
:::info
|
||||
|
||||
Currently the only way to set a job weight is to remove and re-add the job account to a feed.
|
||||
|
||||
:::
|
||||
|
||||
### Lease Contract
|
||||
|
||||
The LeaseContract is a pre-funded escrow account to reward oracles for fulfilling update request. The LeaseContract has a pre-specified `lease.withdrawAuthority` which is the only wallet allowed to withdraw funds from the lease escrow. Any user is able to contribute to a LeaseContract and keep the feed updating.
|
||||
|
||||
When a new openRound is successfully requested for a data feed, the user who requested it is transferred `queue.reward` tokens from the feeds LeaseContract. This is to incentivize users and crank turners to keep feeds updating based on a feeds config.
|
||||
|
||||
When a data feed result is accepted on-chain by a batch of oracles, the oracle rewards, as specified by `queue.reward`, are automatically deducted from the `lease.escrow` and transferred to an `oracle.tokenAccount`.
|
||||
|
||||
## Requesting Updates
|
||||
|
||||
A feed is updated when someone calls `aggregatorOpenRound` on-chain. If openRound is called before `aggregator.minUpdateDelaySeconds` have elapsed, the openRound call will fail and the user will forfeit their transaction fees. If successful, the user is rewarded for keeping the feed updating.
|
||||
|
||||
### Periodic Updates
|
||||
|
||||
Any data feed permitted to request updates on a queue is also permitted to join a queue's existing Crank, `aggregator.crankPubkey`. A Crank is the scheduling mechanism behind feeds that allow them to be periodically updated. The Crank is a buffer account that stores a collection of aggregator public keys, ordered by their next available update, with some level of jitter added to prevent a predictable oracle allocation cycle
|
||||
|
||||
When a feeds Lease Contract is low on funds, it is automatically removed from the crank and must be manually repushed upon refunding the LeaseContract.
|
||||
|
||||
A feed can set `aggregator.disableCrank` to prevent being pushed onto a Crank and draining it's lease.
|
||||
|
||||
## Data Feed Cost
|
||||
|
||||
Each data feed update cost can be calculated by the following equation:
|
||||
|
||||
$Cost_{perUpdate}=(1 + numSuccess) × queue.reward$
|
||||
|
||||
where,
|
||||
|
||||
- _`+1`_ is to reward the update requester for keeping the feed updating
|
||||
- `numSuccess` is the number of successful oracle responses, which will always be between `[aggregator.minOracleResults, aggregator.oracleRequestBatchSize]`
|
||||
- `queue.reward` is the queue's set oracle reward
|
||||
|
||||
If an update round fails to receive `minOracleResults`, only the update requester receives funds from the lease escrow.
|
||||
|
||||
### Variance Threshold
|
||||
|
||||
A feed can set an `aggregator.varianceThreshold` to instruct an oracle to skip reporting a value on-chain if the percentage change between the current result and the `aggregator.previousConfirmedRoundResult` is not exceeded. This is a cost saving tool to conserve lease cost during low volatility.
|
||||
|
||||
A feeds `aggregator.forceReportPeriod` is the compliment and instructs an oracle to always report a result if `aggregator.forceReportPeriod` seconds have elapsed since the last successful confirmed round. This can be thought of as the maximum allowable staleness for a feed.
|
||||
|
||||
The two settings above can greatly increase the lifespan of a feed's lease but also makes it difficult to estimate the remaining time on a lease.
|
||||
|
||||
Check out [@switchboard-xyz/lease-observer](https://github.com/switchboard-xyz/switchboard-v2/tree/main/packages/lease-observer) to get PagerDuty alerts when a lease crosses a low balance threshold.
|
||||
|
||||
## History Buffer
|
||||
|
||||
A history buffer account stores a set number of accepted results for an aggregator, and given Solana’s maximum account size of 10MB, the maximum number of samples a single history buffer can support is ~350,000 samples. An aggregator can only have a single history buffer associated with it.
|
||||
|
||||
A history buffer has a static account size when it is initialized, equal to: `12 Bytes + (28 Bytes × Num Samples)`. Each time an aggregator value is updated on-chain, the associated history buffer is shifted to the right, and the last value is dropped.
|
||||
|
||||
This feature allows Switchboard tasks to parse a history buffer and perform a set of calculations, such as the TwapTask. This allows feeds to reference other feeds and perform complex calculations based on historical samples.
|
||||
|
||||
## Update Lifecycle
|
||||
|
||||
Let's walk through what the feed update lifecycle looks like.
|
||||
|
||||
### Update Request
|
||||
|
||||
- Any user calls [aggregatorOpenRound](/idl/instructions/aggregatorOpenRound), either manually or via a crank turn
|
||||
- sbv2 program checks if `aggregator.minUpdateDelaySeconds` have passed since the last openRound call
|
||||
- sbv2 program checks if a LeaseContract has enough funds to reward the oracles for the next round
|
||||
- sbv2 program assigns the next `aggregator.oracleRequestBatchSize` oracles to the update request and emits an [AggregatorOpenRoundEvent](/idl/events/AggregatorOpenRoundEvent)
|
||||
|
||||
### Oracle Execution
|
||||
|
||||
- Oracle watches the chain for an [AggregatorOpenRoundEvent](/idl/events/AggregatorOpenRoundEvent) with the oracle's public key assigned to the update
|
||||
- Oracle fetches the feed and job account definitions from its RPC Provider
|
||||
- Oracle verifies the job account definitions match the feeds `aggregator.jobHashes`
|
||||
- Oracle executes the job definitions in parallel
|
||||
- When an oracle receives `aggregator.minJobResults`, it calculates the weighted median based on the feeds `aggregator.jobWeights`. Note, this is not enforced on-chain and is purely up to the oracle to respect
|
||||
- If a feed has configured a `aggregator.varianceThreshold` and `aggregator.forceReportPeriod` has not elapsed, the oracle calculates the percentage change between its calculated result and the previous confirmed round. If it does not exceed the feeds `aggregator.varianceThreshold`, the oracle drops the update request and waits for new update request
|
||||
- If a feeds configuration dictate a new on-chain result, the oracle submits an [aggregatorSaveResult](https://docs.switchboard.xyz/idl/instructions/aggregatorSaveResult) transaction
|
||||
|
||||
### Oracle Consensus
|
||||
|
||||
- sbv2 program waits for `aggregator.minOracleResults` to be submitted by the assigned oracles
|
||||
- When sufficient oracle responses, the sbv2 program computes the accepted value from the median of the oracle responses
|
||||
- If a feed has a history buffer account, the accepted result is pushed onto the buffer
|
||||
- Oracles that responded within `queue.varianceToleranceMultiplier` are rewarded `queue.reward` from the feed's LeaseContract
|
||||
- If `queue.slashingEnabled`, oracles that responded outside the `queue.varianceToleranceMultiplier` are slashed `queue.reward` tokens from it's `oracle.tokenAccount` and transferred to the feed's `lease.escrow`
|
||||
- If additional oracle responses are submitted after a value has been accepted, the median is recalculated based on the new response set, oracle rewards are redistributed, and the history buffer value is updated
|
||||
|
||||
## Data Feed Composability
|
||||
|
||||
Data feeds may reference other data feeds and build upon each other. It is **_strongly_** recommended that you own any feed that you reference in case of downstream impacts out of your control. While anyone can extend another feeds lease, a lease owner can always withdraw any lease funds and prevent future updates.
|
||||
|
||||
As an example, you could construct the following feed definition:
|
||||
|
||||
- Create a Switchboard feed that sources SOL/USD prices from a variety of exchanges, each weighted by their 7d volume, along with a history buffer
|
||||
- Create a Switchboard feed that uses an OracleTask to fetch the Pyth SOL/USD price every 10 seconds, along with a history buffer
|
||||
- Create a Switchboard feed that uses an OracleTask to fetch the Chainlink SOL/USD price every 10 seconds, along with a history buffer
|
||||
- Finally, create a Switchboard feed that calculates the 1min TWAP of each source above and returns the median of the results
|
||||
|
||||
This is just a small window into how Switchboard feeds can build on each other and let the downstream consumer configure their feeds to meet their own use cases.
|
||||
|
||||
## More Information
|
||||
|
||||
- [/api/tasks](/api/tasks)
|
||||
- [/idl/accounts/AggregatorAccountData](/idl/accounts/AggregatorAccountData)
|
||||
- [/idl/accounts/CrankAccountData](/idl/accounts/CrankAccountData)
|
||||
- [/idl/accounts/AggregatorHistoryBuffer](/idl/accounts/AggregatorHistoryBuffer)
|
||||
- [/idl/accounts/PermissionAccountData](/idl/accounts/PermissionAccountData)
|
||||
- [/idl/accounts/JobAccountData](/idl/accounts/JobAccountData)
|
||||
- [/idl/accounts/LeaseAccountData](/idl/accounts/LeaseAccountData)
|
||||
- [feed-parser Typescript Example](https://github.com/switchboard-xyz/switchboard-v2/tree/main/packages/feed-parser)
|
||||
- [feed-walkthrough Typescript Example](https://github.com/switchboard-xyz/switchboard-v2/tree/main/packages/feed-walkthrough)
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
sidebar_position: 15
|
||||
title: Feed Operator
|
||||
---
|
||||
|
||||
This page gives an overview on how to configure and operate a Switchboard feed.
|
||||
|
||||
## Job Consensus
|
||||
|
||||
Job consensus refers to how individual oracles calculate their result from a feeds assigned job accounts.
|
||||
|
||||
**_Job Diversity_**
|
||||
|
||||
Data feeds should source data from a variety of sources when applicable. A feed relying on a single source is at the mercy of that sources uptime and responsiveness.
|
||||
|
||||
**_Job Weights_**
|
||||
|
||||
Data feeds should use job weights to calculate the weighted median, which is what the oracle submits on-chain as its final result. A data source that has the majority of an assets price action should be weighted higher than a dead exchange with questionable volume metrics.
|
||||
|
||||
## Oracle Consensus
|
||||
|
||||
Oracle consensus refers to how the final on-chain result is calculated from a batch of oracle responses. A feed's `aggregator.oracleRequestBatchSize` is the number of oracles assigned to a request, while `aggregator.minOracleResults` is the number of responses needed to accept a result.
|
||||
|
||||
**_Increase oracleRequestBatchSize_**
|
||||
|
||||
The quickest way to increase feed security is to request more oracles each update round because this requires a higher degree of oracle collusion in order to affect the accepted result. In reality, this increases the overall cost of a feed so its a careful consideration for feed operators when configuring a feed.
|
||||
|
||||
**_ oracleRequestBatchSize $\neq$ minOracleResults _**
|
||||
|
||||
The number of oracles assigned to an update request should always be less than the number of oracles required to respond. There are a variety of reasons that may cause an oracle response to fail, such as Solana network degradation, individual oracle network issues, or transaction spamming. Your feed's lease is only deducted when an oracle successfully responds and there is no penalty for an oracle who has timed out.
|
||||
|
||||
## Feed Maintenance
|
||||
|
||||
The primary maintenance for a feed is ensuring the lease contract has sufficient funds. The [@switchboard-xyz/lease-observer](https://github.com/switchboard-xyz/switchboard-v2/tree/main/packages/lease-observer) demonstrates how to emit PagerDuty events when a lease is low on funds.
|
||||
|
||||
:::caution
|
||||
|
||||
When a data feed's lease contract does not have enough funds, it will be automatically removed from its crank. When extending a feed's lease, make sure to also repush the feed back onto any cranks for updates to continue.
|
||||
|
||||
:::
|
||||
|
||||
You should also monitor the feed for staleness in case of downstream changes to a data sources endpoint.
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Publisher",
|
||||
"position": 50,
|
||||
"collapsible": false
|
||||
}
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
sidebar_position: 30
|
||||
title: Curation
|
||||
---
|
||||
|
||||
# Job Curation
|
||||
|
||||
- Job Accounts include an author wallet
|
||||
- When a job account is used by a data feed, the job account creator is rewarded
|
||||
- Curators rewarded for populating publisher catalog
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
sidebar_position: 20
|
||||
title: Job Builder
|
||||
---
|
||||
|
||||
# Job Builder
|
||||
|
||||
- Build jobs
|
||||
- [/api/tasks](/api/tasks)
|
||||
|
|
@ -0,0 +1,275 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
slug: .
|
||||
title: Overview
|
||||
---
|
||||
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
|
||||
<Typography variant="h4">
|
||||
<Link to="https://publish.switchboard.xyz/"># publish.switchboard.xyz</Link>
|
||||
</Typography>
|
||||
|
||||
The publisher site is a decentralized marketplace that allows anyone to build a data feed and deploy it on-chain. The site includes a directory of pre-defined feeds from popular sources such as FTX, Coinbase, or any permissionless Serum market. The publisher site streamlines the on-chain workflow and allows a user to configure a data feed from a convienent UI.
|
||||
|
||||
## Connect
|
||||
|
||||
<Grid container spacing={3} justifyContent="space-around">
|
||||
<Grid item md={4}>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Connect_Wallet.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
</Grid>
|
||||
<Grid item md={6}>
|
||||
<Typography>
|
||||
The publisher site contains a <i>Connect Wallet</i> button in the top
|
||||
right corner that allows you to connect your web wallet to Devnet or
|
||||
Mainnet.
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>
|
||||
The publisher site currently supports the following wallets:
|
||||
</Typography>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="https://phantom.app/" target="_blank">
|
||||
Phantom
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://slope.finance/" target="_blank">
|
||||
Slope
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://wallet.coin98.com/" target="_blank">
|
||||
Coin98
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://solflare.com/" target="_blank">
|
||||
Solflare
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://www.sollet.io/" target="_blank">
|
||||
Sollet
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
## Directory
|
||||
|
||||
The publisher site includes some pre-defined sources to help developers publish data feeds. Pre-defined sources can be added to your basket by selecting them in the directory, from there you can toggle individual data sources to meet your on-chain needs.
|
||||
|
||||
**Coming Soon:** Users will soon have the ability to publish their own sources to the site and help grow the catalog.
|
||||
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Directory.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
|
||||
## Checkout
|
||||
|
||||
During checkout, the publisher will create the necessary accounts for your data feed.
|
||||
|
||||
### Lease
|
||||
|
||||
<Grid container spacing={3} justifyContent="space-around">
|
||||
<Grid item md={5} sm={12}>
|
||||
<b>
|
||||
<u>Automatic Updates</u>
|
||||
</b>
|
||||
<Typography>
|
||||
The <i>Enable automatic updates</i> checkbox determines whether your data
|
||||
feed will be added to a crank. A crank allows data feeds to be updated at
|
||||
regular intervals. Event based feeds should uncheck this box.
|
||||
</Typography>
|
||||
<br />
|
||||
<b>
|
||||
<u>Update Interval</u>
|
||||
</b>
|
||||
<Typography>
|
||||
The update interval lets you configure how often and how long a data feed
|
||||
should be updated for. This derives the total cost deposited into the
|
||||
lease contract escrow account, which is used to fund oracles each time a
|
||||
feed is updated. You can extend or terminate a lease at anytime.
|
||||
</Typography>
|
||||
<br />
|
||||
</Grid>
|
||||
<Grid item md={6}>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Lease_Contract_Modal.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 5 }}
|
||||
/>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
### Account Creation
|
||||
|
||||
<Grid container spacing={3} justifyContent="space-around">
|
||||
<Grid item md={6} order={{ xs: 2, md: 1 }}>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Account_Creation.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
</Grid>
|
||||
<Grid item md={6} order={{ xs: 1, md: 2 }}>
|
||||
<Typography>
|
||||
The <i>Account Creation</i> modal gives you a summary of your balance
|
||||
changes before any on-chain transactions occur. Once you have verified the
|
||||
total cost, hit <i>Create Feed</i> to submit the transactions.
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>
|
||||
After the accounts have been created, you will be redirected to the My
|
||||
Feeds page to view your newly created data feeds.
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>
|
||||
By default, data feeds are added to the permissionless queue, where they
|
||||
can begin updating immediately. Data feeds can be upgraded to the
|
||||
permissioned queue by submitting a request to the Switchboard DAO.
|
||||
</Typography>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
## My Feeds
|
||||
|
||||
The My Feeds page shows you a list of active data feeds associated with your wallet.
|
||||
|
||||
<MarkdownImage
|
||||
img="/img/publisher/My_Feeds.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
|
||||
<br />
|
||||
|
||||
The publisher site lets you manage your on-chain feeds and currently lets you:
|
||||
|
||||
<Grid container spacing={3} justifyContent="space-around">
|
||||
<Grid item md={3} order={{ xs: 2, md: 1 }}>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/My_Feeds_Actions.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
</Grid>
|
||||
<Grid item md={7} order={{ xs: 1, md: 2 }}>
|
||||
<ul>
|
||||
<li>
|
||||
<b>View Feed Details: </b> View the Aggregator configuration such as
|
||||
current accepted result, oracle batch size, and associated Job account
|
||||
public keys.
|
||||
</li>
|
||||
<li>
|
||||
<b>View In Explorer: </b> View the Aggregator in the Solana block
|
||||
explorer.
|
||||
</li>
|
||||
<li>
|
||||
<b>Track Feed History: </b> Optionally, add an{" "}
|
||||
<Link to="/feed#history-buffer">aggregator history buffer</Link> to
|
||||
track the last N recorded samples.
|
||||
</li>
|
||||
<li>
|
||||
<b>Extend Lease: </b> Deposit funds in the feeds lease contract.
|
||||
</li>
|
||||
<li>
|
||||
<b>Terminate Lease: </b> Withdraw remaining funds from a feeds lease
|
||||
contract and if present, remove it from its crank.
|
||||
</li>
|
||||
</ul>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
## Custom Feeds
|
||||
|
||||
<Grid container spacing={3}>
|
||||
<Grid item md={6}>
|
||||
<Typography>
|
||||
The <i>Custom Feed</i> button lets you build a custom feed from a JSON
|
||||
definition:
|
||||
</Typography>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Custom_Feed_Button.png"
|
||||
sx={{
|
||||
width: "70%",
|
||||
textAlign: "center",
|
||||
mx: 2,
|
||||
display: "flex",
|
||||
borderRadius: 3,
|
||||
overflow: "hidden",
|
||||
}}
|
||||
/>
|
||||
<br />
|
||||
<Typography>
|
||||
You should see the <i>Custom Feed Modal</i> to the right. Give your feed a
|
||||
name, then for each job you require, select <i>Add Job +</i>.
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>A data feed must have at least one job.</Typography>
|
||||
</Grid>
|
||||
<Grid item md={6}>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Custom_Feed_Modal.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
### Custom Jobs
|
||||
|
||||
<Grid container spacing={3}>
|
||||
<Grid item md={6}>
|
||||
<MarkdownImage
|
||||
img="/img/publisher/Custom_Job_Modal.png"
|
||||
sx={{ borderWidth: "thin", border: "1px solid #D3D3D3", borderRadius: 3 }}
|
||||
/>
|
||||
</Grid>
|
||||
<Grid item md={6}>
|
||||
<Typography>
|
||||
The <i>Custom Job</i> modal lets you build a custom job from a JSON
|
||||
definition or Public Key.
|
||||
</Typography>
|
||||
<br />
|
||||
<b>
|
||||
<u>JSON Definition</u>
|
||||
</b>
|
||||
<Typography>
|
||||
You can find example job definitions at:
|
||||
<ul>
|
||||
<li>
|
||||
<Link to="/api/tasks">/api/tasks</Link>
|
||||
</li>
|
||||
<li>
|
||||
<Link to="/feed/directory">Job Directory</Link>
|
||||
</li>
|
||||
<li>
|
||||
<Link to="https://switchboard.xyz/explorer">
|
||||
Switchboard Explorer
|
||||
</Link>
|
||||
</li>
|
||||
</ul>
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>
|
||||
Paste in your JSON definition, then select <i>Test</i> to simulate the job
|
||||
and view the result.
|
||||
</Typography>
|
||||
<br />
|
||||
<b>
|
||||
<u>Public Key</u>
|
||||
</b>
|
||||
<Typography>
|
||||
You can use an existing JobAccount public key to build your data feed.
|
||||
This is useful if you are building multiple feeds that share job
|
||||
definitions.
|
||||
</Typography>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
When done, select _Add Job_ to return to the _Custom Feed_ modal.
|
||||
|
|
@ -6,8 +6,6 @@ slug: /introduction
|
|||
|
||||
# Introduction
|
||||
|
||||
import MarkdownImage from "../src/components/MarkdownImage";
|
||||
|
||||
> Switchboard is a community-driven, decentralized oracle network built on Solana that allows anyone to publish on-chain data for smart contract developers to reliably build upon.
|
||||
|
||||
Switchboard is a community governed protocol — if additional on-chain data is needed, you will be able to publish it yourself after reading through these docs.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
{
|
||||
"label": "Oracles",
|
||||
"position": 20
|
||||
"position": 20,
|
||||
"collapsible": true
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
import OracleMetrics from "/idl/types/OracleMetrics.md";
|
||||
|
||||
# Oracle Architecture
|
||||
|
||||
A Switchboard oracle is a Node.js container that sits between the Solana blockchain and the internet and waits for update requests from an oracle queue. An oracle queue assigns updates to oracles in a round robin fashion.
|
||||
|
||||
An oracle account is a program derived address (PDA) between the oracle queue it’s being initialized for, as well as the authority public key which will control it. Before an oracle is granted permissions to use a queue, it must transfer the minimum stake amount, set by the queue, to its escrow wallet.
|
||||
|
||||
## Staking
|
||||
|
||||
An oracle is required to transfer `queue.minStake` tokens to its staking wallet, `oracle.tokenAccount`, before being granted queue permissions. The minStake acts as an insurance policy to entice honest oracle behavior.
|
||||
|
||||
## Heartbeat
|
||||
|
||||
An oracle is required to heartbeat on-chain, `oracle.lastHeartbeat`, in order to join the queue and be assigned update request. An oracle must heartbeat before the queue's specified `queue.oracleTimeout` or it will be removed from the queue.
|
||||
|
||||
## Metrics
|
||||
|
||||
The oracle also tracks its performance, `oracle.metrics`.
|
||||
|
||||
<OracleMetrics />
|
||||
|
||||
## Cost & Reward Estimations
|
||||
|
||||
An oracle is required to submit an [aggregatorSaveResult](/idl/instructions/aggregatorSaveResult) transaction each time it updates a feed, which incurs a cost of 5000 lamports. This fee is set by the Solana network and is subject to change.
|
||||
|
||||
$Reward_{perUpdate}=queue.reward - 5000$
|
||||
|
||||
To estimate an oracles cost basis, you will need to know a queue's capacity (Oracles, Feeds, VRFs) and the average number of update request an oracle is assigned over a given time period.
|
||||
|
||||
You will also need to factor in the oracle's heartbeat cost, which is 5000 lamports each. The number of heartbeats is dependent on its `queue.oracleTimeout`, which determines how often an oracle is required to heartbeat.
|
||||
|
||||
## More Information
|
||||
|
||||
- [/idl/accounts/OracleAccountData](/idl/accounts/OracleAccountData)
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Oracle Service",
|
||||
"position": 10,
|
||||
"collapsible": false
|
||||
}
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
title: Docker
|
||||
---
|
||||
|
||||
# Docker
|
||||
|
||||
You can run an oracle locally and assign it to your own oracle queue to test how your program may operate in production. Mainnet oracles should always be run in high availability environments with some set of monitoring capabilities.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Docker-Compose](https://docs.docker.com/compose/install/) or another container orchestration pipeline
|
||||
|
||||
## Setup
|
||||
|
||||
Create a docker-compose.yml file with the required environment variables, as defined in [Oracle Config](./#config).
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="local" label="Local Machine" default>
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
version: "3.3"
|
||||
services:
|
||||
switchboard:
|
||||
image: "switchboardlabs/node:dev-v2-5-3-22"
|
||||
network_mode: host
|
||||
restart: always
|
||||
environment:
|
||||
- LIVE=1
|
||||
- CLUSTER=devnet
|
||||
- RPC_URL=${RPC_URL}
|
||||
- ORACLE_KEY=${ORACLE_KEY}
|
||||
- HEARTBEAT_INTERVAL=15
|
||||
volumes:
|
||||
- ./configs.json:/configs.json
|
||||
secrets:
|
||||
PAYER_SECRETS:
|
||||
file: /filesystem/path/to/keypair.json
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="gcp" label="Google Container">
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
version: "3.3"
|
||||
services:
|
||||
switchboard:
|
||||
image: "switchboardlabs/node:dev-v2-5-3-22
|
||||
network_mode: host
|
||||
restart: always
|
||||
environment:
|
||||
- LIVE=1
|
||||
- CLUSTER=devnet
|
||||
- RPC_URL=${RPC_URL}
|
||||
- ORACLE_KEY=${ORACLE_KEY}
|
||||
- HEARTBEAT_INTERVAL=15
|
||||
- GOOGLE_PAYER_SECRET_PATH=${GOOGLE_PAYER_SECRET_PATH}
|
||||
- GCP_CONFIG_BUCKET=${GCP_CONFIG_BUCKET}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
## Running
|
||||
|
||||
Run the following command to start the container
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
|
@ -0,0 +1,543 @@
|
|||
---
|
||||
sidebar_position: 20
|
||||
title: Google Cloud Platform
|
||||
---
|
||||
|
||||
Before deploying the application, you must first provision a kubernetes cluster with the relevant credentials. There are no exotic requirements for this cluster and to date, it has be able to run on an auto pilot GKE cluster without issue.
|
||||
|
||||
A Switchboard oracle can be run on any cloud provider who offers kubernetes services but this guide will currently be focused on Google Cloud. Feel free to contribute to our documentation if you are running an oracle on another provider. Here's some extra reading to learn more about kubernetes:
|
||||
|
||||
- [What is Kubernetes?](https://cloud.google.com/learn/what-is-kubernetes)
|
||||
- [Kubernetes Engine Quickstart](https://cloud.google.com/kubernetes-engine/docs/quickstart)
|
||||
|
||||
## Requirements
|
||||
|
||||
### Switchboard Helm Charts
|
||||
|
||||
The repo below contains the kubernetes manifest to streamline the deployment. Clone the repo below to get started:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/switchboard-xyz/switchboard-v2
|
||||
cd switchboard-v2/oracles/helm-deployment
|
||||
```
|
||||
|
||||
### gcloud SDK
|
||||
|
||||
You will need to install the google cloud SDK and have a Google Cloud Platform account
|
||||
|
||||
- [Install gcloud SDK](https://cloud.google.com/sdk/docs/install)
|
||||
- [Google Cloud Platform Registration](https://console.cloud.google.com/freetrial/signup/tos)
|
||||
|
||||
Verify it installed correctly with the following command:
|
||||
|
||||
```bash
|
||||
gcloud --version
|
||||
```
|
||||
|
||||
### Grafana Domain Name
|
||||
|
||||
You will need a domain name to point your grafana instance at to monitor your oracle's metrics. During setup, you will create an external IP, which you will need to add to your domains DNS records. Finally we will provision a TLS certificate for your domain for enhanced security.
|
||||
|
||||
## Environment
|
||||
|
||||
You will need to collect the following environment variables to inject into the helm charts before deploying to Google Cloud Project. If you chose to use the automated deployment, an env file will be populated with most of these variables populated.
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
<b>GCP Environment Variables</b>
|
||||
</summary>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Env Variable</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>CLUSTER</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - String (devnet / mainnet-beta)
|
||||
<br />
|
||||
<b>Description</b> - Solana cluster you will be running an oracle on
|
||||
(mainnet-beta/devnet)
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>RPC_URL</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - URL
|
||||
<br />
|
||||
<b>Description</b> - Solana RPC URL that must be capable of supporting
|
||||
websockets. The default RPC pools should be avoided at all cost as you
|
||||
will quickly hit the rate limits and risk being slashed
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WS_URL</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - URL
|
||||
<br />
|
||||
<b>Default</b> - RPC_URL
|
||||
<br />
|
||||
<b>Description</b> - Websocket URL to connect to a Solana RPC server. If
|
||||
not provided, oracle will fallback to RPC_URL
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BACKUP_MAINNET_RPC</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - URL
|
||||
<br />
|
||||
<b>Default</b> - https://api.mainnet-beta.solana.com
|
||||
<br />
|
||||
<b>Description</b> - Backup RPC URL in case of network congestion
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ORACLE_KEY</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Public Key
|
||||
<br />
|
||||
<b>Description</b> - Public key of the oracle account that has been
|
||||
granted permissions to use an oracle queue <br />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>HEARTBEAT_INTERVAL</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Number (seconds)
|
||||
<br />
|
||||
<b>Default</b> - 15
|
||||
<br />
|
||||
<b>Description</b> - Seconds between oracle heartbeats. Queues have
|
||||
different oracle heartbeat requirements. Recommended value is 15
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SERVICE_ACCOUNT_BASE64</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Base64 encoded JSON file
|
||||
<br />
|
||||
<b>Description</b> - Base64 encoded JSON file containing the private key
|
||||
for your service account that has access to your google secret keypair
|
||||
and config bucket
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GOOGLE_PAYER_SECRET_PATH</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - GCP Resource Path
|
||||
<br />
|
||||
<b>Description</b> - Google cloud resource to manage your keypair
|
||||
securely.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GCP_CONFIG_BUCKET</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - GCP Resource Path
|
||||
<br />
|
||||
<b>Default</b> - oracle-configs:configs.json
|
||||
<br />
|
||||
<b>Description</b> - Contains API keys for private API endpoints
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>EXTERNAL_IP</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - IPv4 Address
|
||||
<br />
|
||||
<b>Description</b> - IP Address where your grafana instance will be
|
||||
hosted to view metrics and oracle operating status
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GRAFANA_HOSTNAME</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Fully Qualified Domain Name
|
||||
<br />
|
||||
<b>Description</b> - Hostname where your grafana instance will point to
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GRAFANA_PASSWORD</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - String / Password
|
||||
<br />
|
||||
<b>Default</b> - Sbv2K8sPassword123@
|
||||
<br />
|
||||
<b>Description</b> - Password to admin account that allows access to
|
||||
your grafana instance. You can set this to whatever value you want.
|
||||
<br />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GRAFANA_TLS_CRT</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Base64 encoded CRT file
|
||||
<br />
|
||||
<b>Description</b> - Base64 encoded string of your TLS certificate to
|
||||
secure your grafana instance
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GRAFANA_TLS_KEY</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Base64 encoded private key file
|
||||
<br />
|
||||
<b>Description</b> - Base64 encoded string of the private key used to
|
||||
create your TLS certificate
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
</details>
|
||||
|
||||
## Setup
|
||||
|
||||
The `oracles/helm-deployment` directory in the [Switchboard-V2 SDK](https://github.com/switchboard-xyz/switchboard-v2) contains a bash script to walk through the GCP setup and output the required variables to an env file. This script is provided as a convenience tool, you should understand all of the commands in the script before running. To automate the GCP setup, run the following command:
|
||||
|
||||
```bash
|
||||
./setup-gcloud.sh PROJECTNAME
|
||||
|
||||
# ./setup-gcloud.sh Sbv2-Devnet-Oracle
|
||||
```
|
||||
|
||||
- `PROJECTNAME` will be the name of your GCP project and must contain no spaces or special characters
|
||||
|
||||
The script will walk-through the google cloud setup, create your gcp project, add your oracle keypair as a secret, create a service account and give it access to your keypair, then spin up a kubernetes cluster. The script will periodically prompt you for more information.
|
||||
|
||||
Upon completion you will have a file `PROJECTNAME.env` containing:
|
||||
|
||||
- PROJECT
|
||||
- DEFAULT_REGION
|
||||
- DEFAULT_ZONE
|
||||
- CLUSTER_NAME
|
||||
- EXTERNAL_IP
|
||||
- SECRET_NAME
|
||||
- GOOGLE_PAYER_SECRET_PATH
|
||||
- GCP_CONFIG_BUCKET
|
||||
- SERVICE_ACCOUNT_EMAIL
|
||||
- SERVICE_ACCOUNT_BASE64
|
||||
|
||||
You will need to manually add:
|
||||
|
||||
- CLUSTER
|
||||
- RPC_URL
|
||||
- BACKUP_MAINNET_RPC
|
||||
- ORACLE_KEY
|
||||
- GRAFANA_HOSTNAME
|
||||
- GRAFANA_PASSWORD
|
||||
- GRAFANA_TLS_CRT
|
||||
- GRAFANA_TLS_KEY
|
||||
|
||||
<details>
|
||||
<summary><b>Manual GCP Setup Steps</b></summary>
|
||||
|
||||
<b>Login</b>
|
||||
|
||||
Login to your google cloud account:
|
||||
|
||||
```bash
|
||||
gcloud auth login
|
||||
```
|
||||
|
||||
<b>Project</b>
|
||||
|
||||
Create a new project
|
||||
|
||||
```bash
|
||||
gcloud projects create switchboard-oracle-cluster --name="Switchboard Oracle"
|
||||
```
|
||||
|
||||
Set it as your default project
|
||||
|
||||
```bash
|
||||
gcloud config set project switchboard-oracle-cluster
|
||||
```
|
||||
|
||||
[Google - gcloud projects create](https://cloud.google.com/sdk/gcloud/reference/projects/create)
|
||||
|
||||
<b>gCloud Conifg</b>
|
||||
|
||||
Set the default zone using [list of regions and zones](https://cloud.google.com/compute/docs/regions-zones#available)
|
||||
|
||||
```bash
|
||||
gcloud config set compute/zone us-west1-a # replace with your closest region
|
||||
```
|
||||
|
||||
Set the default region using [list of regions and zones](https://cloud.google.com/compute/docs/regions-zones#available)
|
||||
|
||||
```bash
|
||||
gcloud config set compute/region us-west1 # replace with your closest region
|
||||
```
|
||||
|
||||
[Google - Set default settings for the gcloud tool](https://cloud.google.com/kubernetes-engine/docs/quickstart#autopilot)
|
||||
|
||||
<b>Billing</b>
|
||||
|
||||
You will need to enable billing for the project before enabling any services:
|
||||
|
||||
- https://console.cloud.google.com/billing/enable?project=switchboard-oracle-cluster
|
||||
|
||||
[Google - APIs and billing](https://support.google.com/googleapi/answer/6158867?hl=en)
|
||||
|
||||
<b>Services</b>
|
||||
|
||||
Enable the relevant services:
|
||||
|
||||
```bash
|
||||
gcloud services enable compute.googleapis.com
|
||||
gcloud services enable container.googleapis.com
|
||||
gcloud services enable iamcredentials.googleapis.com
|
||||
gcloud services enable secretmanager.googleapis.com
|
||||
```
|
||||
|
||||
<b>External IP</b>
|
||||
|
||||
You will need to reserve a static IP address for your grafana instance
|
||||
|
||||
```bash
|
||||
gcloud compute addresses create load-balancer --project=switchboard-oracle-cluster
|
||||
gcloud compute addresses list
|
||||
# NAME ADDRESS/RANGE
|
||||
# load-balancer 123.123.123.123 ($LOADBALANCER_IP)
|
||||
```
|
||||
|
||||
This will be your `$EXTERNAL_IP`
|
||||
|
||||
[Google - Reserve a new static external IP address](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#reserve_new_static)
|
||||
|
||||
<b>Service Account</b>
|
||||
|
||||
You will need to create a service account to access our resources.
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts create svc-account --display-name="Oracle Service Account"
|
||||
gcloud iam service-accounts list
|
||||
```
|
||||
|
||||
Now save it to our filesystem
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts keys create secrets/svc-account.json --iam-account=svc-account@switchboard-oracle-cluster.iam.gserviceaccount.com
|
||||
```
|
||||
|
||||
Now convert the json file to a base64 string to store in `$SERVICE_ACCOUNT_BASE64`
|
||||
|
||||
```bash
|
||||
base64 secrets/svc-account.json
|
||||
```
|
||||
|
||||
[Google - Creating service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)
|
||||
|
||||
<b>OraclePayerSecret</b>
|
||||
|
||||
You will need to store your solana keypair in Google Secret Manager for enhanced security. If you are using another keypair replace `--data-file` with your relevant path.
|
||||
|
||||
```bash
|
||||
gcloud secrets create oracle-payer-secret --replication-policy="automatic" --data-file=secrets/authority-keypair.json
|
||||
```
|
||||
|
||||
You can view your `$GOOGLE_PAYER_SECRET_PATH` in the [GCP console](https://console.cloud.google.com/security/secret-manager/secret/oracle-payer-secret/versions&project=switchboard-oracle-cluster) or by running the command
|
||||
|
||||
```bash
|
||||
echo "$(gcloud secrets list --uri --filter=oracle-payer-secret | \
|
||||
cut -c41- | tr -d '\n')/versions/latest"
|
||||
```
|
||||
|
||||
[Google - Creating a secret](https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets)
|
||||
|
||||
<b>Storage Bucket</b>
|
||||
|
||||
You can create a GCP storage bucket to store API keys. The following command will create a new storage bucket and give your service account permissions to read from it. You will need to use a unique name as storage bucket names are global to the entire GCP platform.
|
||||
|
||||
```bash
|
||||
gsutil mb -p switchboard-oracle-cluster -l us-west1 gs://switchboard-oracle-cluster-bucket
|
||||
gsutil iam ch serviceAccount:svc-account@switchboard-oracle-cluster.iam.gserviceaccount.com:legacyBucketReader gs://switchboard-oracle-cluster-bucket
|
||||
gsutil ls
|
||||
# gs://switchboard-oracle-cluster-bucket/
|
||||
```
|
||||
|
||||
You can view your `$GCP_CONFIG_BUCKET` by running the command
|
||||
|
||||
```bash
|
||||
echo "$(gsutil ls | grep 'switchboard-oracle-cluster-bucket' | \
|
||||
sed -e 's/.*gs:\/\/\(.*\)\/.*/\1/' ):configs.json"
|
||||
# switchboard-oracle-cluster-bucket:configs.json
|
||||
```
|
||||
|
||||
[Google - Create storage buckets](https://cloud.google.com/storage/docs/creating-buckets#storage-create-bucket-gsutil)
|
||||
|
||||
<b>Kubernetes Cluster</b>
|
||||
|
||||
Finally you will need to create a new kubernetes cluster
|
||||
|
||||
```bash
|
||||
gcloud container clusters create-auto switchboard-cluster \
|
||||
--service-account=svc-account@switchboard-oracle-cluster.iam.gserviceaccount.com \
|
||||
--region us-west1
|
||||
```
|
||||
|
||||
then connect to it and store your credentials in your gCloud config
|
||||
|
||||
```bash
|
||||
gcloud container clusters get-credentials switchboard-cluster \
|
||||
--project switchboard-oracle-cluster \
|
||||
--region us-west1
|
||||
```
|
||||
|
||||
:::note
|
||||
Remember to update the region to the same region you used for your static IP.
|
||||
:::
|
||||
|
||||
[Google - Create a GKE cluster](https://cloud.google.com/kubernetes-engine/docs/quickstart#autopilot)
|
||||
|
||||
<b>Wrapping Up</b>
|
||||
|
||||
You should now have an `PROJECTNAME.env` file containing
|
||||
|
||||
- EXTERNAL_IP
|
||||
- GOOGLE_PAYER_SECRET_PATH
|
||||
- GCP_CONFIG_BUCKET
|
||||
- SERVICE_ACCOUNT_BASE64
|
||||
|
||||
You will need to manually add:
|
||||
|
||||
- CLUSTER
|
||||
- RPC_URL
|
||||
- BACKUP_MAINNET_RPC
|
||||
- ORACLE_KEY
|
||||
- GRAFANA_HOSTNAME
|
||||
- GRAFANA_PASSWORD
|
||||
- GRAFANA_TLS_CRT
|
||||
- GRAFANA_TLS_KEY
|
||||
|
||||
</details>
|
||||
|
||||
## Grafana
|
||||
|
||||
Grafana is a visualization tool to view your cluster's metrics. While this step is optional, it is recommended if you have no other monitoring or metric suite in place.
|
||||
|
||||
### Domain Name
|
||||
|
||||
You will need a domain name to host your grafana instance. In your domain management tool, add a DNS A record with a value of `$EXTERNAL_IP`.
|
||||
|
||||
This value will be your `$GRAFANA_HOSTNAME` (i.e. grafana.switchboard.com) and will be used to provision a TLS certificate.
|
||||
|
||||
### TLS Certificate
|
||||
|
||||
The following steps will walk you through provisioning a TLS certificate for your domain from letsencrypt. The [helm-manifest repo](https://github.com/switchboard-xyz/helm-manifests) contains a script to walk through creating the neccessary keys and certificate signing request (CSR).
|
||||
|
||||
```bash
|
||||
./setup-grafana.sh PROJECTNAME DOMAIN EMAIL
|
||||
```
|
||||
|
||||
- PROJECTNAME is the name of the env file to store variables
|
||||
- DOMAIN is your $GRAFANA_HOSTNAME from above
|
||||
- EMAIL is the email you will use for your certificate signing request
|
||||
|
||||
When the necessary keys and CSR are generated, head over to [gethttpsforfree.com](https://gethttpsforfree.com.com) and walk through their steps to sign your certificate. Save the final output to the filename given by the script, then rerun the script. The script will save the env variables to `PROJECTNAME.env` and also output them to the console.
|
||||
|
||||
Your `PROJECTNAME.env` file should now contain
|
||||
|
||||
- GRAFANA_HOSTNAME
|
||||
- GRAFANA_PASSWORD (You can set this to whatever value you want)
|
||||
- GRAFANA_TLS_CRT
|
||||
- GRAFANA_TLS_KEY
|
||||
|
||||
## Deploy
|
||||
|
||||
After completing the steps on this page you should have a `PROJECTNAME.env` file with each of the required variables defined. See [Google Cloud / Environment](#environment) for a list of all required variables that must be set.
|
||||
|
||||
Run the following command to build the helm charts with your environment variables injected into the manifests:
|
||||
|
||||
```bash
|
||||
./build-helm.sh PROJECTNAME
|
||||
```
|
||||
|
||||
### Deploy Helm Charts
|
||||
|
||||
Run the command
|
||||
|
||||
```bash
|
||||
./deploy-helm.sh PROJECTNAME
|
||||
```
|
||||
|
||||
When complete, you should see your cluster running in the Google Cloud Console.
|
||||
|
||||
[Google - Observing your GKE clusters](https://cloud.google.com/stackdriver/docs/solutions/gke/observing)
|
||||
|
||||
### Update
|
||||
|
||||
If necessary, rebuild the charts to update any environment variables:
|
||||
|
||||
```bash
|
||||
./build-helm.sh PROJECTNAME
|
||||
```
|
||||
|
||||
then redeploy the helm charts:
|
||||
|
||||
```bash
|
||||
./deploy-helm.sh PROJECTNAME
|
||||
```
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
sidebar_position: 30
|
||||
title: Monitoring
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
The oracle uses open telemetry for emitting metrics.
|
||||
As such, at the time of this writing, the oracle supports prometheus (as well as any wire-compatible solution like cortex, thanos or victoria metrics) and GCP monitoring.
|
||||
This can be configured via the `$METRICS_EXPORTER` environmental variable ('prometheus' and 'gcp')
|
||||
|
||||
If GCP monitoring is used, all data collection and visualization is handled by the platform although users are advised to closely watch billing.
|
||||
|
||||
For users that are either not running on GCP or want a more cost effective solution, grafana and victoria metrics (prometheus compatible scraping+storage) manifests are provided in the kubernetes-manifests repo.
|
||||
|
||||
<details open>
|
||||
<summary>List of metrics</summary>
|
||||
<table>
|
||||
<tr>
|
||||
<th>Metric Name</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_aggregator_variance</td>
|
||||
<td>
|
||||
the ratio between the largest and smallest value from all aggregated
|
||||
responses for a given job
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_heartbeat_failure_total</td>
|
||||
<td>a counter for every time there is a heartbeat failure</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_job_failure_total</td>
|
||||
<td>a counter for every time there is a job failure</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_job_success_total</td>
|
||||
<td>
|
||||
a counter for every time there is a successful completion of a job
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_job_posting_total</td>
|
||||
<td>a counter for every time there is a job posting</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_log_age</td>
|
||||
<td>a value recorder for the age of the job logs when processed</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_node_aggregation_insufficient_responses_total</td>
|
||||
<td>
|
||||
a counter for every time there is an insufficient number of aggregated
|
||||
responses for a job
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_node_balance</td>
|
||||
<td>
|
||||
each oracle will report its balance with a label indicating the public
|
||||
key
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>switchboard_save_result_failure_total</td>
|
||||
<td>
|
||||
a counter for the number of times an oracle is unable to commit a
|
||||
transaction to the blockchain
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>scheduler_node_balance</td>
|
||||
<td>most recent balance of the scheduler wallet</td>
|
||||
</tr>
|
||||
</table>
|
||||
</details>
|
||||
|
||||
## Alerts
|
||||
|
||||
Pagerduty allows you to get real time alerts on your oracle. You will need to sign up for an account and get an API key for access.
|
||||
|
||||
`$PAGERDUTY_EVENT_KEY` is an optional environment variable to help you manage your cluster. You may wish to ignore this variable if you are comfortable with your own monitoring solutions
|
||||
|
||||
- [Pagerduty - Generating API Keys](https://support.pagerduty.com/docs/generating-api-keys#section-events-api-keys)
|
||||
|
|
@ -0,0 +1,284 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Requirements
|
||||
---
|
||||
|
||||
# Background
|
||||
|
||||
A Switchboard oracle is a Node.js container that sits between the Solana blockchain and the internet and waits for update requests from its assigned oracle queue.
|
||||
|
||||
You can find the latest Switchboard oracle image on [DockerHub](https://hub.docker.com/r/switchboardlabs/node/tags).
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
A Switchboard oracle should be hosted in a highly available environment with some level of redundancy and fail over to prevent outages, although oracles are not deducted for being offline.
|
||||
|
||||
Currently the Switchboard oracle is a single threaded Node.js application with no strict hardware requirements. At the very minimum a node should have:
|
||||
|
||||
- 4gb RAM
|
||||
- 3.0 Ghz CPU
|
||||
- 100+ Mbps connection
|
||||
|
||||
## RPC Endpoint
|
||||
|
||||
A Switchboard oracle should have a reliable RPC endpoint with no rate limiting in order to respond in a timely manner. RPC providers will need to have `--full-rpc-api` enabled in their validator config, along with the ability to support fetching 100 program accounts in a single getProgramAccounts request.
|
||||
|
||||
Switchboard recommendeds the following RPC providers:
|
||||
|
||||
- RPC Pool
|
||||
- GenesysGo
|
||||
- Syndica
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash env title=".env"
|
||||
# Solana Config
|
||||
CLUSTER=""
|
||||
RPC_URL=""
|
||||
WS_URL=""
|
||||
BACKUP_MAINNET_RPC=""
|
||||
# Oracle Config
|
||||
ORACLE_KEY=""
|
||||
HEARTBEAT_INTERVAL=15
|
||||
GCP_CONFIG_BUCKET=""
|
||||
# Keypair Config
|
||||
PAYER_SECRET_PATH=""
|
||||
PAYER_SECRETS=""
|
||||
GOOGLE_PAYER_SECRET_PATH=""
|
||||
# Monitoring Config
|
||||
METRICS_EXPORTER
|
||||
PAGERDUTY_EVENT_KEY=""
|
||||
VERBOSE=1
|
||||
```
|
||||
|
||||
### Solana Config
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Env Variable</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>CLUSTER</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - String (devnet / mainnet-beta)
|
||||
<br />
|
||||
<b>Description</b> - Solana cluster you will be running an oracle on
|
||||
(mainnet-beta/devnet)
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>RPC_URL</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - URL
|
||||
<br />
|
||||
<b>Description</b> - Solana RPC URL that must be capable of supporting
|
||||
websockets. The default RPC pools should be avoided at all cost as you
|
||||
will quickly hit the rate limits and risk being slashed
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WS_URL</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - URL
|
||||
<br />
|
||||
<b>Default</b> - RPC_URL
|
||||
<br />
|
||||
<b>Description</b> - Websocket URL to connect to a Solana RPC server. If
|
||||
not provided, oracle will fallback to RPC_URL
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BACKUP_MAINNET_RPC</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - URL
|
||||
<br />
|
||||
<b>Default</b> - https://api.mainnet-beta.solana.com
|
||||
<br />
|
||||
<b>Description</b> - Backup RPC URL in case of network congestion
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### Oracle Config
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Env Variable</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>ORACLE_KEY</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Required</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Public Key
|
||||
<br />
|
||||
<b>Description</b> - Public key of the oracle account that has been
|
||||
granted permissions to use an oracle queue <br />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>HEARTBEAT_INTERVAL</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Number (seconds)
|
||||
<br />
|
||||
<b>Default</b> - 30
|
||||
<br />
|
||||
<b>Description</b> - Seconds between oracle heartbeats. Queues have
|
||||
different oracle heartbeat requirements. Recommended value is 15
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GCP_CONFIG_BUCKET</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - GCP Resource Path
|
||||
<br />
|
||||
<b>Default</b> - Looks for configs.json in the current working
|
||||
directory. If not found, no config is loaded.
|
||||
<br />
|
||||
<b>Description</b> - Contains API keys for private API endpoints
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### Keypair Config
|
||||
|
||||
You must provide one of the following environment variables, which is the same keypair that is the authority for the given `$ORACLE_KEY` and will pay for any on-chain transactions.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Env Variable</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>PAYER_SECRET_PATH</td>
|
||||
<td>
|
||||
<b>Type</b> - Filesystem Path
|
||||
<br />
|
||||
<b>Description</b> - Local filesystem path to keypair file that will pay
|
||||
for on-chain transactions and is the authority for the oracle
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>PAYER_SECRETS</td>
|
||||
<td>
|
||||
<b>Type</b> - Docker Secret
|
||||
<br />
|
||||
<b>Description</b> - Docker Secret path to keypair file that will pay
|
||||
for on-chain transactions and is the authority for the oracle
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>GOOGLE_PAYER_SECRET_PATH</td>
|
||||
<td>
|
||||
<b>Type</b> - GCP Resource Path
|
||||
<br />
|
||||
<b>Description</b> - Google cloud resource to manage your keypair
|
||||
securely.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### Monitoring Config
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Env Variable</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>METRICS_EXPORTER</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - prometheus / gcp / opentelemetry-collector*
|
||||
<br />
|
||||
<b>Default</b> - prometheus
|
||||
<br />
|
||||
<b>Description</b> - Dictates which metric suite to aggregate resource
|
||||
metrics, as defined in:
|
||||
<br />
|
||||
<a href="./service/monitoring">Oracle - Monitoring</a>
|
||||
<br />
|
||||
*opentelemetry-collector only supports the default endpoint
|
||||
localhost:55681/v1/metric
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>PAGERDUTY_EVENT_KEY</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - String
|
||||
<br />
|
||||
<b>Default</b> - Paging disabled
|
||||
<br />
|
||||
<b>Description</b> - Token provided by pagerduty for sending pages about
|
||||
various alerts.
|
||||
<br />
|
||||
<a href="./service/monitoring#alerts">Oracle - Alerts</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>VERBOSE</td>
|
||||
<td>
|
||||
<b>
|
||||
<u>Optional</u>
|
||||
</b>
|
||||
<br />
|
||||
<b>Type</b> - Flag (0 or 1)
|
||||
<br />
|
||||
<b>Default</b> - 0, normal logging
|
||||
<br />
|
||||
<b>Description</b> - Set to 1 to increase the level of logging
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
@ -1,24 +1,24 @@
|
|||
---
|
||||
sidebar_position: 5
|
||||
id: program
|
||||
slug: /program
|
||||
title: Program
|
||||
---
|
||||
|
||||
import PublicKeyButton from "/src/components/PublicKeyButton";
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import ProgramStateAccountData from "/idl/accounts/SbState.md";
|
||||
import Link from "@docusaurus/Link";
|
||||
import ProgramStateAccountData from "/idl/accounts/SbState.md";
|
||||
|
||||
## Program State
|
||||
# Program
|
||||
|
||||
## Program State Account
|
||||
|
||||
<Grid container spacing={3} justifyContent="space-around">
|
||||
<Grid item md={6}>
|
||||
<Grid item md={6} sm={12}>
|
||||
<br />
|
||||
<Typography>
|
||||
The program state account governs the Switchboard V2 program and controls the
|
||||
token mint used throughout for oracle rewards, aggregator leases, and
|
||||
other incentives.
|
||||
The Program State Account is the top level account that is used to connect
|
||||
independent oracle queues.
|
||||
</Typography>
|
||||
<br />
|
||||
<Typography>
|
||||
|
|
@ -27,115 +27,24 @@ import Link from "@docusaurus/Link";
|
|||
model.
|
||||
</Typography>
|
||||
<br />
|
||||
|
||||
### 📦SbState
|
||||
|
||||
<ProgramStateAccountData />
|
||||
|
||||
{/* <Typography>
|
||||
Oracle queue's support:
|
||||
<ul>
|
||||
<li>
|
||||
<b>Data Feeds</b>
|
||||
</li>
|
||||
<li>
|
||||
<b>Randomness</b>
|
||||
</li>
|
||||
<li>
|
||||
<b>Buffer Relayers</b>
|
||||
</li>
|
||||
</ul>
|
||||
</Typography> */}
|
||||
</Grid>
|
||||
<Grid item md={5}>
|
||||
<Grid item md={5} sm={12}>
|
||||
<MarkdownImage img="/img/L0_Architecture.png" />
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
## Mainnet-Beta
|
||||
|
||||
Below is a list of public keys used in the Switchboard V2 mainnet deployment.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Account</th>
|
||||
<th>Public Key</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Program ID</b>
|
||||
</td>
|
||||
<td>
|
||||
<PublicKeyButton publicKey="SW1TCH7qEPTdLsDHRgPuMQjbQxKdH2aBStViMFnt64f" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissionless Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="5JYwqvKkqp35w8Nq3ba4z1WYUeJQ1rB36V8XvaGp6zn1" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="BKtF8yyQsj3Ft6jb2nkfpEKzARZVdGgdEPs6mFmZNmbA" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissioned Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="3HBb2DQqDfuMdzWxNk1Eo9RTMkFYmuEAd32RiLKn9pAn" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GdNVLWzcE6h9SPuSbmu69YzxAj8enim9t6mjzuqTXgLd" />
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
## Devnet
|
||||
|
||||
Below is a list of public keys used in the Switchboard V2 devnet deployment.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Account</th>
|
||||
<th>Public Key</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Program ID</b>
|
||||
</td>
|
||||
<td>
|
||||
<PublicKeyButton publicKey="2TfB33aLaneQb5TNVwyDz3jSZXS6jdW2ARw1Dgf84XCG" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissionless Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="F8ce7MsckeZAbAGmxjJNetxYXQa9mKr9nnrC3qKubyYy" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GN9jjCy2THzZxhYqZETmPM3my8vg4R5JyNkgULddUMa5" />
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<b>Permissioned Queue</b>
|
||||
</td>
|
||||
<td>
|
||||
<b>Queue</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GhYg3R1V6DmJbwuc57qZeoYG6gUuvCotUF1zU3WCj98U" />
|
||||
<br />
|
||||
<b>Crank</b>
|
||||
<br />
|
||||
<PublicKeyButton publicKey="GdNVLWzcE6h9SPuSbmu69YzxAj8enim9t6mjzuqTXgLd" />
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<ProgramStateAccountData />
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Oracle Queue",
|
||||
"position": 10,
|
||||
"collapsible": true
|
||||
}
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
import { Box, Typography, Grid } from "@mui/material";
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import SwitchboardPermission from "/idl/types/SwitchboardPermission.md";
|
||||
|
||||
# Oracle Queue Architecture
|
||||
|
||||
An oracle queue allocates and protects a set of oracles, which act as a resource pool for on-chain programs to utilize. Oracle queues currently support fulfilling update request for the following:
|
||||
|
||||
| Resource Type | Description |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Data Feeds** | Utilize a batch of oracles to resolve a data point from a variety of source and determine the final result as the median of oracle responses <br />_Can be a price feed, sport result, or any data point found on the internet_ |
|
||||
| **Randomness** | Utilize an oracle to publish and verify a Verifiable Randomness Function on-chain.<br />_Can be used for fair NFT launches, decentralized lottery, or any random assignment_ |
|
||||
| **Buffer Relayer** | Utilize an oracle to relay and publish a buffer on-chain<br />_Can be used by programs needing a way to quickly source data on-chain that may not need as many security guarantees as a price feed _ |
|
||||
|
||||
## Configuration
|
||||
|
||||
<Grid container spacing={2}>
|
||||
<Grid item md={4} sm={12}>
|
||||
<ul>
|
||||
<li>
|
||||
<b>Oracle Queue: </b>Contains the Oracle Queue's configuration
|
||||
parameters that influence its security model.
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<b>Oracle Queue Buffer: </b>Stores the current list of oracles actively
|
||||
heartbeating on-chain.
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<b>Oracle: </b>Off-chain resource used by a queue to fulfill update
|
||||
request.
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<b>Crank: </b>Optional, Crank Account that permits data feeds to join
|
||||
and request periodic updates.
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<b>Crank Buffer: </b>Stores the list of data feeds on a crank along with
|
||||
their next allowed update time.
|
||||
</li>
|
||||
</ul>
|
||||
</Grid>
|
||||
<Grid item md={8} sm={12}>
|
||||
<MarkdownImage
|
||||
img="/img/queue/Oracle_Queue_Accounts.jpg"
|
||||
sx={{
|
||||
display: "flex",
|
||||
}}
|
||||
/>
|
||||
</Grid>
|
||||
</Grid>
|
||||
|
||||
<hr />
|
||||
|
||||
:::tip
|
||||
|
||||
See [/idl/accounts/OracleQueueAccountData](/idl/accounts/OracleQueueAccountData) for the full list of an OracleQueueAccount's configuration parameters.
|
||||
|
||||
:::
|
||||
|
||||
## Oracle Queue
|
||||
|
||||
When creating a queue, an OracleQueueBuffer account must also be initialized with a size of 8 Bytes + (32 Bytes × `queue.maxSize`), where `queue.maxSize` is the maximum number of oracles the queue can support. The OracleQueueBuffer account `queue.dataBuffer` stores a list of oracle public keys in a round robin fashion, using `queue.currIdx` to track its position on the queue for allocating resource update request. Once a buffer is full, oracles must be removed before new oracles can join the network. An oracle can be assigned to many update request simultaneously but must continuously heartbeat on-chain to signal readiness.
|
||||
|
||||
An oracle with **PermitOracleHeartbeat** permissions _MUST_ periodically heartbeat on the queue to signal readiness, which adds the oracle to the queue and allows it to be assigned resource update requests. Oracle positions are periodically swapped in the OracleQueueBuffer account to mitigate oracles being assigned the same update requests on each iteration of the queue.
|
||||
|
||||
The queue uses `queue.gcIdx` to track its garbage collection index. When an oracle heartbeats on-chain, it passes the oracle account at index `queue.gcIdx`. If the oracle account has failed to heartbeat before `queue.oracleTimeout`, it is removed from the queue until its next successful heartbeat and will no longer be assigned resource update requests.
|
||||
|
||||
## Access Control
|
||||
|
||||
Oracle queue resources, such as oracles, aggregators, VRF accounts, or buffer relayer accounts, _MUST_ have an associated [PermissionAccount](/idl/accounts/PermissionAccountData) initialized before interacting with a queue. Permissions are granted by `queue.authority`, which could be a DAO controlled account to allow network participants to vote on new entrants.
|
||||
|
||||
Oracles _MUST_ have **PermitOracleHeartbeat** permissions before heartbeating on a queue. This is to prevent a malicous actor from spinning up a plethora of oracles until it obtains the super majority, at which point it could misreport data feed results and cause honest oracles to be slashed.
|
||||
|
||||
See the table below for the minimum required permissions for a resource based on the queues settings:
|
||||
|
||||
| Queue Setting | False | True |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| `unpermissionedFeedsEnabled` | Aggregators & Buffer Relayers _MUST_ have **PermitOracleQueueUsage** permissions before requesting an update | Aggregators & Buffer Relayers require no explicit permissions before requesting an update |
|
||||
| `unpermissionedVrfEnabled` | VRF Accounts _MUST_ have **PermitVrfRequests** permissions before requesting an update | VRF Accounts require no explicit permissions before requesting an update |
|
||||
| `enableBufferRelayers` | Buffer Relayers are _NOT_ permitted to request updates | Buffer Relayers are permitted to request updates |
|
||||
|
||||
<!--
|
||||
TODO:
|
||||
- consecutiveFeedFailureLimit
|
||||
- consecutiveOracleFailureLimit
|
||||
- feedProbationPeriod
|
||||
-->
|
||||
|
||||
## Crank
|
||||
|
||||
A queue can choose to create one or many cranks. A crank is a scheduling mechanism that allows data feeds to request periodic updates. A crank can be turned by anyone, and if successful, the crank turner will be rewarded for jump starting the system.
|
||||
|
||||
A data feed is only permitted to join a crank if it has sufficient permissions (as detailed above) and the crank has available capacity. Data feeds on a crank are ordered by their next available update time with some level of jitter, providing a maximum update interval of 2 × a data feed's `aggregator.minUpdateDelaySeconds`. This is to mitigate oracles being assigned to the same aggregator update request, making a feed vulnerable to a malicious oracle.
|
||||
|
||||
## Economic Security
|
||||
|
||||
An oracle queue uses economic incentives to entice oracles to act honestly, which dictate a queue's security model.
|
||||
|
||||
### Stake
|
||||
|
||||
The queue's `queue.minStake` is the number of tokens required by an oracle to heartbeat on a queue. If an oracle's staking wallet falls below the minStake requirement, it is removed from the queue.
|
||||
|
||||
DeFi protocols with a significant Total Value Locked (TVL) should require oracles with a higher minimum stake to fulfill their update request. Oracles with a higher degree of _skin-in-the-game_ have a greater incentive to respond honestly.
|
||||
|
||||
### Reward
|
||||
|
||||
The queue's specified `queue.reward` is the number of tokens an oracle or crank turner receives for successfully completing an on-chain action. For a crank turner this is turning the crank and invoking a data feed update. For an oracle this is responding to an update request within the reliable margin from the accepted result.
|
||||
|
||||
Queues should reward oracles enough such that the economic incentive over the lifecycle of the feed exceeds the opportunity cost to attack a protocol consuming the feed.
|
||||
|
||||
### Slashing
|
||||
|
||||
A queue may set `queue.slashingEnabled` to true in order to dissuade oracles from responding to update request outside a set margin of error.
|
||||
|
||||
A queue's `queue.varianceToleranceMultiplier` determines how many standard deviations an oracle must respond within before being slashed and forfeiting a portion of their stake. [Defaults to 2 std deviations]
|
||||
|
||||
DeFi protocols with a significant TVL should require their feeds to be on a queue with slashing enabled.
|
||||
|
||||
## Governance
|
||||
|
||||
An oracle queue can be governed by its network participants to control the various queue configuration parameters, such as:
|
||||
|
||||
- `queue.minStake` - require a higher up-front cost for oracles to entice honest behavior
|
||||
- `queue.reward` - control the oracle reward payout for successfully fulfilling update request
|
||||
- `queue.slashingEnabled` - to disincentivize malcious oracle behavior
|
||||
- Permit new oracles to join the network
|
||||
|
||||
## More Information
|
||||
|
||||
- [/idl/accounts/OracleQueueAccountData](/idl/accounts/OracleQueueAccountData)
|
||||
- [/idl/accounts/OracleQueueBuffer](/idl/accounts/OracleQueueBuffer)
|
||||
|
|
@ -0,0 +1,375 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
title: Private Queues
|
||||
---
|
||||
|
||||
A private queue is any Oracle Queue not controlled by the Switchboard DAO.
|
||||
|
||||
Switchboard is architected to route off-chain data to an on-chain account. A publisher is responsible for building the job definition, which defines the task(s) the oracles must perform to fetch and transform external data. Sometimes a publisher may wish to bring private data on-chain using an API key which poses a set of challenges. In order for the oracle to retrieve the data, they need access to the publisher's API key. Blockchains are public so there is no easy way to conceal the API key on-chain.
|
||||
|
||||
Switchboard provides the ability to create your own queue with your own set of oracles, allowing the oracles access to your API key so they can resolve the private endpoints.
|
||||
|
||||
## Variable Expansion
|
||||
|
||||
Oracles can be provided a `configs.json` file to store various configurations needed to execute job definitions. If an oracle encounters a job definition with a variable, it will parse the `configs.json` and embed the value in the job definition.
|
||||
|
||||
Oracles can embed API Keys on a per job basis by specifying the jobAccount public key or by using an asterik character to use the variable for multiple job definitions. **_Wildcard variables should use a unique name to prevent incorrect substitution._**
|
||||
|
||||
```json title="configs.json"
|
||||
{
|
||||
"jobVariables": {
|
||||
// Pubkey of the Job account for which this variable expansion applies
|
||||
"HtB62K71H49RJbATYpmB6UCMBXLK6G3Q5JtGveTMR8Mt": {
|
||||
"VARIABLE_NAME": "abc123"
|
||||
},
|
||||
// Global variable expansion that applies to any Job account. SEE CAUTION BELOW
|
||||
"*": {
|
||||
"GLOBAL_VARIABLE_NAME": "abc123"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
Private queue's should **_ALWAYS_** have `unpermissionedFeedsEnabled` set to false. Allowing unpermitted feeds could result in a malicous actor creating a job definition that leaks your sensitive API keys.
|
||||
|
||||
:::
|
||||
|
||||
## Example
|
||||
|
||||
We'll be using [commodities-api](https://www.commodities-api.com) to resolve our data for this example. You will need to signup for an account to get a `COMMODITIES_API_KEY`.
|
||||
|
||||
### Create a Queue
|
||||
|
||||
First, we will need to create our own queue. The following command will create a queue with a single oracle and crank.
|
||||
|
||||
```bash
|
||||
sbv2 queue:create \
|
||||
--name "Private Queue" \
|
||||
--keypair ../payer-keypair.json \
|
||||
--authority ../payer-keypair.json \
|
||||
--numOracles 1 \
|
||||
--reward 0 \
|
||||
--outputFile "Private_Queue.json"
|
||||
```
|
||||
|
||||
### Start Oracle
|
||||
|
||||
Create a docker-compose file, replacing `ORACLE_KEY`, `RPC_URL`, and `PAYER_KEYPAIR` with the appropriate values.
|
||||
|
||||
```yml title="docker-compose.yml"
|
||||
version: "3.3"
|
||||
services:
|
||||
oracle:
|
||||
image: "switchboardlabs/node:dev-v2-5-3-22"
|
||||
network_mode: host
|
||||
restart: always
|
||||
secrets:
|
||||
- PAYER_SECRETS
|
||||
environment:
|
||||
- LIVE=1
|
||||
- CLUSTER=devnet
|
||||
- HEARTBEAT_INTERVAL=30 # Seconds
|
||||
- ORACLE_KEY=${ORACLE_KEY}
|
||||
- RPC_URL=${RPC_URL}
|
||||
volumes:
|
||||
- ./configs.json:/configs.json
|
||||
secrets:
|
||||
PAYER_SECRETS:
|
||||
file: ${PAYER_KEYPAIR}
|
||||
```
|
||||
|
||||
We need to embed the commodities-api key in our oracle's configs.json file.
|
||||
|
||||
```json title="configs.json"
|
||||
{
|
||||
"jobVariables": {
|
||||
// Pubkey of the OracleJob account for which this variable expansion applies or *.
|
||||
"*": {
|
||||
"COMMODITIES_API_KEY": "YOUR_API_KEY_HERE"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Start the oracle
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
### Create WHEAT Aggregator
|
||||
|
||||
Looking at their docs, we'll need to fetch data from the following endpoint and take the inverse. The aggregator definition will look like this:
|
||||
|
||||
```json title="Wheat.json"
|
||||
{
|
||||
"name": "WHEAT",
|
||||
"metadata": "",
|
||||
"oracleRequestBatchSize": 1,
|
||||
"minOracleResults": 1,
|
||||
"minJobResults": 1,
|
||||
"minUpdateDelaySeconds": 900,
|
||||
"jobs": [
|
||||
{
|
||||
"name": "commodities-api WHEAT",
|
||||
"tasks": [
|
||||
{
|
||||
"httpTask": {
|
||||
"url": "https://www.commodities-api.com/api/latest?access_key=${COMMODITIES_API_KEY}&base=USD&symbols=WHEAT"
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonParseTask": {
|
||||
"path": "$.data.rates.WHEAT"
|
||||
}
|
||||
},
|
||||
{
|
||||
"powTask": {
|
||||
"scalar": -1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Now we need to create an aggregator and add this job definition to it.
|
||||
|
||||
```bash
|
||||
sbv2 aggregator:create:json wheat.json \
|
||||
--keypair ../payer-keypair.json \
|
||||
--queueKey QUEUE_KEY_OUTPUTTED_ABOVE \
|
||||
--outputFile Wheat_Aggregator.json
|
||||
```
|
||||
|
||||
Now we can request an update from our running oracle
|
||||
|
||||
```bash
|
||||
sbv2 aggregator:update AGGREGATORKEY --keypair PAYERKEYPAIR
|
||||
```
|
||||
|
||||
We should see the oracle respond to the job and update the on-chain value
|
||||
|
||||
```bash
|
||||
sbv2 aggregator:print AGGREGATORKEY
|
||||
```
|
||||
|
||||
### Other Aggregator Definitions
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
|
||||
#### Crude
|
||||
|
||||
</summary>
|
||||
|
||||
```json title="Crude.json"
|
||||
{
|
||||
"name": "Crude WTIOIL",
|
||||
"metadata": "",
|
||||
"oracleRequestBatchSize": 1,
|
||||
"minOracleResults": 1,
|
||||
"minJobResults": 1,
|
||||
"minUpdateDelaySeconds": 900,
|
||||
"jobs": [
|
||||
{
|
||||
"name": "commodities-api WTIOIL",
|
||||
"tasks": [
|
||||
{
|
||||
"httpTask": {
|
||||
"url": "https://www.commodities-api.com/api/latest?access_key=${COMMODITIES_API_KEY}&base=USD&symbols=WTIOIL"
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonParseTask": {
|
||||
"path": "$.data.rates.WTIOIL"
|
||||
}
|
||||
},
|
||||
{
|
||||
"powTask": {
|
||||
"scalar": -1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
|
||||
#### Gold
|
||||
|
||||
</summary>
|
||||
|
||||
```json title="Gold.json"
|
||||
{
|
||||
"name": "Gold",
|
||||
"metadata": "",
|
||||
"oracleRequestBatchSize": 1,
|
||||
"minOracleResults": 1,
|
||||
"minJobResults": 1,
|
||||
"minUpdateDelaySeconds": 900,
|
||||
"jobs": [
|
||||
{
|
||||
"name": "commodities-api XAU",
|
||||
"tasks": [
|
||||
{
|
||||
"httpTask": {
|
||||
"url": "https://www.commodities-api.com/api/latest?access_key=${COMMODITIES_API_KEY}&base=USD&symbols=XAU"
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonParseTask": {
|
||||
"path": "$.data.rates.XAU"
|
||||
}
|
||||
},
|
||||
{
|
||||
"powTask": {
|
||||
"scalar": -1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
|
||||
#### Silver
|
||||
|
||||
</summary>
|
||||
|
||||
```json title="Silver.json"
|
||||
{
|
||||
"name": "Silver",
|
||||
"metadata": "",
|
||||
"oracleRequestBatchSize": 1,
|
||||
"minOracleResults": 1,
|
||||
"minJobResults": 1,
|
||||
"minUpdateDelaySeconds": 900,
|
||||
"jobs": [
|
||||
{
|
||||
"name": "commodities-api XAG",
|
||||
"tasks": [
|
||||
{
|
||||
"httpTask": {
|
||||
"url": "https://www.commodities-api.com/api/latest?access_key=${COMMODITIES_API_KEY}&base=USD&symbols=XAG"
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonParseTask": {
|
||||
"path": "$.data.rates.XAG"
|
||||
}
|
||||
},
|
||||
{
|
||||
"powTask": {
|
||||
"scalar": -1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
|
||||
#### Nickel
|
||||
|
||||
</summary>
|
||||
|
||||
```json title="Nickel.json"
|
||||
{
|
||||
"name": "Nickel",
|
||||
"metadata": "",
|
||||
"oracleRequestBatchSize": 1,
|
||||
"minOracleResults": 1,
|
||||
"minJobResults": 1,
|
||||
"minUpdateDelaySeconds": 900,
|
||||
"jobs": [
|
||||
{
|
||||
"name": "commodities-api NI",
|
||||
"tasks": [
|
||||
{
|
||||
"httpTask": {
|
||||
"url": "https://www.commodities-api.com/api/latest?access_key=${COMMODITIES_API_KEY}&base=USD&symbols=NI"
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonParseTask": {
|
||||
"path": "$.data.rates.NI"
|
||||
}
|
||||
},
|
||||
{
|
||||
"powTask": {
|
||||
"scalar": -1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
|
||||
#### Coffee
|
||||
|
||||
</summary>
|
||||
|
||||
```json title="Coffee.json"
|
||||
{
|
||||
"name": "Coffee",
|
||||
"metadata": "",
|
||||
"oracleRequestBatchSize": 1,
|
||||
"minOracleResults": 1,
|
||||
"minJobResults": 1,
|
||||
"minUpdateDelaySeconds": 900,
|
||||
"jobs": [
|
||||
{
|
||||
"name": "commodities-api COFFEE",
|
||||
"tasks": [
|
||||
{
|
||||
"httpTask": {
|
||||
"url": "https://www.commodities-api.com/api/latest?access_key=${COMMODITIES_API_KEY}&base=USD&symbols=COFFEE"
|
||||
}
|
||||
},
|
||||
{
|
||||
"jsonParseTask": {
|
||||
"path": "$.data.rates.COFFEE"
|
||||
}
|
||||
},
|
||||
{
|
||||
"powTask": {
|
||||
"scalar": -1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"label": "Randomness",
|
||||
"position": 40,
|
||||
"collapsible": true
|
||||
}
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
slug: .
|
||||
title: Architecture
|
||||
description: Learn how to use Switchboard's Verifiable Random Functions
|
||||
keywords: [Switchboard, Solana, VRF, randomness, verifiable, proof]
|
||||
---
|
||||
|
||||
# Randomness Architecture
|
||||
|
||||
import MarkdownImage from "/src/components/MarkdownImage";
|
||||
import RandomnessInstructions from "/idl/_randomness_instructions.mdx";
|
||||
import {
|
||||
Typography,
|
||||
IconButton,
|
||||
Box,
|
||||
CardActionArea,
|
||||
Card,
|
||||
CardContent,
|
||||
} from "@mui/material";
|
||||
import Link from "@docusaurus/Link";
|
||||
import GitHubIcon from "@mui/icons-material/GitHub";
|
||||
import VrfAccountData from "/idl/accounts/VrfAccountData.md";
|
||||
import VrfInit from "/idl/instructions/vrfInit.md";
|
||||
import VrfProve from "/idl/instructions/vrfProve.md";
|
||||
import VrfVerify from "/idl/instructions/vrfVerify.md";
|
||||
import VrfRequestRandomness from "/idl/instructions/vrfRequestRandomness.md";
|
||||
|
||||
import CallbackZC from "/idl/types/CallbackZC.md";
|
||||
|
||||
:::caution
|
||||
|
||||
While Switchboard V2's oracle network is fully audited, the VRF implementation is currently unaudited software. Please use at your own risk.
|
||||
|
||||
:::
|
||||
|
||||
A VRF account is an on-chain account that holds the latest VRF value, as well as its owners specified callback function. When a VRF account owner requests a new randomness value, the oracle queue delegates the update request to an oracle based on its round robin ordering of oracles heartbeating on-chain. The oracle submits its VRF seed on-chain, then must submit 276 transactions to turn the state machine, which computes the proof. When the proof is computed and successfully validates the pseudo-random value, the oracle invokes the account owner’s callback instruction.
|
||||
|
||||
The VRF function return a **_u8[32]_** buffer that can be transmuted to most data types using the [bytemuck crate](https://crates.io/crates/bytemuck).
|
||||
|
||||
```rust
|
||||
let result_buffer: [u8; 32];
|
||||
// get result buffer from parsed VRF Account
|
||||
msg!("Result buffer is {:?}", result_buffer);
|
||||
let value: &[u128] = bytemuck::cast_slice(&result_buffer[..]);
|
||||
msg!("u128 buffer {:?}", value);
|
||||
let result = value[0] % max_result as u128;
|
||||
msg!("Current VRF Value [0 - {}) = {}!", max_result, result);
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
:::tip
|
||||
|
||||
See [/idl/accounts/VrfAccountData](/idl/accounts/VrfAccountData) for the full list of an AggregatorAccount's configuration parameters.
|
||||
|
||||
:::
|
||||
|
||||
## Callback
|
||||
|
||||
When creating a VRF Account, the VRF `authority` should specify a `callback` function that will be called by the oracle. VRF Accounts should ensure their `callback` function consumes less than ~160k compute units or it may fail to complete.
|
||||
|
||||
<CallbackZC />
|
||||
|
||||
## Reward Oracles
|
||||
|
||||
When a VRF Account requests a new random value from a queue, it transfers 0.1 wSOL to it's `escrow` wallet. An oracle receives 90% of the reward when it verifies the proof on-chain and the remaining 10% if the callback succeeds.
|
||||
|
||||
## Update Lifecycle
|
||||
|
||||
- `vrfRequestRandomness`
|
||||
- check `vrfStatus`
|
||||
- `tokenTransfer`
|
||||
- increment counter
|
||||
- set status to _StatusRequesting_
|
||||
- emit `VrfRequestEvent`
|
||||
- oracle fulfills VRF request
|
||||
- `vrfProve`
|
||||
- set status to _StatusVerifying_
|
||||
- `vrfVerify` x 277
|
||||
- set status to _StatusVerified_
|
||||
- 90% `tokenTransfer`
|
||||
- invoke VRF Callback
|
||||
- if success
|
||||
- 10% `tokenTransfer`
|
||||
- set status to _StatusCallbackSuccess_
|
||||
- if failure
|
||||
- set status to _StatusVerifyFailure_
|
||||
|
||||
## More Information
|
||||
|
||||
- [/idl/accounts/VrfAccountData](/idl/accounts/VrfAccountData)
|
||||
- [/developers/randomness](/developers/randomness)
|
||||
|
|
@ -1,6 +1,9 @@
|
|||
// @ts-check
|
||||
// Note: type annotations allow type checking and IDEs autocompletion
|
||||
|
||||
const math = require("remark-math");
|
||||
const katex = require("rehype-katex");
|
||||
|
||||
/** @type {import('@docusaurus/types').Config} */
|
||||
const config = {
|
||||
title: "Switchboard",
|
||||
|
|
@ -29,6 +32,8 @@ const config = {
|
|||
remarkPlugins: [
|
||||
[require("@docusaurus/remark-plugin-npm2yarn"), { sync: true }],
|
||||
],
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
// editUrl:
|
||||
// process.env.NODE_ENV === "production"
|
||||
// ? process.env.CI_PROJECT_URL + "/-/edit/main/"
|
||||
|
|
@ -48,6 +53,15 @@ const config = {
|
|||
}),
|
||||
],
|
||||
],
|
||||
stylesheets: [
|
||||
{
|
||||
href: "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css",
|
||||
type: "text/css",
|
||||
integrity:
|
||||
"sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM",
|
||||
crossorigin: "anonymous",
|
||||
},
|
||||
],
|
||||
plugins: [
|
||||
"my-loaders",
|
||||
[
|
||||
|
|
@ -115,24 +129,20 @@ const config = {
|
|||
label: "Docs",
|
||||
},
|
||||
{
|
||||
to: "idl/",
|
||||
to: "/idl/",
|
||||
position: "left",
|
||||
label: "IDL",
|
||||
// activeBaseRegex: "docs/(next|v8)",
|
||||
},
|
||||
{
|
||||
type: "dropdown",
|
||||
label: "Developers",
|
||||
label: "APIs",
|
||||
position: "left",
|
||||
to: "api",
|
||||
to: "/api/",
|
||||
items: [
|
||||
{
|
||||
label: "Overview",
|
||||
to: "api/",
|
||||
},
|
||||
{
|
||||
label: "Task Protobufs",
|
||||
to: "api/tasks",
|
||||
to: "/api/tasks",
|
||||
},
|
||||
{
|
||||
label: "Typescript",
|
||||
|
|
@ -152,7 +162,7 @@ const config = {
|
|||
},
|
||||
{
|
||||
label: "CLI",
|
||||
to: "api/cli",
|
||||
to: "/api/cli",
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
- [Accounts](/program/accounts/)
|
||||
- [AggregatorAccountData](/idl/accounts/AggregatorAccountData)
|
||||
- [BufferRelayerAccountData](/idl/accounts/BufferRelayerAccountData)
|
||||
- [CrankAccountData](/idl/accounts/CrankAccountData)
|
||||
- [JobAccountData](/idl/accounts/JobAccountData)
|
||||
- [LeaseAccountData](/idl/accounts/LeaseAccountData)
|
||||
|
|
@ -17,12 +18,16 @@
|
|||
- [aggregatorSaveResult](/idl/instructions/aggregatorSaveResult)
|
||||
- [aggregatorSetAuthority](/idl/instructions/aggregatorSetAuthority)
|
||||
- [aggregatorSetBatchSize](/idl/instructions/aggregatorSetBatchSize)
|
||||
- [aggregatorSetForceReportPeriod](/idl/instructions/aggregatorSetForceReportPeriod)
|
||||
- [aggregatorSetHistoryBuffer](/idl/instructions/aggregatorSetHistoryBuffer)
|
||||
- [aggregatorSetMinJobs](/idl/instructions/aggregatorSetMinJobs)
|
||||
- [aggregatorSetMinOracles](/idl/instructions/aggregatorSetMinOracles)
|
||||
- [aggregatorSetQueue](/idl/instructions/aggregatorSetQueue)
|
||||
- [aggregatorSetUpdateInterval](/idl/instructions/aggregatorSetUpdateInterval)
|
||||
- [aggregatorSetVarianceThreshold](/idl/instructions/aggregatorSetVarianceThreshold)
|
||||
- [bufferRelayerInit](/idl/instructions/bufferRelayerInit)
|
||||
- [bufferRelayerOpenRound](/idl/instructions/bufferRelayerOpenRound)
|
||||
- [bufferRelayerSaveResult](/idl/instructions/bufferRelayerSaveResult)
|
||||
- [crankInit](/idl/instructions/crankInit)
|
||||
- [crankPop](/idl/instructions/crankPop)
|
||||
- [crankPush](/idl/instructions/crankPush)
|
||||
|
|
@ -48,9 +53,11 @@
|
|||
- [vrfRequestRandomness](/idl/instructions/vrfRequestRandomness)
|
||||
- [vrfVerify](/idl/instructions/vrfVerify)
|
||||
- [Events](/program/events)
|
||||
- [AggregatorCrankEvictionEvent](/idl/events/AggregatorCrankEvictionEvent)
|
||||
- [AggregatorInitEvent](/idl/events/AggregatorInitEvent)
|
||||
- [AggregatorOpenRoundEvent](/idl/events/AggregatorOpenRoundEvent)
|
||||
- [AggregatorValueUpdateEvent](/idl/events/AggregatorValueUpdateEvent)
|
||||
- [BufferRelayerOpenRoundEvent](/idl/events/BufferRelayerOpenRoundEvent)
|
||||
- [CrankLeaseInsufficientFundsEvent](/idl/events/CrankLeaseInsufficientFundsEvent)
|
||||
- [CrankPopExpectedFailureEvent](/idl/events/CrankPopExpectedFailureEvent)
|
||||
- [FeedPermissionRevokedEvent](/idl/events/FeedPermissionRevokedEvent)
|
||||
|
|
@ -70,29 +77,13 @@
|
|||
- [Types](/program/types)
|
||||
- [AccountMetaBorsh](/idl/types/AccountMetaBorsh)
|
||||
- [AccountMetaZC](/idl/types/AccountMetaZC)
|
||||
- AggregatorAddJobParams
|
||||
- [AggregatorHistoryRow](/idl/types/AggregatorHistoryRow)
|
||||
- AggregatorInitParams
|
||||
- AggregatorLockParams
|
||||
- AggregatorOpenRoundParams
|
||||
- AggregatorRemoveJobParams
|
||||
- [AggregatorRound](/idl/types/AggregatorRound)
|
||||
- AggregatorSaveResultParams
|
||||
- AggregatorSetAuthorityParams
|
||||
- AggregatorSetBatchSizeParams
|
||||
- AggregatorSetHistoryBufferParams
|
||||
- AggregatorSetMinJobsParams
|
||||
- AggregatorSetMinOraclesParams
|
||||
- AggregatorSetQueueParams
|
||||
- AggregatorSetUpdateIntervalParams
|
||||
- AggregatorSetVarianceThresholdParams
|
||||
- [BorshDecimal](/idl/types/BorshDecimal)
|
||||
- [BufferRelayerRound](/idl/types/BufferRelayerRound)
|
||||
- [Callback](/idl/types/Callback)
|
||||
- [CallbackZC](/idl/types/CallbackZC)
|
||||
- [CompletedPointZC](/idl/types/CompletedPointZC)
|
||||
- CrankInitParams
|
||||
- CrankPopParams
|
||||
- CrankPushParams
|
||||
- [CrankRow](/idl/types/CrankRow)
|
||||
- [EcvrfIntermediate](/idl/types/EcvrfIntermediate)
|
||||
- [EcvrfProofZC](/idl/types/EcvrfProofZC)
|
||||
|
|
@ -100,38 +91,17 @@
|
|||
- [Error](/idl/types/Error)
|
||||
- [FieldElementZC](/idl/types/FieldElementZC)
|
||||
- [Hash](/idl/types/Hash)
|
||||
- JobInitParams
|
||||
- [Lanes](/idl/types/Lanes)
|
||||
- [Lanes](/idl/types/Lanes)
|
||||
- LeaseExtendParams
|
||||
- LeaseInitParams
|
||||
- LeaseSetAuthorityParams
|
||||
- LeaseWithdrawParams
|
||||
- OracleHeartbeatParams
|
||||
- OracleInitParams
|
||||
- [OracleMetrics](/idl/types/OracleMetrics)
|
||||
- OracleQueueInitParams
|
||||
- OracleQueueSetRewardsParams
|
||||
- OracleQueueVrfConfigParams
|
||||
- [OracleResponseType](/idl/types/OracleResponseType)
|
||||
- OracleWithdrawParams
|
||||
- PermissionInitParams
|
||||
- PermissionSetParams
|
||||
- ProgramConfigParams
|
||||
- ProgramInitParams
|
||||
- [ProjectivePointZC](/idl/types/ProjectivePointZC)
|
||||
- [Scalar](/idl/types/Scalar)
|
||||
- [Shuffle](/idl/types/Shuffle)
|
||||
- [Shuffle](/idl/types/Shuffle)
|
||||
- [SwitchboardDecimal](/idl/types/SwitchboardDecimal)
|
||||
- [SwitchboardPermission](/idl/types/SwitchboardPermission)
|
||||
- VaultTransferParams
|
||||
- [VrfBuilder](/idl/types/VrfBuilder)
|
||||
- VrfInitParams
|
||||
- VrfProveAndVerifyParams
|
||||
- VrfProveParams
|
||||
- VrfRequestRandomnessParams
|
||||
- [VrfRound](/idl/types/VrfRound)
|
||||
- [VrfStatus](/idl/types/VrfStatus)
|
||||
- VrfVerifyParams
|
||||
- [Errors](/program/errors)
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue