Check status:
```bash [bash]
docker compose --project-directory temp-network ps
```
View logs:
```bash [bash]
# View all logs
docker compose --project-directory temp-network logs -f
# View specific service logs
docker compose --project-directory temp-network logs -f anvil
docker compose --project-directory temp-network logs -f anvil-settlement
docker compose --project-directory temp-network logs -f deployer
docker compose --project-directory temp-network logs -f genesis-generator
docker compose --project-directory temp-network logs -f relay-sidecar-1
docker compose --project-directory temp-network logs -f sum-node-1
```
Stop the network:
```bash [bash]
docker compose --project-directory temp-network down
```
Clean up data:
```bash [bash]
docker compose --project-directory temp-network down -v
rm -rf temp-network
```
## Create Task
Submit a sum task to the network.
```bash [bash]
taskID=$(cast send --rpc-url http://127.0.0.1:8545 --json \
--private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
0x4826533B4897376654Bb4d4AD88B7faFD0C98528 \
"createTask(uint256,uint256)" 33 9 | jq -r '.logs[0].topics[1]')
```
This creates a task for the network, which later collects the required number of attestations and broadcasts the result to every supported destination chain.
## Verify Task Result
It is possible to verify result on the first chain:
```bash [bash]
result=$(cast call --rpc-url http://127.0.0.1:8545 \
0x4826533B4897376654Bb4d4AD88B7faFD0C98528 \
"responses(bytes32)" $taskID)
cast decode-abi --json "data()(uint48,uint256)" $result
```
It is also possible to verify result on the second chain:
```bash [bash]
result=$(cast call --rpc-url http://127.0.0.1:8546 \
0x5FC8d32690cc91D4c39d9d3abcBD16989F875707 \
"responses(bytes32)" $taskID)
cast decode-abi --json "data()(uint48,uint256)" $result
```
This prints the task result with the corresponding timestamp.
```bash [Expected output]
symbiotic-super-sum % result=$(cast call --rpc-url http://127.0.0.1:8545 \
0x4826533B4897376654Bb4d4AD88B7faFD0C98528 \
"responses(bytes32)" $taskID)
cast decode-abi --json "data()(uint48,uint256)" $result
[
1754052445,
42
]
```
## Build!
```
symbiotic-super-sum
├─ network-scripts
│ ├─ deploy.sh
│ ├─ genesis-generator.sh
│ ├─ sidecar-start.sh
│ └─ sum-node-start.sh
├─ off-chain
│ ├─ abis/
│ ├─ cmd/
│ │ ├─ benchmark/
│ │ └─ node/
│ │ └─ main.go
│ └─ internal/
│ ├─ contracts/
│ │ └─ sumTask.go
│ └─ utils/
├─ script
│ ├─ MyRelayDeploy.sol
│ ├─ mocks/
│ ├─ my-relay-deploy.toml
│ └─ utils/
├─ src
│ ├─ SumTask.sol
│ └─ symbiotic
│ ├─ Driver.sol
│ ├─ KeyRegistry.sol
│ ├─ Settlement.sol
│ └─ VotingPowers.sol
├─ generate_network.sh
├─ package.json
└─ …
```
## Prerequisites
Make sure to have all the tools listed below installed before you start.
1. **Git** ([Installation Guide](https://git-scm.com/downloads))
2. **Foundry** - Ethereum development toolchain ([Installation Guide](https://book.getfoundry.sh/getting-started/installation))
3. **Node.js** (v18 or later) and **npm** ([Installation Guide](https://nodejs.org/en/download/))
4. **Docker** ([Installation Guide](https://docs.docker.com/get-docker/))
5. **Go** (v1.21 or later) ([Installation Guide](https://golang.org/doc/install))
6. Python (v3.11 or later) ([Installation Guide](https://www.python.org/downloads/))
## **1. Deploy Symbiotic Core and Setup Your First Vault**
### **Deploy Symbiotic Core to your local chain**
Symbiotic Core comprises the foundational contracts that govern the Symbiotic ecosystem, offering a comprehensive suite for its administration and interaction. The repository provides pre-configured scripts to facilitate deployment to a local chain, as well as additional utilities designed to streamline ongoing workflows with the core contracts.
`SymbioticCoreInit.sol` is the integration script that spins up fresh factories, registries, vaults, and helper services, then exposes utilities for building test scenarios. `SymbioticCoreConstants.sol` is the address book library that returns the canonical contract set and supported collateral tokens for mainnet, Holešky, Sepolia, and Hoodi. `SymbioticCoreBindings.sol` contains the Foundry broadcast helpers used to create vaults, register operators/networks, manage opt-ins, and exercise slashing flows against those core contracts.
Core contracts can be deployed using `_initCore_SymbioticCore` function ([script details](https://github.com/symbioticfi/relay-contracts/blob/main/script/RelayDeploy.sol#L101)):
```solidity [@symbioticfi/relay-contracts/script/deploy/RelayDeploy.sol#101]
function getCore() public withoutBroadcast loadConfig returns (SymbioticCoreConstants.Core memory) {
if (!SymbioticCoreConstants.coreSupported()) {
if (config.get("vault_factory").data.length == 0) {
SymbioticCoreConstants.Core memory core = _initCore_SymbioticCore(false); // [!code focus]
```
The console output lists every deployed Symbiotic Core contract (vault factory, registries, opt-in services, etc.). Persist these addresses—you’ll feed them into the rest of the quickstart.
### **Deploy a vault**
Vaults are the delegation and restaking management layer of Symbiotic. They handle three crucial parts of the Symbiotic economy: accounting, delegation strategies and slashing processing
The vault is created during operator registration by VotingPowers contract ([see contract details](https://github.com/symbioticfi/relay-contracts/blob/main/src/modules/voting-power/extensions/logic/OpNetVaultAutoDeployLogic.sol#L289)).
```solidity [@symbioticfi/relay-contracts/src/modules/voting-power/extensions/logic/OpNetVaultAutoDeployLogic.sol#289]
function createVault(
uint64 version,
address owner,
bytes memory vaultParams,
uint64 delegatorIndex,
bytes memory delegatorParams,
bool withSlasher,
uint64 slasherIndex,
bytes memory slasherParams
) public returns (address, address, address) {
return IVaultConfigurator(IOpNetVaultAutoDeploy(address(this)).VAULT_CONFIGURATOR())
.create(
IVaultConfigurator.InitParams({
version: version,
owner: owner,
vaultParams: vaultParams,
delegatorIndex: delegatorIndex,
delegatorParams: delegatorParams,
withSlasher: withSlasher,
slasherIndex: slasherIndex,
slasherParams: slasherParams
})
);
}
```
For testnet or mainnet vaults you can skip this step and create one directly via the Vault Factory UI at [https://app.symbiotic.fi/create](https://app.symbiotic.fi/create)
## **2. Opt-Ins and Stake Allocation**
### **Required On-Chain Actions**
In Symbiotic, networks are represented through a network address (either an EOA or a contract) and a middleware contract. Deploy the network contract using the DeployNetworkBase script. During initialization, the network is also registered within NetworkRegistry ([script details](https://github.com/symbioticfi/symbiotic-super-sum/blob/5e7625c8fb16acdd30a7695050f2f7b5c8f44d32/script/MyRelayDeploy.sol#L101)).
```solidity [script/MyRelayDeploy.sol#101]
function getNetwork() public withoutBroadcast loadConfig returns (address) {
if (config.get("network").data.length == 0) {
address[] memory proposersAndExecutors = new address[](1);
proposersAndExecutors[0] = getDeployerAddress();
SymbioticCoreConstants.Core memory core = getCore();
vm.broadcast();
address networkImpl =
address(new Network(address(core.networkRegistry), address(core.networkMiddlewareService)));
config.set(
"network",
_deployContract(
NETWORK_SALT,
networkImpl,
abi.encodeCall(
INetwork.initialize,
(INetwork.NetworkInitParams({
globalMinDelay: 0,
delayParams: new INetwork.DelayParams[](0),
proposers: proposersAndExecutors,
executors: proposersAndExecutors,
name: "Example Network",
metadataURI: "https://example.network",
defaultAdminRoleHolder: getDeployerAddress(),
nameUpdateRoleHolder: getDeployerAddress(),
metadataURIUpdateRoleHolder: getDeployerAddress()
}))
),
getDeployerAddress(),
false
)
);
}
return config.get("network").toAddress();
}
```
The OperatorRegistry maintains a record of all registered operators.
Operators must register here before they can participate in network activities or receive stake allocations ([script details](https://github.com/symbioticfi/symbiotic-super-sum/blob/5e7625c8fb16acdd30a7695050f2f7b5c8f44d32/script/MyRelayDeploy.sol#L371)).
```solidity [script/MyRelayDeploy.sol#371]
getCore().operatorRegistry.registerOperator();
```
Opt-ins are crucial for establishing connections between different entities in the Symbiotic ecosystem. Through the OperatorNetworkOptInService, operators can opt into networks they wish to work with. This signifies their willingness to provide services to these networks.
Operators use the OperatorVaultOptInService to opt into specific vaults. This allows them to receive stake allocations from these vaults ([script details](https://github.com/symbioticfi/symbiotic-super-sum/blob/5e7625c8fb16acdd30a7695050f2f7b5c8f44d32/script/MyRelayDeploy.sol#L372)).
```solidity [script/MyRelayDeploy.sol#372]
getCore().operatorNetworkOptInService.optIn(address(getNetwork())); // [!code focus]
votingPowers.registerOperator();
IVault vault = IVault(votingPowers.getAutoDeployedVault(operator.addr));
getCore().operatorVaultOptInService.optIn(address(vault)); // [!code focus]
```
Network opt into desired vaults by calling `setMaxNetworkLimit()` on each vault’s delegator contract ([script details](https://github.com/symbioticfi/relay-contracts/blob/70dc1ae21bdebf08e2f01246a42e31aee6a1c39d/src/modules/voting-power/extensions/OpNetVaultAutoDeploy.sol#L69)).
```solidity [@symbioticfi/relay-contracts/src/modules/voting-power/extensions/OpNetVaultAutoDeploy.sol#69]
(address vault, address delegator,) = OpNetVaultAutoDeployLogic.createVault(operator);
_registerOperatorVault(operator, vault);
if (isSetMaxNetworkLimitHookEnabled()) {
ISetMaxNetworkLimitHook(NETWORK())
.setMaxNetworkLimit(delegator, SUBNETWORK_IDENTIFIER(), type(uint256).max); // [!code focus]
}
```
## **3. Network Middleware**
### **Overview**
Relay Contracts use a modular architecture with five core modules that together manage validator networks, ensuring flexibility and clear separation of concerns.
* **Network** integrates Relay Contracts into the Symbiotic ecosystem, providing verifiable delays, standardized lifecycle management, and serving as the network address across the system.
* **VotingPowerProvider** connects to Symbiotic Core to calculate operator and vault voting power based on stake and rules. It supports extensible strategies for onboarding, slashing, rewards, and key management.
* **KeyRegistry** manages and verifies operators’ cryptographic keys (BLS BN254, ECDSA SECP256K1), supporting registration, verification, and lifecycle management.
* **ValSetDriver** derives and maintains validator sets for off-chain components, managing epoch transitions and linking on-chain voting power with off-chain consensus.
* **Settlement** commits compressed validator sets each epoch, verifies signatures, and supports multi-chain deployments for cross-chain validation.
### **Deployment tooling**
The deployment tooling is in the `@symbioticfi/relay-contracts/script/deploy/` folder. It consists of `RelayDeploy.sol` Foundry script template and `relay-deploy.sh` bash script (Relay smart contracts use external libraries, so it's not currently possible to use solely Foundry script for multi-chain deployment).
* `RelayDeploy.sol` - abstract base that wires common Symbiotic Core helpers and exposes the four deployment hooks: KeyRegistry, VotingPowerProvider, Settlement, and ValVetDriver
* `relay-deploy.sh` - orchestrates per-contract multi-chain deployments
The script deploys Relay modules under [OpenZeppelin's TransparentUpgradeableProxy](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/proxy/transparent/TransparentUpgradeableProxy.sol) using [CreateX](https://github.com/pcaversaccio/createx) (it provides better control for production deployments and more simplified approaches for development).
### **Deployment**
1. Implement your `MyRelayDeploy.sol` Foundry script with the deployment configuration of your Relay modules:
* Implement all virtual functions of `RelayDeploy.sol`
* In the constructor, take the path of the `toml` file
* Use additional helpers such as `getCore()`, `getKeyRegistry()`, `getVotingPowerProvider()`, etc. (see full list in [RelayDeploy.sol](https://github.com/symbioticfi/relay-contracts/blob/main/script/RelayDeploy.sol))
2. Implement your `my-relay-deploy.toml` configuration file with RPC URLs needed for deployment and specify which modules to deploy on which chains
3. Execute the deployment script, e.g.:
```bash
./lib/relay-contracts-new/script/deploy/relay-deploy.sh ./script/MyRelayDeploy.sol "$DEPLOY_CONFIG_PATH" --broadcast --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
```
At the end, your `toml` file will contain the addresses of the deployed Relay modules.
### Middleware contract
Networks need a middleware contract that incorporates custom logic and must include slashing logic.
The script sets middleware for the network in the following way ([script details](https://github.com/symbioticfi/symbiotic-super-sum/blob/5e7625c8fb16acdd30a7695050f2f7b5c8f44d32/script/MyRelayDeploy.sol#L291))
```solidity [script/MyRelayDeploy.sol#291]
Network(payable(network))
.execute(
address(core.networkMiddlewareService),
0,
abi.encodeWithSelector(INetworkMiddlewareService.setMiddleware.selector, votingPowerProvider),
bytes32(0),
bytes32(0)
);
```
## **4. Network Go Live**
The Symbiotic Relay is a peer-to-peer sidecar network that runs alongside main blockchain nodes using a stateless design based entirely on on-chain state. A built-in HTTP API allows querying validator data, tracking epochs, and managing quorum signature aggregation.
Symbiotic-super-sum spins up a mini Symbiotic relay network on your laptop: two local blockchains, a contract deployer, and as many operator nodes as you request. Once the contracts are live, a small genesis job hands every relay node the same starting snapshot so they agree on history. Each operator runs a relay sidecar that keeps them chatting over libp2p, watches both blockchains, and exposes a simple API. A matching sum node sits beside each relay, grabs the contract addresses, and handles the actual task submissions or aggregation work. Together, these containers mimic the full relay network
### **Running network**
`generate_network.sh` generates Docker configuration. Start the network by running `docker compose --project-directory temp-network up -d`
There are several implementations of relay client - [ts](https://github.com/symbioticfi/relay-client-ts), [rust](https://github.com/symbioticfi/relay-client-rs) and [go](https://github.com/symbioticfi/relay).
Here is Go example of integration to sidecar network ([script details](https://github.com/symbioticfi/symbiotic-super-sum/blob/5e7625c8fb16acdd30a7695050f2f7b5c8f44d32/off-chain/cmd/node/main.go#L315)):
```go [off-chain/cmd/node/main.go#315]
relayClient = v1.NewSymbioticClient(conn)
...
suggestedEpoch := uint64(0)
epochInfos, err := relayClient.GetLastAllCommitted(ctx, &v1.GetLastAllCommittedRequest{}) // [!code focus]
if err != nil {
return err
} else {
for _, info := range epochInfos.EpochInfos {
if suggestedEpoch == 0 || info.GetLastCommittedEpoch() < suggestedEpoch {
suggestedEpoch = info.GetLastCommittedEpoch()
}
}
}
resp, err := relayClient.SignMessage(ctx, &v1.SignMessageRequest{ // [!code focus]
KeyTag: 15,
Message: msg,
RequiredEpoch: &suggestedEpoch,
})
if err != nil {
return err
}
```
Another example for cosmos-sdk can be found [here](https://github.com/symbioticfi/cosmos-relay-sdk).
# RFQ
## Check ERC-20 allowance
`POST /api/v1/check_approval`
Reads the wallet's ERC-20 allowance for the Reactor contract and returns an approve() transaction when it is below the requested amount. Call it before submitting an order so the Reactor holds a large enough allowance for the input token.
### Request body (required) (`application/json`)
- `walletAddress` `string` _(required)_: Token owner whose Reactor allowance is read — the swapper that will sign the order.
- `chainId` `integer` _(required)_: Chain to run the check on. Must match the single chain this deployment is configured for.
- `token` `string` _(required)_: ERC-20 the swapper will spend. Its allowance for the Reactor is what gets checked.
- `amount` `string` _(required)_: Allowance the wallet needs, in the token's smallest unit. No approval is returned once allowance reaches it.
### Responses
#### `200`: Success
Body (`application/json`):
- `requestId` `string` _(required)_: Freshly generated UUID identifying this API call.
- `approval` `object` _(required)_: Transaction to send before ordering, or null when the current allowance already covers `amount`.
- `to` `string` _(required)_: Address to send the transaction to — the ERC-20 contract passed in `token`.
- `data` `string` _(required)_: Calldata for approve(reactor, 2^256-1), granting the Reactor an unlimited allowance.
- `value` `string` _(required)_: Native value to attach to the transaction, in wei. Always "0".
- `cancel` `null` _(required)_: Always null. This endpoint never returns an allowance-revocation transaction.
#### `400`: Error
Body (`application/json`):
- `error` `object` _(required)_: Wrapper object present on every error response. It is the only top-level key in the body.
- `code` `string` _(required)_: Machine-readable slug that mirrors the status: badRequest, forbidden, notFound, conflict, internalError.
- `message` `string` _(required)_: Human-readable reason, and the only field that distinguishes causes sharing the same code.
- `status` `number` _(required)_: HTTP status code, repeated inside the body so the envelope is self-describing.
- `timestamp` `string` _(required)_: ISO 8601 UTC instant captured when the error was raised on the server.
- `details` `object`: Sent only for request-validation failures: an issues[] of {path, message}, one entry per failed check.
### Example request
```bash
curl https://swap.symbiotic.fi/api/v1/check_approval \
--request POST \
--header 'Content-Type: application/json' \
--data '{
"walletAddress": "string",
"chainId": 0,
"token": "string",
"amount": "string"
}'
```
```ts
fetch('https://swap.symbiotic.fi/api/v1/check_approval', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
walletAddress: 'string',
chainId: 0,
token: 'string',
amount: 'string'
})
})
```
## Request a quote
`POST /api/v1/quote`
Fans the swap request out to enabled solvers with eligible adapter inventory and returns a non-empty quotes array, best output first, with ties broken by the faster solver response. Each entry contains solver metadata, a quote, and its EIP-712 signing data. Choose an entry, sign its signatureData, and submit its quote to POST /api/v1/order. Responds 404 "No quotes available" when the amount is below the input token's configured minimum, no solver is eligible, or no solver returns a non-zero quote.
### Request body (required) (`application/json`)
- `tokenInChainId` `integer` _(required)_: Chain the input token lives on. Must equal the single chain this deployment serves or the call 400s.
- `tokenOutChainId` `integer` _(required)_: Chain of the output token. Must equal tokenInChainId and the deployment's chain.
- `tokenIn` `string` _(required)_: Token the swapper is selling. 0x address, case-insensitive and normalized to lowercase.
- `tokenOut` `string` _(required)_: Token the swapper wants to receive. Every outputs[].token must repeat this address.
- `type` `string` _(required)_: Only "EXACT_INPUT" is supported: amount fixes the input and solvers compete on the output amount.
- `amount` `string` _(required)_: Input amount to sell, in tokenIn's smallest unit. Below the token's configured minimum no quote is returned.
- `swapper` `string` _(required)_: Address that must sign the order and, unless an output overrides it, receives the output tokens.
- `routingPreference` `string`: Only "BEST_PRICE" is accepted and it is the default. It is recorded but does not affect solver selection.
- `permitAmount` `string`: Optional, "EXACT" is the only accepted value and it is only stored alongside the quote request.
- `solverIds` `string[]`: Restricts the auction to these solver ids (1-50 entries). Omit to fan out to every enabled solver.
- `outputs` `object[]` _(required)_: Split of the output across recipients: 1-50 entries whose portionBps sum to at most 10000.
- `token` `string` _(required)_: Token this recipient is paid in. Must equal tokenOut or the request is rejected.
- `recipient` `string`: Defaults to swapper when omitted for backward compatibility.
- `portionBps` `integer`: Fixed share of the output in basis points. Exactly one output must omit it and takes the remainder.
### Responses
#### `200`: Success
Body (`application/json`):
- `requestId` `string` _(required)_: Server-generated UUID for this quote request. It is logged, so quote it when reporting issues.
- `routing` `string` _(required)_: Routing mode. Always "Priority".
- `quotes` `object[]` _(required)_: Quote options sorted by best price. Permissioned assets return selectable per-solver options. Other assets return one best quote. Sign the selected option's signatureData and submit its quote with the signature to POST /order.
- `solver` `object` _(required)_: Solver that produced this quote.
- `id` `string` _(required)_: Configured solver ID. Reusable in the request's solverIds.
- `name` `string` _(required)_: Human-readable solver name for client display.
- `filler` `string` _(required)_: Filler address this solver is registered under, used to check it may fill from an adapter.
- `metadata` `object` _(required)_: Solver metadata copied from the deployment manifest. Includes logoUrl when a matching hosted logo is available, and may contain additional keys.
- `logoUrl` `string