Single command deployment of SNS on local replica

Developers
1

:rocket: Introducing local_sns: Deploy SNS on Your Local dfx Network

local_sns is a standalone Rust tool for deploying and managing Service Nervous System (SNS) instances on local dfx networks.

Note: This tool was originally developed to test SNS functionality for TOKO, but we’ve open-sourced it for the community. The tool now features a fully interactive menu system and comprehensive SNS management capabilities!

What is local_sns?

local_sns automates the entire SNS deployment process locally, from creating ICP neurons and proposals to participating in swaps and finalizing deployments. It’s perfect for developers who want to:

  • Test SNS functionality before deploying to mainnet

  • Develop SNS integrations without waiting for proposal execution times

  • Experiment with SNS governance and neuron management

  • Learn how SNS deployment works through automated scripts

Key Features

:white_check_mark: Fully Automated Deployment - One command to deploy a complete SNS locally

:white_check_mark: Interactive Menu System - Easy-to-use menu for all operations

:white_check_mark: Fully Interactive Scripts - All scripts prompt for missing arguments

:white_check_mark: Comprehensive SNS Management - Create neurons, manage hotkeys, mint tokens, and more

:white_check_mark: Self-Contained - Standalone Rust binary, no external dependencies

Quick Start


# Clone the repository

git clone https://github.com/dragginzgame/local_sns.git

cd local_sns

# Start your local dfx network (requires dfx 0.30.1+)

dfx start --clean --system-canisters

# Launch the interactive menu (recommended)

bash scripts/start.sh

The interactive menu provides easy access to all operations. If no SNS is deployed, it will prompt you to deploy one automatically!

What You Can Do

The interactive menu gives you access to:

  • Deploy SNS - Fully automated deployment of complete SNS instances

  • Manage Neurons - Create SNS neurons, add hotkeys, query neurons, and disburse tokens

  • Governance - Create proposals to mint tokens with automatic voting

  • ICP Operations - Manage ICP neurons, add hotkeys, and configure visibility

All operations are interactive - just follow the prompts. No need to remember complex command syntax!

Example Workflow


# 1. Start the interactive menu

bash scripts/start.sh

# 2. Deploy your first SNS (option 9, or prompted automatically)

# This creates all canisters, participants, and finalizes the swap

# 3. Mint tokens (option 8)

# Creates a proposal and automatically votes with all neurons

# You need tokens in your ledger balance before creating neurons

# 4. Create an SNS neuron (option 6)

# Stakes tokens from your ledger balance

# Prompts for principal, amount, memo, and dissolve delay

# 5. Add a hotkey (option 1 for SNS)

# Interactive selection of neurons and hotkeys

You can also run individual scripts directly - they all support interactive prompts when arguments are omitted. See the README for complete documentation.

Configuration

Customize your SNS parameters in src/init/sns_config.rs. This includes token information, governance parameters, swap settings, and more. You can even add a custom logo by placing a PNG file at src/init/logo.png - it will be automatically loaded and converted during deployment.

Requirements

  • Rust toolchain - Install from rustup.rs

  • dfx SDK 0.30.1+ - Must support the --system-canisters flag

  • Local dfx network - Running with system canisters enabled

Use Cases

  • SNS Development - Test SNS features locally before mainnet deployment

  • Integration Testing - Verify your dApp works with SNS governance

  • Educational - Learn how SNS deployment works end-to-end

  • Experimentation - Try different SNS configurations safely

Try It Out

  1. Clone and run - bash scripts/start.sh to launch the interactive menu

  2. Deploy - Follow the prompts to deploy your first local SNS

  3. Experiment - Try creating neurons, managing governance, and minting tokens

  4. Customize - Modify src/init/sns_config.rs for your needs

For detailed documentation, command reference, and technical details, see the README.

Links

:link: Repository: GitHub - dragginzgame/local_sns: Codebase to deploy a SNS on the local replica

:open_book: Documentation: See README.md in the repository

:bug: Issues: Open an issue on GitHub

Development & Contributions

This tool was created as part of our development workflow for TOKO to test SNS integration and governance features. We’ve made it available as a standalone tool for the community.

Improvements Welcome: We’re open to pull requests, suggestions, and improvements! If you have ideas for new features or better patterns, we’d love to see them.

Questions?

Feel free to ask questions, share your use cases, or contribute improvements!

8 Likes
2

This sounds awesome @rem.codes, nice job! I’m sure I’ll make extensive use of this soon. Local testing for SNSs seems like an area that was in need of improvement!

@icpp, I wonder if this will come in handy for last minute testing before the ONICAI production launch soon.

2 Likes
3

It sounds great indeed. We will definitely give it a try.

2 Likes
4

I’ve updated the main post to make it a bit easier to read, also made the CLI interactive where you just have to run bash scripts/start.sh and have different options that trigger different scripts.

1 Like