Skip to content

Instantly share code, notes, and snippets.

@anomit

anomit/bds-dsv-devnet-onboarding.md

Created October 30, 2025 10:39
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save anomit/f35c62bd4f59ee8553ef8e7c450a4f87 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save anomit/f35c62bd4f59ee8553ef8e7c450a4f87 to your computer and use it in GitHub Desktop.
Download ZIP
BDS DSV Devnet Onboarding Guide
Raw
bds-dsv-devnet-onboarding.md

🚀 BDS DSV Devnet Onboarding Guide

Attribute Details
Last Updated October 30, 2025
Target Audience Existing mainnet snapshotter operators
Prerequisites Familiarity with snapshotter operations

🎯 What Makes This Different?

🔄 Decentralized Sequencer Validator (DSV) Network

Unlike traditional mainnet setups that rely on centralized sequencers, this devnet uses Powerloom's Decentralized Sequencer Validator Network. This means:

  • True decentralization: No single point of failure in transaction ordering
  • Validator consensus: Multiple validators work together to sequence transactions
  • Enhanced security: Cryptographic economic incentives ensure honest behavior
  • P2P architecture: Direct peer-to-peer communication between nodes

⚡ Near-Instant Data Feeds with BDS

The Blockchain Data Service (BDS) represents a new paradigm in data delivery:

  • Real-time data: Near-instant snapshot submissions and availability
  • Uniswap V3 focus: Current release serves Uniswap V3 liquidity and trading data
  • Live preview: See the future at https://bds.powerloom.io/
  • Use cases: DeFi applications requiring real-time market data

📚 Learn More: Read more about these concepts in our blog posts:

📋 Step 1: Mint Your Devnet Node

🔑 Get Test Tokens

  1. Visit https://devnet-mint.powerloom.dev/
  2. Click "Get $PLT from Faucet"
  3. Enter your wallet address
  4. Alternative: Direct faucet at https://devnet-faucet.powerloom.dev/

🏗️ Mint Your Node

  1. Back at the devnet dashboard, click "Mint New Node (1 $PLT each)"
  2. Review and approve the transaction
  3. Note your Slot ID (you'll need this later)

👛 Generate Snapshotter Credentials

  1. Click "Manage" next to your new slot ID
  2. Use https://vanity-eth.tk/ to generate a burner wallet
  3. Save both the address and private key - critical for next steps!

🚀 Step 2: Deploy Your Node

Option A: Quick Single-Node Setup (Recommended)

# Clone and setup
git clone https://github.com/powerloom/snapshotter-lite-v2.git bds-snapshotter-lite-v2/
cd bds-snapshotter-lite-v2/
git checkout feat/bds_lite_dsv_rollout

# One-command deployment
sudo ./build.sh --bds-dsv-devnet

What happens next:

  • 🤖 Automatic BDS DSV devnet configuration
  • 📡 Fetches latest protocol settings from GitHub
  • 🔗 Auto-selects BDS_DEVNET_ALPHA_UNISWAPV3 market
  • 🔧 Prompts for your configuration values

Required Information:

  • SOURCE_RPC_URL: Ethereum mainnet RPC URL
  • SIGNER_ACCOUNT_ADDRESS: Your burner wallet address
  • SIGNER_ACCOUNT_PRIVATE_KEY: Your burner wallet private key
  • SLOT_ID: The slot ID from Step 1
  • TELEGRAM_CHAT_ID: Optional, for notifications

✅ Success Indicators

Look for these key log messages showing the complete startup sequence:

# P2P Key Validation
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ LOCAL_COLLECTOR_PRIVATE_KEY found in environment (128 characters)
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ P2P key format is valid (128 hex characters)

# Bootstrap Node Loading
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ Loaded 2 bootstrap nodes from BOOTSTRAP_NODE_ADDRS

# P2P Network Initialization
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ Connection manager configured: LowWater=50, HighWater=200 (publisher mode)
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ Using configured private key from LOCAL_COLLECTOR_PRIVATE_KEY
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ Local collector host created with Peer ID: 12D3KooWBtZHpesajo57fNtQiyh4quLxkhu763fnQWxNYjLwySrH

# Bootstrap Node Connection
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | 🔗 Attempting to connect to 2 bootstrap nodes
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ P2P peer connected: 12D3KooWHmvWNk3kVfbh73KRZZ54j5vy2HN2AC4oXFr8JrVNnnQr, Addr: /ip4/143.198.161.179/tcp/9101

# End-to-End Submission Success
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ Successfully wrote to stream for SIMULATION snapshot submission (Project: baseSnapshot:0xc275a7390966e4bcbf331b837cd7316c4a3efa83:devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH, Epoch: 0) with ID: e1ef3265-bfab-4c08-8651-e45c04531109
snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH  | ✅ Successfully published submission to gossipsub

# Main Snapshotter Confirmation
snapshotter-lite-v2-524-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH           | ✅ Successfully submitted snapshot to local collector: request {
snapshotter-lite-v2-524-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH           |   slotId: 524
snapshotter-lite-v2-524-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH           |   snapshotCid: "bafkreicievww2te6wrchlragmiaooqwie2ljrp5lgt3md3lmm6u7myovve"
snapshotter-lite-v2-524-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH           |   projectId: "baseSnapshot:0xc275a7390966e4bcbf331b837cd7316c4a3efa83:devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH"
snapshotter-lite-v2-524-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH           | }

🎯 Verify Your Deployment

  • Check the Devnet dashboard - refresh to see your submissions
  • Look for snapshot submissions appearing in real-time
  • Monitor P2P connections to bootstrap nodes

Option B: Multi-Node CLI Setup (Advanced)

If you have not used the CLI earlier, it would be a good idea to read the CLI documentation to get a hang of it.

Switch to the branch feat/bds-dsv-devnet-rollout and run the CLI. If you have not cloned the repository yet, clone it and switch to the branch.

Important

The CLI for BDS Devnet is currently in development, so it is recommended to use uv to run the CLI.

On most Ubuntu systems, you can install uv using the following command:

snap install astral-uv --classic
git clone https://github.com/powerloom/snapshotter-lite-multi-setup.git
cd snapshotter-lite-multi-setup/
git checkout feat/bds-dsv-devnet-rollout
uv sync
uv run powerloom-snapshotter-cli shell

The above starts the interactive shell mode. You can now run commands to create a new profile and identity configuration for the BDS DSV Devnet setup.

2.1 Create a new profile and identity configuration for the BDS DSV Devnet setup

Important

  • When asked for the NFT holder wallet address, enter the address against which you minted the node in the previous step.
  • When asked for the SNAPSHOTTER signer address, enter the address of the snapshotter account that you created in the previous step.
  • When asked for the signer private key, enter the private key of the snapshotter account that you created in the previous step.
  • Whenever asked for a data market selection, choose BDS_DEVNET_ALPHA_UNISWAPV3
powerloom-snapshotter> profile create bds-dsv-devnet
✅ Created profile: bds-dsv-devnet
💡 Use 'powerloom-snapshotter-cli configure --profile bds-dsv-devnet' to add configurations.

powerloom-snapshotter> profile set-default bds-dsv-devnet
✅ Set 'bds-dsv-devnet' as the default profile.
ℹ️ Commands without --profile will now use this profile.

[bds-dsv-devnet] powerloom-snapshotter> configure --env devnet
→ Using profile: bds-dsv-devnet
✅ Using default Powerloom RPC URL: https://rpc-devnet.powerloom.dev
1. AAVEV3 (Source: ETH-MAINNET)
2. BDS_DEVNET_ALPHA_UNISWAPV3 (Source: ETH-MAINNET)
3. UNISWAPV2 (Source: ETH-MAINNET)
4. UNISWAPV3 (Source: ETH-MAINNET)
👉 Select data market (number or name): 2
🏷️ Using profile: bds-dsv-devnet
👉 Enter slot NFT holder wallet address (0x...) (): <NFT holder wallet address>
👉 Enter SNAPSHOTTER signer address (0x...) (): <SNAPSHOTTER signer address>
👉 Enter signer private key ():
👉 Enter RPC URL for ETH-MAINNET (): <ETH-MAINNET RPC URL>
👉 Enter Telegram chat ID (optional) ():
✅ Created /root/.powerloom-snapshotter-cli/profiles/bds-dsv-devnet/.env.devnet.bds_devnet_alpha_uniswapv3.eth_mainnet with following values:
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Environment File Contents ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ WALLET_HOLDER_ADDRESS=0xCF...                                                                                                                                                                                                                                                        │
│ SIGNER_ACCOUNT_ADDRESS=0xAC...                                                                                                                                                                                                                                                       │
│ SIGNER_ACCOUNT_PRIVATE_KEY=(hidden)                                                                                                                                                                                                                                                                                     │
│ SOURCE_RPC_URL=<ETH-MAINNET RPC URL>
│ TELEGRAM_REPORTING_URL=https://tg-testing.powerloom.io/                                                                                                                                                                                                                                                                 │
│ MAX_STREAM_POOL_SIZE=100                                                                                                                                                                                                                                                                                                │
│ CONNECTION_REFRESH_INTERVAL_SEC=60                                                                                                                                                                                                                                                                                      │
│ POWERLOOM_RPC_URL=https://rpc-devnet.powerloom.dev                                                                                                                                                                                                                                                                      │
│ LITE_NODE_BRANCH=main                                                                                                                                                                                                                                                                                                   │
│ LOCAL_COLLECTOR_IMAGE_TAG=latest                                                                                                                                                                                                                                                                                        │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[bds-dsv-devnet] powerloom-snapshotter> deploy --env devnet
→ Using profile: bds-dsv-devnet
🐳 Docker daemon is running.
🚀 Deploying to environment: DEVNET...
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Select Data Markets on DEVNET ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                                                                                                                                         │
│  1. UNISWAPV2 (Source: ETH-MAINNET)                                                                                                                                                                                                                                                                                     │
│  2. AAVEV3 (Source: ETH-MAINNET)                                                                                                                                                                                                                                                                                        │
│  3. UNISWAPV3 (Source: ETH-MAINNET)                                                                                                                                                                                                                                                                                     │
│  4. BDS_DEVNET_ALPHA_UNISWAPV3 (Source: ETH-MAINNET)                                                                                                                                                                                                                                                                    │
│                                                                                                                                                                                                                                                                                                                         │
│  0. Custom input (type market names manually)                                                                                                                                                                                                                                                                           │
│  A. Select all markets (4 markets)                                                                                                                                                                                                                                                                                      │
│                                                                                                                                                                                                                                                                                                                         │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
👉 Select markets (e.g., '1,3' or '1-3' or 'A' for all) (1): 4
✅ Selected 1 market(s): BDS_DEVNET_ALPHA_UNISWAPV3
🏷️ Using profile: bds-dsv-devnet
✓ Found profile config for market BDS_DEVNET_ALPHA_UNISWAPV3: /root/.powerloom-snapshotter-cli/profiles/bds-dsv-devnet/.env.devnet.bds_devnet_alpha_uniswapv3.eth_mainnet
ℹ️ No specific slots provided. Fetching all slots owned by <NFT holder wallet address> on devnet...
Found 42 slots for wallet <NFT holder wallet address> on devnet: [...truncated...]
ℹ️ Found slots for wallet <NFT holder wallet address>: [...truncated...]
☑️ Do you want to deploy all of these fetched slots? (y/n) [y]: y

Let the deployment process complete.

  • Thereafter you can use the status command to check the status of the deployment.
  • You can also verify submissions on the Devnet dashboard by refreshing the page or the slot.
  • You can attach to the screen session displayed in the status command to check the logs as well.
[bds-dsv-devnet] powerloom-snapshotter> status
📊 Checking snapshotter instances status...
                                                                                                  Snapshotter Instances Status                                                                                                  \
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Powerloom Chain ┃ Data Market                ┃ Slot ID ┃ Full Session Name                        ┃ PID     ┃ Screen Status       ┃ Docker Containers                                                                        ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ devnet          │ bds_devnet_alpha_uniswapv3 │ 500     │ pl_devnet_bds_devnet_alpha_uniswapv3_525 │ 589865  │ (10/29/25 19:59:49) │   - snapshotter-lite-v2-500-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH (Up 14 hours)          │
│                 │                            │         │                                          │         │                     │   - snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH (Up 15 hours)

[bds-dsv-devnet] powerloom-snapshotter> exit
root@srv-VPC:~/snapshotter-lite-multi-setup# screen -r pl_devnet_bds_devnet_alpha_uniswapv3_500

🔍 Technical Architecture

🌐 P2P Network Configuration

Your node automatically connects to multiple bootstrap nodes for resilience:

  • Bootstrap Node 1: /ip4/159.203.190.22/tcp/9100/p2p/...
  • Bootstrap Node 2: /ip4/143.198.161.179/tcp/9101/p2p/...
  • Failover: If one node is down, others maintain network connectivity

📊 Data Flow

  1. Local Collector → Gathers blockchain data
  2. P2P Gossipsub → Broadcasts to DSV network
  3. DSV Validators → Process and aggregate submissions
  4. BDS Service → Makes data available via API

🏗️ Container Architecture

  • snapshotter-lite-v2: Main snapshotter logic
  • snapshotter-lite-local-collector: P2P networking and data collection
  • Automatic key generation: No manual P2P key setup required

🛠️ Troubleshooting

❌ Bootstrap Connection Issues

Symptom: failed to dial: all dials failed Solution: Normal behavior - system will connect to available bootstrap nodes

⚠️ P2P Key Issues

Symptom: LOCAL_COLLECTOR_PRIVATE_KEY not found Solution: Keys are auto-generated - no manual action needed

📡 Submission Issues

Symptom: No submissions appearing on dashboard Solution:

  1. Check slot ID matches your minted node
  2. Verify SIGNER_ACCOUNT_ADDRESS is correct
  3. Ensure SOURCE_RPC_URL is accessible

🔍 Log Monitoring

# View real-time logs
docker logs -f snapshotter-lite-local-collector-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH

# Check main snapshotter
docker logs -f snapshotter-lite-v2-[SLOT_ID]-devnet-BDS_DEVNET_ALPHA_UNISWAPV3-ETH

🎉 Success! What's Next?

💬 Get Support

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment