Elgato_dark/datahaven
1
0
Fork 0
mirror of https://github.com/datahaven-xyz/datahaven synced 2026-05-23 09:18:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: 📚 Add comprehensive setup documentation for Snowbridge Relays

Browse source
This commit is contained in:
Steve Degosserie 2025-12-01 16:00:08 +01:00
parent 67bc549b1b
commit ec27db7bad
No known key found for this signature in database
GPG key ID: 9455A9F1AD80CE80
5 changed files with 841 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

175
docs/snowbridge-beacon-relay.md
View file

@ -25,6 +25,94 @@ Ethereum Beacon Chain → DataHaven
- Substrate account with balance for transaction fees
- Persistent storage for relay datastore
## Hardware Requirements
### Specifications
| Component | Requirement |
|-----------|-------------|
| **CPU** | 4 cores |
| **RAM** | 8 GB |
| **Storage (Datastore)** | 10 GB SSD |
| **Network** | 100 Mbit/s symmetric |
### Important Considerations
- **Persistent storage**: The relay maintains a local datastore to track processed beacon updates; use persistent volumes in containerized deployments
- **Network latency**: Low latency connections to both beacon node and DataHaven node improve relay performance
- **Reliable RPC endpoints**: Use enterprise-grade or self-hosted beacon nodes for production deployments
## RPC Endpoint Requirements
### Beacon Node API
The relay requires access to a **stable, reliable Ethereum Beacon API endpoint**. Endpoint instability or downtime will prevent the relay from functioning correctly.
**Recommended providers:**
- Self-hosted beacon node (Lighthouse, Prysm, Teku, Nimbus, Lodestar)
- [Dwellir](https://www.dwellir.com/)
- [Chainstack](https://chainstack.com/)
- [QuickNode](https://www.quicknode.com/)
- [Alchemy](https://www.alchemy.com/)
**Requirements:**
- Full beacon API support (`/eth/v1/beacon/*` endpoints)
- State endpoint access for sync committee data
- Low latency (< 100ms recommended)
- High availability (99.9%+ uptime)
## Relay Redundancy
### Why Redundancy Matters
Running multiple relay instances provides fault tolerance and ensures continuous bridge operation even if one relay fails. The on-chain pallets have built-in deduplication, so only the first valid submission is accepted—redundant relays simply provide backup coverage.
### Configuring Redundant Relays
Deploy multiple relay instances pointing to **different RPC providers** for maximum fault tolerance:
**Instance 1 (Primary):**
```json
{
"source": {
"beacon": {
"endpoint": "https://beacon-provider-a.example.com",
"stateEndpoint": "https://beacon-provider-a.example.com"
}
},
"sink": {
"parachain": {
"endpoint": "wss://datahaven-rpc-1.example.com"
}
}
}
```
**Instance 2 (Backup):**
```json
{
"source": {
"beacon": {
"endpoint": "https://beacon-provider-b.example.com",
"stateEndpoint": "https://beacon-provider-b.example.com"
}
},
"sink": {
"parachain": {
"endpoint": "wss://datahaven-rpc-2.example.com"
}
}
}
```
### Best Practices for Redundancy
1. **Use different RPC providers**: Avoid single points of failure by using different beacon node providers for each relay instance
2. **Geographic distribution**: Deploy relays in different regions/data centers
3. **Independent infrastructure**: Run relays on separate machines or Kubernetes nodes
4. **Separate funding accounts**: Use different relay accounts to avoid nonce conflicts
5. **Monitor all instances**: Set up alerting for each relay independently
## Key Requirements
### Substrate Private Key
@ -41,6 +129,8 @@ The relay account must be funded with HAVE tokens to pay for transaction fees wh
**Recommended Balance**: 100+ HAVE for continuous operations
For detailed operating cost estimates and optimization strategies, see the [Relay Operating Costs](./snowbridge-relay-costs.md) guide.
## CLI Flags
### Required Flags
@ -72,8 +162,9 @@ The relay account must be funded with HAVE tokens to pay for transaction fees wh
"slotsInEpoch": 32,
"epochsPerSyncCommitteePeriod": 256,
"forkVersions": {
"deneb": 0,
"electra": 0
"deneb": 269568,
"electra": 364032,
"fulu": 411392
}
},
"datastore": {
@ -93,6 +184,56 @@ The relay account must be funded with HAVE tokens to pay for transaction fees wh
}
```
### Fork Versions by Network
The `forkVersions` parameter specifies the epoch at which each consensus layer fork becomes active. Use the correct values for your target network:
#### Ethereum Mainnet
```json
"forkVersions": {
"deneb": 269568,
"electra": 364032,
"fulu": 411392
}
```
| Fork | Epoch | Activation Date | Fork Version Hex |
|------|-------|-----------------|------------------|
| Deneb | 269568 | March 13, 2024 | `0x04000000` |
| Electra | 364032 | May 7, 2025 | `0x05000000` |
| Fulu | 411392 | December 3, 2025 | `0x06000000` |
#### Hoodi Testnet
```json
"forkVersions": {
"deneb": 0,
"electra": 2048,
"fulu": 67584
}
```
| Fork | Epoch | Fork Version Hex |
|------|-------|------------------|
| Deneb | 0 (genesis) | `0x50000910` |
| Electra | 2048 | `0x60000910` |
| Fulu | 67584 | `0x70000910` |
**Note**: Hoodi is a merged-from-genesis testnet where Deneb is active from epoch 0. Check the [official Hoodi configuration](https://github.com/eth-clients/hoodi) for the latest values.
#### Local Development / Devnet
```json
"forkVersions": {
"deneb": 0,
"electra": 0,
"fulu": 0
}
```
For local development networks where all forks are active from genesis.
### Configuration Parameters
#### Source (Beacon Chain)
@ -104,7 +245,9 @@ The relay account must be funded with HAVE tokens to pay for transaction fees wh
| `source.beacon.spec.syncCommitteeSize` | Size of sync committee | `512` |
| `source.beacon.spec.slotsInEpoch` | Slots per epoch | `32` |
| `source.beacon.spec.epochsPerSyncCommitteePeriod` | Epochs per sync committee period | `256` |
| `source.beacon.spec.forkVersions` | Fork version configuration | `{"deneb": 0, "electra": 0}` |
| `source.beacon.spec.forkVersions.deneb` | Epoch when Deneb fork activated | `269568` (mainnet) |
| `source.beacon.spec.forkVersions.electra` | Epoch when Electra fork activated | `364032` (mainnet) |
| `source.beacon.spec.forkVersions.fulu` | Epoch when Fulu fork activated | `411392` (mainnet) |
| `source.beacon.datastore.location` | Path to persistent datastore | `/relay-data` |
| `source.beacon.datastore.maxEntries` | Maximum datastore entries | `100` |
@ -130,12 +273,30 @@ docker run --rm \
-v $(pwd)/datastore:/data \
--platform linux/amd64 \
datahavenxyz/snowbridge-relay:latest \
generate-beacon-checkpoint --config beacon-relay.json --export-json
generate-beacon-checkpoint --config beacon-relay.json \
> beacon_checkpoint.hex
```
This outputs the raw checkpoint payload to `beacon_checkpoint.hex`.
### Submit Checkpoint to DataHaven
The checkpoint must be submitted via a sudo call to `EthereumBeaconClient.force_checkpoint`:
The checkpoint must be submitted via a sudo call to `EthereumBeaconClient.force_checkpoint`. There are two methods:
#### Option 1: Using Polkadot.js Apps (Recommended)
1. Open [Polkadot.js Apps](https://polkadot.js.org/apps/) and connect to your DataHaven node
2. Navigate to **Developer** > **Extrinsics**
3. Select **Decode** tab
4. Prepend `0x24003c00` to the contents of `beacon_checkpoint.hex` and paste the full hex string
- `0x24` = Sudo pallet index
- `0x00` = sudo call index
- `0x3c` = EthereumBeaconClient pallet index
- `0x00` = force_checkpoint call index
5. The UI should decode this as `sudo.sudo(ethereumBeaconClient.force_checkpoint(...))`
6. Select your Sudo account and submit the transaction
#### Option 2: Using Polkadot-API (TypeScript)
```typescript
import { createClient } from 'polkadot-api';
@ -331,5 +492,9 @@ curl http://beacon-node:4000/eth/v1/beacon/states/head/finality_checkpoints
- [BEEFY Relay](./snowbridge-beefy-relay.md)
- [Execution Relay](./snowbridge-execution-relay.md)
- [Solochain Relay](./snowbridge-solochain-relay.md)
- [Relay Operating Costs](./snowbridge-relay-costs.md)
- [Snowbridge Documentation](https://docs.snowbridge.network)
- [DataHaven Snowbridge Repository](https://github.com/datahaven-xyz/snowbridge)
- [Ethereum Consensus Specs - Mainnet Config](https://github.com/ethereum/consensus-specs/blob/dev/configs/mainnet.yaml)
- [Hoodi Testnet Configuration](https://github.com/eth-clients/hoodi)
- [Ethereum Fork Timeline](https://ethereum.org/ethereum-forks/)

94
docs/snowbridge-beefy-relay.md
View file

@ -25,6 +25,97 @@ DataHaven → Ethereum
- Ethereum account with ETH for gas fees
- Deployed BeefyClient and Gateway contracts on Ethereum
## Hardware Requirements
### Specifications
| Component | Requirement |
|-----------|-------------|
| **CPU** | 4 cores |
| **RAM** | 8 GB |
| **Storage (Datastore)** | 5 GB SSD |
| **Network** | 100 Mbit/s symmetric |
### Important Considerations
- **No persistent storage required**: BEEFY relay is stateless and recovers from on-chain state on restart
- **Gas optimization**: The relay batches BEEFY proofs when possible to reduce Ethereum gas costs
- **Network latency**: Low latency to Ethereum node is important for timely proof submission
- **Reliable RPC endpoints**: Use enterprise-grade or self-hosted nodes for production deployments
## RPC Endpoint Requirements
### Ethereum Execution Layer
The relay requires access to a **stable, reliable Ethereum WebSocket endpoint**. Endpoint instability or downtime will prevent the relay from functioning correctly.
**Recommended providers:**
- Self-hosted execution node (Geth, Nethermind, Besu, Erigon)
- [Dwellir](https://www.dwellir.com/)
- [Chainstack](https://chainstack.com/)
- [QuickNode](https://www.quicknode.com/)
- [Alchemy](https://www.alchemy.com/)
**Requirements:**
- WebSocket support (WSS for production)
- Low latency (< 100ms recommended)
- High availability (99.9%+ uptime)
### DataHaven Node
- Full node or archive node with WebSocket endpoint
- Low latency connection for monitoring BEEFY finality
## Relay Redundancy
### Why Redundancy Matters
Running multiple relay instances provides fault tolerance and ensures continuous bridge operation even if one relay fails. The BeefyClient contract handles duplicate submissions gracefully—only the first valid submission is processed.
### Configuring Redundant Relays
Deploy multiple relay instances pointing to **different RPC providers** for maximum fault tolerance:
**Instance 1 (Primary):**
```json
{
"source": {
"polkadot": {
"endpoint": "wss://datahaven-rpc-1.example.com"
}
},
"sink": {
"ethereum": {
"endpoint": "wss://eth-provider-a.example.com"
}
}
}
```
**Instance 2 (Backup):**
```json
{
"source": {
"polkadot": {
"endpoint": "wss://datahaven-rpc-2.example.com"
}
},
"sink": {
"ethereum": {
"endpoint": "wss://eth-provider-b.example.com"
}
}
}
```
### Best Practices for Redundancy
1. **Use different RPC providers**: Avoid single points of failure by using different Ethereum node providers for each relay instance
2. **Geographic distribution**: Deploy relays in different regions/data centers
3. **Independent infrastructure**: Run relays on separate machines or Kubernetes nodes
4. **Separate funding accounts**: Use different relay accounts to avoid nonce conflicts
5. **Monitor all instances**: Set up alerting for each relay independently
## Key Requirements
### Ethereum Private Key
@ -41,6 +132,8 @@ The relay account must be funded with ETH to pay for gas when submitting BEEFY p
**Recommended Balance**: 0.5+ ETH for continuous operations (gas costs vary with network conditions)
For detailed operating cost estimates and optimization strategies, see the [Relay Operating Costs](./snowbridge-relay-costs.md) guide.
## CLI Flags
### Required Flags
@ -349,5 +442,6 @@ Relayers can earn incentives for successful proof submissions. See Snowbridge do
- [Beacon Relay](./snowbridge-beacon-relay.md)
- [Execution Relay](./snowbridge-execution-relay.md)
- [Solochain Relay](./snowbridge-solochain-relay.md)
- [Relay Operating Costs](./snowbridge-relay-costs.md)
- [Snowbridge Documentation](https://docs.snowbridge.network)
- [DataHaven Snowbridge Repository](https://github.com/datahaven-xyz/snowbridge)

191
docs/snowbridge-execution-relay.md
View file

@ -27,6 +27,112 @@ Ethereum Execution Layer → DataHaven
- Deployed Gateway contract on Ethereum
- Persistent storage for relay datastore
## Hardware Requirements
### Specifications
| Component | Requirement |
|-----------|-------------|
| **CPU** | 4 cores |
| **RAM** | 8 GB |
| **Storage (Datastore)** | 10 GB SSD |
| **Network** | 100 Mbit/s symmetric |
### Important Considerations
- **Persistent storage**: The relay maintains a local datastore to track processed messages; use persistent volumes in containerized deployments
- **Message throughput**: Storage requirements may increase with high message volumes
- **Network connectivity**: Requires connections to both Ethereum (execution + beacon) and DataHaven nodes
- **Reliable RPC endpoints**: Use enterprise-grade or self-hosted nodes for production deployments
## RPC Endpoint Requirements
### Ethereum Execution Layer
The relay requires access to a **stable, reliable Ethereum WebSocket endpoint**. Endpoint instability or downtime will prevent the relay from functioning correctly.
**Recommended providers:**
- Self-hosted execution node (Geth, Nethermind, Besu, Erigon)
- [Dwellir](https://www.dwellir.com/)
- [Chainstack](https://chainstack.com/)
- [QuickNode](https://www.quicknode.com/)
- [Alchemy](https://www.alchemy.com/)
**Requirements:**
- WebSocket support (WSS for production)
- Full event log access for Gateway contract monitoring
- Low latency (< 100ms recommended)
- High availability (99.9%+ uptime)
### Beacon Node API
The relay also requires access to the Ethereum Beacon API for constructing message proofs.
**Recommended providers:**
- Self-hosted beacon node (Lighthouse, Prysm, Teku, Nimbus, Lodestar)
- Same providers as execution layer (with beacon API support)
**Requirements:**
- Full beacon API support (`/eth/v1/beacon/*` endpoints)
- State endpoint access for proof construction
- Low latency (< 100ms recommended)
## Relay Redundancy
### Why Redundancy Matters
Running multiple relay instances provides fault tolerance and ensures continuous bridge operation even if one relay fails. The on-chain pallets have built-in deduplication, so only the first valid submission is accepted—redundant relays simply provide backup coverage.
### Configuring Redundant Relays
Deploy multiple relay instances pointing to **different RPC providers** for maximum fault tolerance:
**Instance 1 (Primary):**
```json
{
"source": {
"ethereum": {
"endpoint": "wss://eth-provider-a.example.com"
},
"beacon": {
"endpoint": "https://beacon-provider-a.example.com"
}
},
"sink": {
"parachain": {
"endpoint": "wss://datahaven-rpc-1.example.com"
}
}
}
```
**Instance 2 (Backup):**
```json
{
"source": {
"ethereum": {
"endpoint": "wss://eth-provider-b.example.com"
},
"beacon": {
"endpoint": "https://beacon-provider-b.example.com"
}
},
"sink": {
"parachain": {
"endpoint": "wss://datahaven-rpc-2.example.com"
}
}
}
```
### Best Practices for Redundancy
1. **Use different RPC providers**: Avoid single points of failure by using different Ethereum node providers for each relay instance
2. **Geographic distribution**: Deploy relays in different regions/data centers
3. **Independent infrastructure**: Run relays on separate machines or Kubernetes nodes
4. **Separate funding accounts**: Use different relay accounts to avoid nonce conflicts
5. **Monitor all instances**: Set up alerting for each relay independently
## Key Requirements
### Substrate Private Key
@ -43,6 +149,8 @@ The relay account must be funded with HAVE tokens to pay for transaction fees.
**Recommended Balance**: 100+ HAVE for continuous operations
For detailed operating cost estimates and optimization strategies, see the [Relay Operating Costs](./snowbridge-relay-costs.md) guide.
## CLI Flags
### Required Flags
@ -144,8 +252,45 @@ The relay account must be funded with HAVE tokens to pay for transaction fees.
## Multi-Instance Deployment
For high-availability or load distribution, multiple Execution Relayers can be deployed:
For high-availability or load distribution, multiple Execution Relayers can be deployed using the `schedule` configuration to coordinate between instances.
### Schedule Configuration Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `schedule.id` | `number` or `null` | Unique identifier for this relay instance (0-indexed). Set to `null` for single-instance deployments. |
| `schedule.totalRelayerCount` | `number` | Total number of relay instances in the deployment. All instances must use the same value. |
| `schedule.sleepInterval` | `number` | Seconds to wait between polling for new messages. Lower values = faster detection, higher resource usage. |
### How Multi-Instance Scheduling Works
When multiple relayers are deployed, the `schedule.id` and `totalRelayerCount` parameters work together to distribute message processing:
1. **Message assignment**: Messages are assigned to relayers based on `message_nonce % totalRelayerCount == schedule.id`
2. **Staggered processing**: Each relayer only processes messages assigned to its ID, preventing duplicate submissions
3. **Failover**: If a relayer fails, its messages will eventually be picked up by other relayers after timeout
**Example with 3 relayers:**
- Instance 0 processes messages where `nonce % 3 == 0` (nonces: 0, 3, 6, 9, ...)
- Instance 1 processes messages where `nonce % 3 == 1` (nonces: 1, 4, 7, 10, ...)
- Instance 2 processes messages where `nonce % 3 == 2` (nonces: 2, 5, 8, 11, ...)
### Configuration Examples
**Single Instance (default):**
```json
{
"schedule": {
"id": null,
"totalRelayerCount": 1,
"sleepInterval": 1
}
}
```
**Three-Instance Deployment:**
*Instance 0:*
```json
{
"schedule": {
@ -156,7 +301,48 @@ For high-availability or load distribution, multiple Execution Relayers can be d
}
```
Each instance should have a unique `id` (0, 1, 2, ...) and the same `totalRelayerCount`.
*Instance 1:*
```json
{
"schedule": {
"id": 1,
"totalRelayerCount": 3,
"sleepInterval": 1
}
}
```
*Instance 2:*
```json
{
"schedule": {
"id": 2,
"totalRelayerCount": 3,
"sleepInterval": 1
}
}
```
### Sleep Interval Tuning
The `sleepInterval` parameter controls how frequently the relay polls for new messages:
| Value | Use Case | Trade-offs |
|-------|----------|------------|
| `1` | Low latency required | Higher RPC usage, faster message detection |
| `5` | Balanced | Good balance of latency and resource usage |
| `10` | Cost-sensitive | Lower RPC costs, slower message detection |
| `30` | Minimal activity | Very low resource usage, higher latency |
**Recommendation**: Start with `sleepInterval: 1` for production deployments where message latency is important. Increase if RPC rate limits become an issue.
### Deployment Checklist
1. **Unique IDs**: Each instance must have a unique `schedule.id` (0 to `totalRelayerCount - 1`)
2. **Consistent count**: All instances must use the same `totalRelayerCount` value
3. **Separate accounts**: Use different Substrate accounts to avoid nonce conflicts
4. **Independent storage**: Each instance needs its own persistent datastore volume
5. **Different RPC endpoints**: Point instances to different RPC providers for fault tolerance
## Running the Relay
@ -363,5 +549,6 @@ Relayers can claim incentives from the protocol for successful message deliverie
- [Beacon Relay](./snowbridge-beacon-relay.md)
- [BEEFY Relay](./snowbridge-beefy-relay.md)
- [Solochain Relay](./snowbridge-solochain-relay.md)
- [Relay Operating Costs](./snowbridge-relay-costs.md)
- [Snowbridge Documentation](https://docs.snowbridge.network)
- [DataHaven Snowbridge Repository](https://github.com/datahaven-xyz/snowbridge)

184
docs/snowbridge-relay-costs.md Normal file
View file

@ -0,0 +1,184 @@
# Snowbridge Relay Operating Costs
## Overview
This page provides guidance on funding requirements and operating cost estimates for running Snowbridge relays. These costs apply across all relay types (Beacon, BEEFY, Execution, and Solochain).
## Account Funding Requirements
### Ethereum Account (BEEFY, Solochain Relays)
Relays that submit transactions to Ethereum require funded Ethereum accounts for gas fees.
| Relay Type | Minimum | Recommended | Purpose |
|------------|---------|-------------|---------|
| BEEFY Relay | 0.5 ETH | 2.0 ETH | Submit BEEFY proofs to BeefyClient contract |
| Solochain Relay | 0.5 ETH | 2.0 ETH | Submit messages to Gateway, sync rewards |
### Substrate Account (Beacon, Execution, Solochain Relays)
Relays that submit extrinsics to DataHaven require funded Substrate accounts for transaction fees.
| Relay Type | Minimum | Recommended | Purpose |
|------------|---------|-------------|---------|
| Beacon Relay | 100 HAVE | 500 HAVE | Submit beacon updates to EthereumBeaconClient |
| Execution Relay | 100 HAVE | 500 HAVE | Deliver messages via EthereumInboundQueue |
| Solochain Relay | 100 HAVE | 500 HAVE | DataHaven operations |
## Gas Cost Breakdown (Ethereum)
Relays submitting to Ethereum incur gas costs for various operations:
| Operation | Relay Type | Estimated Gas | Frequency |
|-----------|------------|---------------|-----------|
| BEEFY commitment | BEEFY | 200,000-400,000 | Per commitment |
| Message delivery | Solochain | 150,000-300,000 | Per message |
| Reward sync update | Solochain | 100,000-200,000 | Per epoch/period |
## Annual Operating Cost Forecast
> **Disclaimer**: The cost estimates below are approximate projections based on typical network conditions and are provided for planning purposes only. Actual costs may vary significantly based on network congestion, gas price fluctuations, ETH price volatility, and message volume. **Always conduct your own cost analysis** based on current market conditions before budgeting for relay operations.
### Assumptions
- Average gas price: 30 gwei
- ETH price: $3,000 USD (as of December 2025)
- HAVE transaction fees: negligible compared to ETH costs
### BEEFY Relay Costs
BEEFY proofs are submitted periodically to keep the BeefyClient contract updated with DataHaven finality.
| Scenario | Commitments/Day | Gas/Year (ETH) | Annual Cost (USD) |
|----------|-----------------|----------------|-------------------|
| **Low activity** | 4-6 | 0.4-0.8 ETH | $1,200-$2,400 |
| **Medium activity** | 10-15 | 1.0-1.6 ETH | $3,000-$4,800 |
| **High activity** | 20-30 | 2.0-3.5 ETH | $6,000-$10,500 |
### Solochain Relay Costs
The Solochain Relay handles message delivery and reward synchronization.
| Scenario | Messages/Day | Gas/Year (ETH) | Annual Cost (USD) |
|----------|--------------|----------------|-------------------|
| **Low activity** | 50 | 0.8-1.5 ETH | $2,400-$4,500 |
| **Medium activity** | 100 | 1.5-3.0 ETH | $4,500-$9,000 |
| **High activity** | 200 | 3.0-6.0 ETH | $9,000-$18,000 |
### Beacon & Execution Relay Costs
These relays only incur HAVE transaction fees on DataHaven, which are minimal:
| Relay Type | Annual HAVE Estimate | Notes |
|------------|---------------------|-------|
| Beacon Relay | 50-200 HAVE | Sync committee updates |
| Execution Relay | 100-500 HAVE | Message delivery to DataHaven |
### Cost Calculation Formula
```
Annual ETH Cost = (operations_per_day × avg_gas_per_operation × avg_gas_price × 365) / 1e18
Annual USD Cost = Annual ETH Cost × ETH_price
```
**Example (Solochain Relay, Medium Activity):**
```
= (100 messages × 200,000 gas × 30 gwei × 365 days) / 1e18
= 2.19 ETH/year
= ~$6,570 USD/year at $3,000/ETH
```
## Total Operating Costs (Full Relay Stack)
Running a complete Snowbridge relay infrastructure requires all four relays. Here's a combined cost estimate:
| Scenario | ETH/Year | HAVE/Year | Annual USD (ETH only) |
|----------|----------|-----------|----------------------|
| **Low activity** | 1.2-2.3 ETH | 200-400 HAVE | $3,600-$6,900 |
| **Medium activity** | 2.5-4.6 ETH | 400-800 HAVE | $7,500-$13,800 |
| **High activity** | 5.0-9.5 ETH | 800-1,500 HAVE | $15,000-$28,500 |
> **Note**: These estimates assume a single relay instance per type. Running redundant relays (recommended for production) will multiply costs proportionally.
## Cost Optimization Strategies
### 1. Gas Price Optimization
- **Monitor gas prices**: Use services like [ETH Gas Station](https://ethgasstation.info/) or [Etherscan Gas Tracker](https://etherscan.io/gastracker)
- **Off-peak submissions**: Non-urgent operations can wait for lower gas prices
- **Gas price limits**: Configure maximum gas price thresholds in relay settings
### 2. Batching Operations
- BEEFY relay batches commitments when possible
- Solochain relay batches reward updates
- Reduces per-operation overhead
### 3. Right-Size Your Deployment
| Network Activity | Recommended Setup |
|------------------|-------------------|
| Low volume | Single instance per relay type |
| Medium volume | 2 instances with different providers |
| High volume/Production | 3+ instances across regions |
### 4. Infrastructure Cost Savings
- **Shared RPC endpoints**: Use the same provider subscription across relays
- **Self-hosted nodes**: Higher upfront cost but eliminates per-request fees
- **Cloud cost optimization**: Use reserved instances or spot pricing where appropriate
## Balance Monitoring & Alerts
### Recommended Alert Thresholds
| Account Type | Low Balance Alert | Critical Alert |
|--------------|-------------------|----------------|
| Ethereum | 0.2 ETH | 0.1 ETH |
| Substrate (HAVE) | 50 HAVE | 20 HAVE |
### Monitoring Setup
```bash
# Check Ethereum balance
cast balance $RELAY_ETH_ADDRESS --rpc-url $ETH_RPC_URL
# Check HAVE balance (using subxt or polkadot-js)
# Monitor via your preferred Substrate tooling
```
### Automated Top-Up
Consider implementing automated funding from a treasury account when balances fall below thresholds. This prevents relay downtime due to insufficient funds.
## Cost Variability Factors
### Ethereum Gas Prices
Gas prices can vary dramatically:
| Condition | Typical Gas Price | Impact |
|-----------|-------------------|--------|
| Low congestion | 10-20 gwei | 50% below estimates |
| Normal | 20-40 gwei | Within estimates |
| High congestion | 50-100 gwei | 2-3x estimates |
| Extreme (NFT mints, etc.) | 100-500+ gwei | 5-10x estimates |
### ETH Price Volatility
ETH price directly affects USD costs:
| ETH Price | Annual Cost (Medium Activity) |
|-----------|------------------------------|
| $2,000 | ~$4,400 |
| $3,000 | ~$6,600 |
| $4,000 | ~$8,800 |
| $5,000 | ~$11,000 |
## Related Documentation
- [Beacon Relay](./snowbridge-beacon-relay.md)
- [BEEFY Relay](./snowbridge-beefy-relay.md)
- [Execution Relay](./snowbridge-execution-relay.md)
- [Solochain Relay](./snowbridge-solochain-relay.md)
- [Snowbridge Documentation](https://docs.snowbridge.network)

215
docs/snowbridge-solochain-relay.md
View file

@ -28,6 +28,137 @@ DataHaven → Ethereum (with bidirectional monitoring)
- Deployed BeefyClient, Gateway, and RewardsRegistry contracts on Ethereum
- Persistent storage for relay datastore
## Hardware Requirements
The Solochain Relay handles more operations than other relays (bidirectional messaging + rewards), so additional resources are recommended.
### Specifications
| Component | Requirement |
|-----------|-------------|
| **CPU** | 4 cores |
| **RAM** | 8 GB |
| **Storage (Datastore)** | 20 GB SSD |
| **Network** | 100 Mbit/s symmetric |
### Important Considerations
- **Persistent storage**: The relay maintains a local datastore to track processed messages and reward operations; use persistent volumes in containerized deployments
- **Bidirectional operations**: Handles both DataHaven → Ethereum messages and reward synchronization
- **Network connectivity**: Requires connections to Ethereum (execution + beacon) and DataHaven nodes simultaneously
- **Higher resource usage**: May use more resources during high message volumes or reward distribution periods
- **Reliable RPC endpoints**: Use enterprise-grade or self-hosted nodes for production deployments
## RPC Endpoint Requirements
### Ethereum Execution Layer
The relay requires access to a **stable, reliable Ethereum WebSocket endpoint**. Endpoint instability or downtime will prevent the relay from functioning correctly.
**Recommended providers:**
- Self-hosted execution node (Geth, Nethermind, Besu, Erigon)
- [Dwellir](https://www.dwellir.com/)
- [Chainstack](https://chainstack.com/)
- [QuickNode](https://www.quicknode.com/)
- [Alchemy](https://www.alchemy.com/)
**Requirements:**
- WebSocket support (WSS for production)
- Full event log access for contract monitoring
- Low latency (< 100ms recommended)
- High availability (99.9%+ uptime)
### Beacon Node API
The relay also requires access to the Ethereum Beacon API for finality verification.
**Recommended providers:**
- Self-hosted beacon node (Lighthouse, Prysm, Teku, Nimbus, Lodestar)
- Same providers as execution layer (with beacon API support)
**Requirements:**
- Full beacon API support (`/eth/v1/beacon/*` endpoints)
- State endpoint access for sync committee data
- Low latency (< 100ms recommended)
### DataHaven Node
- Full node or archive node with WebSocket endpoint
- Low latency connection for monitoring outbound messages
## Relay Redundancy
### Why Redundancy Matters
Running multiple relay instances provides fault tolerance and ensures continuous bridge operation even if one relay fails. The Gateway contract and on-chain pallets handle duplicate submissions gracefully—only the first valid submission is processed.
### Configuring Redundant Relays
Deploy multiple relay instances pointing to **different RPC providers** for maximum fault tolerance. Use the `schedule` configuration to coordinate between instances:
**Instance 1 (Primary):**
```json
{
"source": {
"ethereum": {
"endpoint": "wss://eth-provider-a.example.com"
},
"solochain": {
"endpoint": "wss://datahaven-rpc-1.example.com"
},
"beacon": {
"endpoint": "https://beacon-provider-a.example.com"
}
},
"sink": {
"ethereum": {
"endpoint": "wss://eth-provider-a.example.com"
}
},
"schedule": {
"id": 0,
"totalRelayerCount": 2,
"sleepInterval": 10
}
}
```
**Instance 2 (Backup):**
```json
{
"source": {
"ethereum": {
"endpoint": "wss://eth-provider-b.example.com"
},
"solochain": {
"endpoint": "wss://datahaven-rpc-2.example.com"
},
"beacon": {
"endpoint": "https://beacon-provider-b.example.com"
}
},
"sink": {
"ethereum": {
"endpoint": "wss://eth-provider-b.example.com"
}
},
"schedule": {
"id": 1,
"totalRelayerCount": 2,
"sleepInterval": 10
}
}
```
### Best Practices for Redundancy
1. **Use different RPC providers**: Avoid single points of failure by using different Ethereum and DataHaven node providers for each relay instance
2. **Geographic distribution**: Deploy relays in different regions/data centers
3. **Independent infrastructure**: Run relays on separate machines or Kubernetes nodes
4. **Separate funding accounts**: Use different relay accounts (both Ethereum and Substrate) to avoid nonce conflicts
5. **Coordinate with schedule IDs**: Use unique `schedule.id` values for each instance
6. **Monitor all instances**: Set up alerting for each relay independently
## Key Requirements
### Both Ethereum and Substrate Private Keys
@ -41,10 +172,14 @@ The Solochain Relay requires **both** an Ethereum private key and a Substrate pr
### Account Funding
| Account | Funding Required |
|---------|-----------------|
| Ethereum | 0.5+ ETH for gas fees |
| Substrate | 100+ HAVE for transaction fees |
The Solochain Relay requires funded accounts on both Ethereum and DataHaven to operate continuously.
| Account | Minimum | Recommended | Purpose |
|---------|---------|-------------|---------|
| Ethereum | 0.5 ETH | 2.0 ETH | Gas fees for Gateway contract calls |
| Substrate (HAVE) | 100 HAVE | 500 HAVE | Transaction fees on DataHaven |
For detailed operating cost estimates, annual forecasts, and cost optimization strategies, see the [Relay Operating Costs](./snowbridge-relay-costs.md) guide.
## CLI Flags
@ -327,8 +462,44 @@ spec:
## Multi-Instance Deployment
For high-availability, deploy multiple Solochain Relayers:
For high-availability or load distribution, multiple Solochain Relayers can be deployed using the `schedule` configuration to coordinate between instances.
### Schedule Configuration Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `schedule.id` | `number` | Unique identifier for this relay instance (0-indexed). |
| `schedule.totalRelayerCount` | `number` | Total number of relay instances in the deployment. All instances must use the same value. |
| `schedule.sleepInterval` | `number` | Seconds to wait between polling for new messages. Lower values = faster detection, higher resource usage. |
### How Multi-Instance Scheduling Works
When multiple relayers are deployed, the `schedule.id` and `totalRelayerCount` parameters work together to distribute message processing:
1. **Message assignment**: Messages are assigned to relayers based on `message_nonce % totalRelayerCount == schedule.id`
2. **Staggered processing**: Each relayer only processes messages assigned to its ID, preventing duplicate submissions
3. **Failover**: If a relayer fails, its messages will eventually be picked up by other relayers after timeout
**Example with 2 relayers:**
- Instance 0 processes messages where `nonce % 2 == 0` (nonces: 0, 2, 4, 6, ...)
- Instance 1 processes messages where `nonce % 2 == 1` (nonces: 1, 3, 5, 7, ...)
### Configuration Examples
**Single Instance (default):**
```json
{
"schedule": {
"id": 0,
"totalRelayerCount": 1,
"sleepInterval": 10
}
}
```
**Two-Instance Deployment:**
*Instance 0:*
```json
{
"schedule": {
@ -339,15 +510,36 @@ For high-availability, deploy multiple Solochain Relayers:
}
```
**Instance 0**:
*Instance 1:*
```json
{ "schedule": { "id": 0, "totalRelayerCount": 2, "sleepInterval": 10 } }
{
"schedule": {
"id": 1,
"totalRelayerCount": 2,
"sleepInterval": 10
}
}
```
**Instance 1**:
```json
{ "schedule": { "id": 1, "totalRelayerCount": 2, "sleepInterval": 10 } }
```
### Sleep Interval Tuning
The `sleepInterval` parameter controls how frequently the relay polls for new messages:
| Value | Use Case | Trade-offs |
|-------|----------|------------|
| `1` | Low latency required | Higher RPC usage, faster message detection |
| `10` | Balanced (default) | Good balance of latency and resource usage |
| `30` | Cost-sensitive | Lower RPC costs, slower message detection |
**Recommendation**: The default `sleepInterval: 10` works well for most deployments. Decrease if message latency is critical; increase if RPC rate limits are a concern.
### Deployment Checklist
1. **Unique IDs**: Each instance must have a unique `schedule.id` (0 to `totalRelayerCount - 1`)
2. **Consistent count**: All instances must use the same `totalRelayerCount` value
3. **Separate accounts**: Use different Ethereum and Substrate accounts to avoid nonce conflicts
4. **Independent storage**: Each instance needs its own persistent datastore volume
5. **Different RPC endpoints**: Point instances to different RPC providers for fault tolerance
## Monitoring
@ -414,5 +606,6 @@ Ensure both relays are operational before starting the Solochain Relay.
- [Beacon Relay](./snowbridge-beacon-relay.md)
- [BEEFY Relay](./snowbridge-beefy-relay.md)
- [Execution Relay](./snowbridge-execution-relay.md)
- [Relay Operating Costs](./snowbridge-relay-costs.md)
- [Snowbridge Documentation](https://docs.snowbridge.network)
- [DataHaven Snowbridge Repository](https://github.com/datahaven-xyz/snowbridge)