# Welcome to Sonic

Building Game Economies on Solana

> Sonic is the first atomic SVM (Solana Virtual Machine) chain engineered to enable sovereign game economies on Solana. 

It addresses a specific challenge in blockchain gaming: how to run complex games with high performance while maintaining true decentralization. As an atomic Solana Virtual Machine (SVM) chain, Sonic allows games to operate with their own economics while staying connected to Solana's security.

***

#### Sonic's Tech Stack

#### HyperGrid Framework

Sonic's HyperGrid framework transforms this landscape by enabling each game to operate in its own dedicated grid. This means a massively multiplayer game can handle thousands of concurrent player actions, while a trading card game can manage complex card interactions and marketplaces - all running simultaneously without competing for the same blockchain resources.

#### Sorada

Sorada represents a fundamental shift in our approach to SVM data architecture. By decoupling read operations from the core transaction processing pipeline, we've created a system that delivers unprecedented performance improvements for data retrieval.

Our testing shows a 30-40x improvement in read performance compared to standard RPC nodes. For all applications, this translates to response times as low as 5ms for read operations - a game-changing improvement that enables truly responsive blockchain gaming experiences.

#### Rush

Rush is Sonic's Entity-Component-System (ECS) framework, designed to make blockchain game development feel natural and approachable. It takes a declarative approach where game developers define their game's world, entities, and components using simple configuration files, eliminating the need to write complex blockchain code. Rather than requiring developers to learn intricate blockchain concepts, Rush generates all the necessary smart contracts and SDKs from these configurations.

***

Let's explore the Sonic ecosystem together, buckle up, its going to be awesome!!


# Getting Started

Welcome to Sonic!!

Sonic is the first atomic SVM chain built to enable sovereign economies on Solana. 

Built on top of the HyperGrid framework (Solana's first concurrent scaling framework), Sonic's tech stack enables applications to have customized blockspace while maintaining atomic settlement with Solana.


# Setting up your wallet

Your wallet serves as your digital identity on Sonic, allowing you to interact with the blockchain, manage assets, and execute transactions. This guide will walk you through the process of setting up and configuring your wallet for use with Sonic.

### Wallets

You can from the following wallets!

* Visit your wallet's official website
* Download and install the browser extension
* Follow the wallet's setup process to create a new wallet or import an existing one

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Backpack</td><td><a href="/files/f3dWpJbKyN6VY2difwRi">/files/f3dWpJbKyN6VY2difwRi</a></td><td><a href="https://backpack.app/">https://backpack.app/</a></td></tr><tr><td>OKX  Web3 Wallet</td><td><a href="/files/gBRazM7aA1L0QNViN4C3">/files/gBRazM7aA1L0QNViN4C3</a></td><td><a href="https://www.okx.com/zh-hans/web3/wallet/sonic-svm">https://www.okx.com/zh-hans/web3/wallet/sonic-svm</a></td></tr><tr><td>Nightly Wallet</td><td><a href="/files/gl7mxgXGrXNd63UYWLXz">/files/gl7mxgXGrXNd63UYWLXz</a></td><td><a href="https://nightly.app/">https://nightly.app/</a></td></tr><tr><td>Bybit</td><td><a href="/files/nkaOTVj1DQjaYlb05vdk">/files/nkaOTVj1DQjaYlb05vdk</a></td><td><a href="https://www.bybit.com/en/web3/home">https://www.bybit.com/en/web3/home</a></td></tr><tr><td>NuFi</td><td><a href="/files/oSZhmmVcKZMcC1x2Bezw">/files/oSZhmmVcKZMcC1x2Bezw</a></td><td><a href="https://nu.fi/">https://nu.fi/</a></td></tr></tbody></table>


# Bridging funds to Sonic

You can bridge funds to Sonic from Solana using the following bridges&#x20;

<table data-view="cards"><thead><tr><th></th><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Sonic bridge</td><td><a href="https://bridge.sonic.game/">https://bridge.sonic.game/</a></td><td><a href="/files/Q1uQGaXRiNdifaw8yA1t">/files/Q1uQGaXRiNdifaw8yA1t</a></td><td><a href="https://bridge.sonic.game/">https://bridge.sonic.game/</a></td></tr><tr><td>Hyperlane bridge</td><td><a href="https://www.usenexus.org/">https://www.usenexus.org/</a></td><td><a href="/files/ND82gotCyg0FEBkpncBo">/files/ND82gotCyg0FEBkpncBo</a></td><td><a href="https://www.usenexus.org/">https://www.usenexus.org/</a></td></tr><tr><td>Superbridge</td><td><a href="https://sonic-svm.superbridge.app/">https://sonic-svm.superbridge.app/</a></td><td><a href="/files/Qa0lYey3kym1M6v9iq7i">/files/Qa0lYey3kym1M6v9iq7i</a></td><td></td></tr></tbody></table>


# Join Sonic community!

For all latest news and announcements join our Sonic community !

Follow our X: [@SonicSVM](https://x.com/SonicSVM)

Join our [Discord Server](https://discord.gg/eEmTER6qkV)! 😁


# Why Choose Sonic?

#### Lightning Speed at Low Cost

Sonic offers a \[really] fast on-chain game experience amongst all gaming L1s, powered by SVM.

#### Composable Gaming Primitives & Sandbox Environment

Sonic exposes native composable gaming primitives and extensible data types based on the ECS framework on-chain. The game engine sandbox utilities to developers while building their business logic on chain.

#### Monetization Infrastructure

Sonic is natively enabled with growth, traffic, payment & settlement infrastructure for games.


# Getting Started

In this page, you will learn about how to start building on Sonic.

Dive right into Sonic to start building or setup your tooling.

* [**Setup your local environment**](/developers/getting-started/setup-local-development) - Install the Solana CLI to get your local development environment setup
* [**Build & Deploy Your First Sonic Program**](/developers/getting-started/build-and-deploy-your-first-program) - Build and deploy your first on-chain Sonic program, directly in your browser using [Solana Playground](https://beta.solpg.io/).


# Setup local development for Sonic SVM

This quick start guide will demonstrate how to quickly install and set up your local development environment, getting you ready to start developing and deploying Solana programs to the blockchain.

Sonic's local development environment should be very similar to setting up the Solana's local development environment.

## 1. Install the Solana CLI

Follow this [official guide](https://solana.com/developers/guides/getstarted/setup-local-development) to setup the Solana CLI locally. If you already have it setup, you may skip this step.

## 2. Configure your Sonic Cluster&#x20;

After setting up the Solana CLI, you can configure it to point to the Sonic Devnet Cluster for development. Learn more about Sonic's clusters [here](/architecture/clusters).

After installing the Solana CLI you can run the following command to ensure that it's correctly installed.

```bash
solana config get
```


# Build & Deploy Your First Program

This guide provides a step-by-step overview of deploying a program on Sonic SVM. Familiarity with command-line tools is necessary.

## **1. Install CLI Tools**

Ensure that the Solana command line tools are installed as you will be using these tools throughout the deployment process.

## **2. Write Your Program**

Develop your program logic. For those using Rust with Anchor, input your program logic into the `lib.rs` file located in the `src` directory of your project. Confirm that your program compiles correctly and passes all tests.

## **3. Build Your Program**

Compile your program to a BPF (Berkeley Packet Filter) executable, the format required for on-chain programs:

### **With Anchor**

Run `anchor build`. [Anchor](https://www.anchor-lang.com/) manages the compilation details.

### **Without Anchor**

Use `cargo build-bpf` for direct Rust usage.

## **4. Deploy Your Program**

Before deploying your program, ensure your CLI is set to the [Sonic Devnet](/architecture/clusters#devnet) network using the following command:

```bash
solana config set --url https://devnet.sonic.game
```

After deploying your building your program and configuring your RPC URL, you can deploy your program with the following command:

```
solana program deploy <PATH_TO_YOUR_COMPILED_PROGRAM>
```

Ensure that you have enough SOL in your wallet to cover deployment costs. You can get some devnet tokens from the [Sonic faucet](https://faucet.sonic.game).

***

After configuring your network, you may now deploy your program to Sonic. Use the following commands based on your setup:

### **With Anchor**

If the Anchor CLI is installed, you can deploy your program with the following command. This handles the deployment automatically.

```bash
anchor deploy
```

### **Without Anchor**

If you're using the native solana method to author your program, you can also use the Solana CLI to deploy your program.

## **5. Verify Deployment**

Post-deployment, check that your program operates as intended. Interact with your program using Solana's web3.js library or the CLI tools to send transactions.

### **Additional Tips:**

* Keep your program's keypair secure for future upgrades or interactions.
* Monitor the network and your program's performance, particularly if it gains widespread usage.

## **Example: "Hello Sonic!" Program**

This example implements a simple Greeting Counter Program on Sonic.

### With Solana Native Program

```rust
use borsh::{BorshDeserialize, BorshSerialize};
use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint,
    entrypoint::ProgramResult,
    msg,
    program_error::ProgramError,
    pubkey::Pubkey,
};

#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct GreetingAccount {
    pub counter: u32,
}

entrypoint!(process_instruction);

pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    _instruction_data: &[u8],
) -> ProgramResult {
    
    msg!("Hello, Sonic World!");
    
    let accounts_iter = &mut accounts.iter();
    let account = next_account_info(accounts_iter)?;

    if account.owner != program_id {
        msg!("Greeted account does not have the correct program id");
        return Err(ProgramError::IncorrectProgramId);
    }

    let mut greeting_account = GreetingAccount::try_from_slice(&account.data.borrow())?;
    greeting_account.counter += 1;
    greeting_account.serialize(&mut *account.data.borrow_mut())?;
    
    msg!("Greeted {} time(s)!", greeting_account.counter);
    Ok(())
}
```

### With Anchor Program

If you are building with [**Anchor**](https://anchor-lang.com), you may use the variant below. Please remember to change the program ID after building your program with `anchor build` before deploying it.

```rust
use anchor_lang::prelude::*;

// !!! Replace with your program ID after running `anchor build` !!!
declare_id!("<REPLACE_WITH_YOUR_PROGRAM_ID>");

#[program]
pub mod hello_sonic_world {
    use super::*;

    pub fn initialize(ctx: Context<Initialize>, authority: Pubkey) -> Result<()> {
        let greeting_account = &mut ctx.accounts.greeting_account;
        greeting_account.counter = 0;
        greeting_account.authority = authority;
        Ok(())
    }

    pub fn increment_greeting(ctx: Context<IncrementGreeting>) -> Result<()> {
        msg!("Hello, Sonic World!");

        let greeting_account = &mut ctx.accounts.greeting_account;
        greeting_account.counter += 1;

        msg!("Greeted {} time(s)!", greeting_account.counter);
        Ok(())
    }
}

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(init, payer = user, space = 8 + 4 + 32)]
    pub greeting_account: Account<'info, GreetingAccount>,
    #[account(mut)]
    pub user: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct IncrementGreeting<'info> {
    #[account(mut, has_one = authority)]
    pub greeting_account: Account<'info, GreetingAccount>,
    pub authority: Signer<'info>,
}

#[account]
pub struct GreetingAccount {
    pub counter: u32,
    pub authority: Pubkey,
}

```

## **Run your dAPP on Sonic Devnet**

Example "Hello World" application in TypeScript:

### With Solana Native Program dApp

```typescript
import {
  Connection,
  PublicKey,
  Keypair,
  Transaction,
  TransactionInstruction,
  SystemProgram,
  sendAndConfirmTransaction
} from '@solana/web3.js';
import bs58 from 'bs58';
import * as borsh from 'borsh';

class GreetingAccount {
  counter = 0;
  constructor(fields?: { counter: number }) {
    if (fields) {
      this.counter = fields.counter;
    }
  }
}

const GreetingSchema = new Map([
  [GreetingAccount, { kind: 'struct', fields: [['counter', 'u32']] }]
]);

const programId = new PublicKey('<REPLACE_WITH_YOUR_PROGRAM_ID>');
const connection = new Connection('https://devnet.sonic.game', 'confirmed');
const feePayer = Keypair.fromSecretKey(
  bs58.decode(
    '<REPLACE_WITH_YOUR_PRIVATE_KEY>'
  )
);

async function sayHello() {
  const GREETING_SIZE = borsh.serialize(
    GreetingSchema,
    new GreetingAccount()
  ).length;

  const greetedAccountKeypair = new Keypair();
  const greetedAccountPubkey = greetedAccountKeypair.publicKey;

  const lamports =
    await connection.getMinimumBalanceForRentExemption(GREETING_SIZE);

  const createGreetingAccountIx = SystemProgram.createAccount({
    fromPubkey: feePayer.publicKey,
    lamports,
    newAccountPubkey: greetedAccountPubkey,
    programId: programId,
    space: GREETING_SIZE
  });

  // Create greet instruction
  const greetIx = new TransactionInstruction({
    keys: [
      {
        pubkey: greetedAccountPubkey,
        isSigner: false,
        isWritable: true
      }
    ],
    programId
  });

  const transaction = new Transaction().add(createGreetingAccountIx, greetIx);

  const txHash = await sendAndConfirmTransaction(connection, transaction, [
    feePayer,
    greetedAccountKeypair
  ]);
  console.log(`Use 'solana confirm -v ${txHash}' to see the logs`);

  const greetingAccount = await connection.getAccountInfo(greetedAccountPubkey);
  // Deserialize the account data
  const deserializedAccountData = borsh.deserialize(
    GreetingSchema,
    GreetingAccount,
    greetingAccount!.data
  );

  console.log(
    'Sonic Greeting successful. Account data:',
    deserializedAccountData
  );
}

sayHello()
  .then(() => console.log('Done'))
  .catch(console.error);
```

### With Anchor Program dApp

```rust
import {
  Connection,
  PublicKey,
  Keypair,
  Transaction,
  SystemProgram,
  sendAndConfirmTransaction
} from '@solana/web3.js';
import { Program, AnchorProvider, web3 } from '@project-serum/anchor';
import { IDL } from './idl/hello_sonic_world.json'; // Make sure you have the correct IDL file

const programId = new PublicKey('<REPLACE_WITH_YOUR_PROGRAM_ID>');
const connection = new Connection('https://devnet.solana.com', 'confirmed');
const feePayer = Keypair.fromSecretKey(
  bs58.decode('<REPLACE_WITH_YOUR_PRIVATE_KEY>')
);

// Anchor setup
const wallet = new AnchorProvider(connection, feePayer, {
  preflightCommitment: 'confirmed',
});

const program = new Program(IDL, programId, wallet);

async function sayHello() {
  // Create the greeting account
  const greetedAccountKeypair = Keypair.generate();
  const greetedAccountPubkey = greetedAccountKeypair.publicKey;

  const lamports = await connection.getMinimumBalanceForRentExemption(
    8 + 4 + 32 // space for the account (discriminator, counter, and authority)
  );

  const createGreetingAccountIx = SystemProgram.createAccount({
    fromPubkey: feePayer.publicKey,
    lamports,
    newAccountPubkey: greetedAccountPubkey,
    programId: program.programId,
    space: 8 + 4 + 32, // size of the GreetingAccount (8 discriminator + 4 counter + 32 authority)
  });

  const transaction = new Transaction().add(createGreetingAccountIx);

  await sendAndConfirmTransaction(connection, transaction, [
    feePayer,
    greetedAccountKeypair,
  ]);

  console.log(`Greeting account created with public key: ${greetedAccountPubkey.toBase58()}`);

  // Initialize the greeting account
  await program.rpc.initialize(feePayer.publicKey, {
    accounts: {
      greetingAccount: greetedAccountPubkey,
      user: feePayer.publicKey,
      systemProgram: SystemProgram.programId,
    },
    signers: [greetedAccountKeypair, feePayer],
  });

  console.log('Greeting account initialized');

  // Increment the greeting counter
  await program.rpc.incrementGreeting({
    accounts: {
      greetingAccount: greetedAccountPubkey,
      authority: feePayer.publicKey,
    },
  });

  console.log('Greeting incremented');

  // Fetch the account data
  const account = await program.account.greetingAccount.fetch(
    greetedAccountPubkey
  );

  console.log('Greeting successful. Account data:', account);
}

sayHello()
  .then(() => console.log('Done'))
  .catch(console.error);
```

***

Running the above script \[either with Solana Native, or with Anchor] programs should output the following:

```bash
Use 'solana confirm -v TsCwj8s8meQFSfqUKdHqDQVzfUbqRcugP2gJ5kaGCj4v4D7aKvohqQQncvUFunqZVH9sS6jhESMjwe6SHGPfrXf' to see the logs
Sonic Greeting successful. Account data: GreetingAccount { counter: 1 }
Done
```

You can find an example of the executed transaction [here](https://explorer.sonic.game/tx/TsCwj8s8meQFSfqUKdHqDQVzfUbqRcugP2gJ5kaGCj4v4D7aKvohqQQncvUFunqZVH9sS6jhESMjwe6SHGPfrXf). The program address for this program is [here](https://explorer.sonic.game/address/BoiBFQbz4ux1rHvAhXEFgujCS57QLby6HxhvBMCp3vkp).


# Developer Tooling

In this section you will find some helpful information to help you during development. We have created some resources to make the development experience as smooth as butter:

1. [**Sonic Explorer**](/developers/developer-tooling/explorer) - A web-based tool that provides detailed insights into the Solana blockchain, allowing users to view transactions, accounts, blocks, and network statistics in real-time.
2. [**Sonic Faucet**](/developers/developer-tooling/faucet) - A web-based tool that airdrops development SOL for facilitating transaction fees on Sonic Devnet environment.
3. [**Wallet Extensions**](/developers/developer-tooling/wallet-extensions) - If you're building on Sonic for the browser, we have curated a list of recommended browser wallets for Sonic. Support for more wallets is continuously on-going.
4. [**Kronus**](https://kronus.sonic.game/) - We recommend you deploy program updates with a multisig program authority.


# Explorer

{% hint style="success" %}
Check Sonic Explorer Here: <https://explorer.sonic.game>
{% endhint %}

An explorer is a web-based tool that allows users to search and analyze a blockchain's data in real-time. The Sonic explorer is crucial for developers, validators, and users alike, providing visibility into transactions, accounts, block production, and more.&#x20;

Here are some of the key features and uses of the Sonic Explorer:

1. **Transaction Details**: You can search for and view details of specific transactions, including the sender, receiver, amount transferred, and fees paid.
2. **Account Information**: Explorers provide detailed information on accounts on Sonic, including balance, transaction history, and associated smart contracts.
3. **Block Information**: Users can view details about individual blocks such as the block producer, the transactions included in the block, and the time of production.
4. **Network Statistics**: Sonic explorers often display overall network statistics such as the current transaction rate, total number of validators, and network uptime.
5. **Smart Contracts and Programs**: They allow for inspection of deployed smart contracts and programs on Sonic, showing the code and interactions over time.
6. **Real-time Monitoring and Alerts**: Some explorers offer features like real-time monitoring of network events and alerts for specific transaction activities.

<figure><img src="/files/B1NjeprtAavET3RnzdHb" alt=""><figcaption></figcaption></figure>


# Faucet

{% hint style="success" %}
Check Sonic Faucet Here: <https://faucet.sonic.game>
{% endhint %}

A faucet is a service that distributes free tokens, typically used in test environments like testnets or devnets, to enable developers to test their applications without spending real money.

These tokens have no real-world value but are essential for simulating transactions, testing smart contracts, and ensuring that applications function correctly in a controlled environment.


# Wallet Extensions

Below are some wallets that natively support the Sonic network.

{% hint style="info" %}
We are constantly growing the list of wallets with native support for Sonic.
{% endhint %}

You can from the following wallets!

* Visit your wallet's official website
* Download and install the browser extension
* Follow the wallet's setup process to create a new wallet or import an existing one

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Backpack</td><td><a href="/files/f3dWpJbKyN6VY2difwRi">/files/f3dWpJbKyN6VY2difwRi</a></td><td><a href="https://backpack.app/">https://backpack.app/</a></td></tr><tr><td>OKX  Web3 Wallet</td><td><a href="/files/gBRazM7aA1L0QNViN4C3">/files/gBRazM7aA1L0QNViN4C3</a></td><td><a href="https://www.okx.com/zh-hans/web3/wallet/sonic-svm">https://www.okx.com/zh-hans/web3/wallet/sonic-svm</a></td></tr><tr><td>Nightly Wallet</td><td><a href="/files/gl7mxgXGrXNd63UYWLXz">/files/gl7mxgXGrXNd63UYWLXz</a></td><td><a href="https://nightly.app/">https://nightly.app/</a></td></tr><tr><td>Bybit</td><td><a href="/files/nkaOTVj1DQjaYlb05vdk">/files/nkaOTVj1DQjaYlb05vdk</a></td><td><a href="https://www.bybit.com/en/web3/home">https://www.bybit.com/en/web3/home</a></td></tr><tr><td>NuFi</td><td><a href="/files/oSZhmmVcKZMcC1x2Bezw">/files/oSZhmmVcKZMcC1x2Bezw</a></td><td><a href="https://nu.fi/">https://nu.fi/</a></td></tr></tbody></table>

## Wallet Extension Developers

If you are a wallet developer, and you would like to add Sonic to your wallet, after adding it, please [shoot us a DM](https://twitter.com/sonicsvm) and we can add you to the list of supported wallets.


# Additional Tools & Examples

As Sonic's ecosystem is growing, more native Solana tools are becoming available on Sonic as well.&#x20;

| Tools                     | Description                                   | Docs link                                                                                                                            | Program Addresses                            |
| ------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| Metaplex's Token Metadata | NFT Standard.                                 | [Docs](https://developers.metaplex.com/token-metadata)                                                                               |                                              |
| Metaplex's Candy Machine  | Launch your own NFT collection.               | [Docs](https://developers.metaplex.com/candy-machine)                                                                                |                                              |
| Metaplex's Core           | NFT Standard                                  | [Docs](https://developers.metaplex.com/core)                                                                                         |                                              |
| Metaplex's Bubblegum      | Compressed NFTs                               | [Docs](https://developers.metaplex.com/bubblegum)                                                                                    |                                              |
| Pyth ( Receiver )         | Allows users to post Pyth Price updates       | [Docs](https://github.com/pyth-network/pyth-crosschain/blob/e399a0325f81ee55f678df605d4b2dd6e7fbb01f/target_chains/solana/README.md) | rec5EKMGg6MxZYaMdyBfgwp4d5rB9T1VQH5pJv5LtFJ  |
| Pyth ( Price Feed )       | Fetch Price Feeds for all the your Defi needs | [Docs](https://docs.pyth.network/price-feeds/use-real-time-data/solana)                                                              | pythWSnswVUd12oZpeFP8e9CVaEqJg25g1Vtc2biRsT  |
| Pyth Price Feed IDs       | All Pyth Price Feed IDs at one place          | [Docs](https://www.pyth.network/developers/price-feed-ids)                                                                           |                                              |
| Feed                      | Onchain provable randomness                   | [Docs](https://feed-protocol.gitbook.io/docs)                                                                                        | FEED1qspts3SRuoEyG29NMNpsTKX8yG9NGMinNC4GeYB |
| Sonic Agent Kit           | Make LLMs do interactions on Sonic            | [Github](https://github.com/sendaifun/sonic-agent-kit)                                                                               |                                              |
| Privy                     | Embedded Wallets                              | [Docs](https://docs.privy.io/guide/react/wallets/usage/solana/#custom-svm)                                                           |                                              |
| Damn Fun                  | Build and deploy AI-native games              | [Docs](https://docs.digimon.tech/digimon) , [Example](https://github.com/CohumanSpace/damn-example)                                  |                                              |
| MPC Vault                 | Multichain Multisig Wallet                    | [Website](https://mpcvault.com/)                                                                                                     |                                              |
| Kronos                    | SonicSVM Native Multisig                      | [Website](https://kronus.sonic.game/)                                                                                                |                                              |


# Additional Resources

All important links at one place

SonicSVM has complete portability for Solana programs, so if you are building for Solana, you can deploy it to Solana without doing any code changes. You would just require to change the RPC URL and deploy there.

#### Wallets Support List

* [Backpack](https://backpack.app/)
* [Nightly](https://nightly.app/)
* [OKX](https://www.okx.com/zh-hans/web3/wallet/sonic-svm)
* [Bybit](https://www.bybit.com/en/web3/home)
* [NuFi](https://nu.fi/)

#### Important Links

\
RPC URLs

|                   |                                               |
| ----------------- | --------------------------------------------- |
| Mainnet           | <https://rpc.mainnet-alpha.sonic.game>        |
| Secondary Mainnet | <https://api.mainnet-alpha.sonic.game>        |
| Helius            | <https://sonic.helius-rpc.com/>               |
| Mainnet gRPC      | <https://grpc.mainnet-alpha.sonic.game:10000> |
| Testnet           | <https://api.testnet.sonic.game/>             |

We support 300 requests per second across all the *mainnet-alpha.sonic.game* domain.

Bridges

|                 |                                      |
| --------------- | ------------------------------------ |
| Sonic           | <https://bridge.sonic.game/>         |
| Hyperlane       | <https://www.usenexus.org/>          |
| Superbridge     | <https://sonic-svm.superbridge.app/> |
| Orbiter Finance | <https://www.orbiter.finance/>       |

Additional Links

|          |                                |
| -------- | ------------------------------ |
| Faucet   | <https://faucet.sonic.game/#/> |
| Explorer | <https://explorer.sonic.game/> |

#### Developer Docs, Libraries and Frameworks

| Tools                        | Usage                                                 | Language          | Links                                                                               |
| ---------------------------- | ----------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| Sonic Code Examples          | Learn how to do basic interactions on Sonic           | Typescript & Rust | <https://github.com/mirrorworld-universe/sonic-code-examples>                       |
| Sonic Agent Kit              | Connect any AI agents to sonic protocols              | Typescript        | <https://github.com/sendaifun/sonic-agent-kit>                                      |
| Kronos                       | SonicSVM Native MultiSig, great for managing treasury | Webapp            | <https://kronus.sonic.game/>                                                        |
| SolanaWeb3JS                 | Client side interactions for all things SVM.          | Typescript        | <https://solana-labs.github.io/solana-web3.js/>                                     |
| Sonic Wallet Adapter Example | Code snippet to connect Sonic wallets on a Next App.  | Typescript        | <https://github.com/Saviour1001/SuperSonicWallet>                                   |
| Anchor                       | Smart Contracts Framework                             | Rust              | <https://www.anchor-lang.com/docs>                                                  |
| Steel                        | Smart Contracts Framework                             | Rust              | <https://github.com/regolith-labs/steel>                                            |
| Sol Playground               | Online Smart Contract IDE                             | Rust              | <https://beta.solpg.io/>                                                            |
| Privy                        | Embedded Wallets                                      | Typescript        | [Docs](https://docs.privy.io/guide/react/wallets/usage/solana/#custom-svm)          |
| Metaplex                     | All things NFTs                                       | Typescript & Rust | <https://developers.metaplex.com/>                                                  |
| Pyth                         | Real time price feed oracles                          | Typescript & Rust | <https://www.pyth.network/>                                                         |
| Solana Cookbook              | Code snippets to do different types of interactions   | Typescript & Rust | <https://solana.com/developers/cookbook>                                            |
| Solders                      | Python tool kit                                       | Python            | <https://github.com/kevinheavey/solders>                                            |
| EspressoCash                 | Dart tool kit                                         | Dart              | <https://github.com/espresso-cash/espresso-cash-public/tree/master/packages/solana> |

#### Resources to learn more about SVM

* How Solana works - <https://report.helius.dev/>
* Solana Docs - <https://solana.com/docs>
* Helius Blog ( covers a lot of SVM topics ) - <https://www.helius.dev/blog>

{% hint style="info" %}
You can take any code snippet from existing code snippets of Solana change the RPC URL to Sonic and redeploy your smart contracts.

For client-side code, you just have to change the RPC URL as well and you can use any of the libraries mentioned above.&#x20;

For more help, you can join our [discord](https://discord.com/invite/eEmTER6qkV).
{% endhint %}


# Overview

Welcome to Sonic!!

Sonic is the first atomic SVM chain built to enable sovereign economies on Solana.&#x20;

Built on top of the HyperGrid framework (Solana's first concurrent scaling framework), Sonic's tech stack enables applications to have customized blockspace while maintaining atomic settlement with Solana.


# Sonic SVM Whitepaper

> Whitepaper Link: [Github](https://github.com/mirrorworld-universe/reports/blob/master/Sonic%20SVM%20%E2%80%93%20A%20HyperGrid%20Scaling%20Future%20of%20Solana.pdf)

\
More technicals & Governance

1. [Sonic Hypergrid Technical Roadmap](https://github.com/mirrorworld-universe/reports/blob/master/Sonic%20SVM%20%E2%80%93%20HyperGrid%20Technical%20Detailed%20Roadmap.pdf)
2. [Sonic Governance Framework](https://github.com/mirrorworld-universe/reports/blob/master/Sonic%20Governance%20Framework.pdf)


# Vision & Architecture

The Sonic Vision

Sonic envisions a future where blockchain games operate with:

* True sovereignty over their game economies
* Unprecedented performance and scalability
* Seamless integration with existing game development workflows
* Complete composability with the Solana ecosystem

### Architectural Philosophy

Sonic's architecture is built on three fundamental pillars:

#### 1. State Sovereignty

Each game ecosystem operates within its own specialized Grid, enabling:

* Independent state management
* Custom execution environments
* Optimized performance characteristics
* Flexible resource allocation

#### 2. Horizontal Scalability

True scaling is achieved through:

* Multi-grid concurrent execution
* Dynamic resource allocation
* Parallel transaction processing
* Grid specialization


# Clusters

On this page you will find cluster related information that will allow you to interact with Sonic.

Sonic has several different groups of validators, known as **Clusters**. Each serving different purposes within the overall ecosystem and containing dedicated api nodes to fulfill **JSON-RPC** requests for their respective Cluster.

The individual nodes within a Cluster are owned and operated by third parties, with a public endpoint available for each.

## Links

<table><thead><tr><th width="227">Network Name</th><th>Sonic Testnet</th></tr></thead><tbody><tr><td>Mainnet Alpha </td><td><a href="https://api.mainnet-alpha.sonic.game">https://api.mainnet-alpha.sonic.game</a></td></tr><tr><td>Helius RPC URL</td><td><a href="https://sonic.helius-rpc.com/">https://sonic.helius-rpc.com/</a></td></tr><tr><td>Testnet RPC URL</td><td><a href="https://api.testnet.sonic.game">https://api.testnet.sonic.game</a></td></tr><tr><td>Faucet URL</td><td><a href="https://faucet.sonic.game">https://faucet.sonic.game</a></td></tr><tr><td>Block Explorer URL</td><td><a href="https://explorer.sonic.game">https://explorer.sonic.game</a></td></tr></tbody></table>


# HyperGrid Framework

Introducing HyperGrid – a rollup scaling and orchestration framework for dedicated Solana Virtual Machine (SVM) ecosystem rollup operators.

HyperGrid protocol is a rollup scaling and orchestration framework for dedicated Solana Virtual Machine (SVM) ecosystem rollup operators. HyperGrid utilizes state compression and Byzantine Fault Tolerance (BFT) to achieve potentially infinite transaction throughput by enabling horizontal scaling across multiple grids, exemplified by Sonic – a gaming-specific grid that settles on Solana.

Among other things, a key feature of HyperGrid is [**Atomic Interoperability**](/architecture/hypergrid-framework/interoperability-with-solana). HyperGrid is designed to be interoperable with Solana. It implements an interoperability interface that allows for wholly encapsulated programs on Solana to delegate execution to Grids orchestrated by HyperGrid. This approach offers several benefits:

* Creates a single source of truth for all programs running on Solana
* Facilitates the delegation of program computation to HyperGrid
* Enables rollups to benefit from the Base layer's services and liquidity


# HyperGrid Infrastructure

An in-depth analysis of the HyperGrid Framework

This section will provide an in-depth analysis of the technical solution centered around the HyperGrid Shared State Network (HSSN). This comprehensive document will cover several key aspects:

1. A reimagining of the HyperGrid's data interaction pathways, detailing how information flows through the system.
2. An exploration of the Shared State Network's crucial role in orchestrating and administering various components of the solution.
3. A thorough design-level breakdown of the necessary products and development tasks. This will outline what needs to be built and how, ensuring all required functionalities are implemented.

The primary aim of this document is to lay out a clear, actionable blueprint for the successful deployment and integration of the HyperGrid technical solution. It will serve as a guiding resource for developers, architects, and stakeholders involved in bringing this innovative system to life.

{% content-ref url="/pages/URD6MrKfzoE0z7EW344a" %}
[Architectural Overview](/architecture/hypergrid-framework/hypergrid-infrastructure/architectural-overview)
{% endcontent-ref %}

{% content-ref url="/pages/5vfrE40GI3gAfWUSNHa6" %}
[Grids and Network Relationships](/architecture/hypergrid-framework/hypergrid-infrastructure/grids-and-network-relationships)
{% endcontent-ref %}


# Architectural Overview

HyperGrid's multi-grid architecture overview: semi-autonomous grids anchored to Solana for consensus and finality.

HyperGrid's architecture is predicated on a multi-grid approach, wherein each grid operates semi-autonomously while remaining anchored to the Solana mainnet for consensus and finality. This section will dissect the structural elements and their interrelations.

<figure><img src="/files/LEdApuDf8gLb7Rks37Wr" alt=""><figcaption><p>HyperGrid System Architecture</p></figcaption></figure>

### Key Components

1. **Solana Base Layer**: The foundation upon which the HyperGrid system is built, providing ultimate consensus and finality.
2. **HyperGrid Shared State Network (HSSN)**:
   * Central to the architecture, spanning across all grids
   * Contains multiple validators (Validator 1 through Validator N)
   * Facilitates sharing of states between Grids and the Solana Base Layer
   * Manages batch ZK proofs for settlement
3. **Grid Structure** (exemplified by Grid 1 and Grid 2):
   * Each grid represents a semi-autonomous ecosystem, potentially dedicated to specific applications (e.g., different games)
   * Components within each grid:
     * **ZK-Coprocessor**: Manages grid-specific operations merkle proof operations.
     * **SVM Runtime**: Execution environments for Grids on Solana Virtual Machine
     * **Sonic Gas Engine**: Manages computational resources
     * **Concurrent Merkle Tree Generator**: Efficiently processes state transitions
4. **User Interaction**:
   * Users can interact with each grid independently
   * Transactions (SVM Tx and EVM Tx) flow between users and the respective grid's runtimes
   * Transaction responses are sent back to users

### Data Flow

1. **Interoperability – State Sharing**:
   * Bi-directional state sharing occurs between the Solana Base Layer and the HSSN
   * HSSN shares states with individual grids
   * State sharing can also happen between Grids as we shall see later
2. **ZK Proofs**:
   * Transactions are compressed and aggregated into a Merkle tree.
   * For each block, we shall commit the corresponding root state hash.
   * The Validity Proof for this block is computed on Grid.
   * ZK proofs for settlement are posted from the HSSN to the Solana Base Layer.

This architecture enables HyperGrid to achieve high scalability and flexibility while maintaining a strong connection to the security and finality provided by the Solana blockchain.


# Grids and Network Relationships

HyperGrid's network architecture: Shared State Network, Grid instances, and Solana Base Layer relationships for scalable dApp deployment.

<figure><img src="/files/yLfLuL9v062nEmkttSYq" alt=""><figcaption><p>HyperGrid Shared State Network Data Flow</p></figcaption></figure>

The HyperGrid framework is designed to support a wide array of application-specific networks, or decentralized applications, with a particular focus on high-demand applications like games, DeFi, AI Agents, e.t.c. within its ecosystem. This architecture aims to:

1. Reduce strain on the Solana Base Layer's performance
2. Minimize performance conflicts and competition for block-space inclusion between Base Layer and the various domain-specific dApps.

{% hint style="info" %}
HyperGrid makes it possible for dApps or operators to either instantiate their own Grid instance for their specific application or implement their own domain-specific SVM network.

[Click this link to learn more about Grids](/architecture/hypergrid-framework/hypergrid-infrastructure/grids-and-network-relationships/grids).
{% endhint %}

### Key Features

* **Flexibility for Grid Network Creators**: Developers can choose between:
  * Using the HyperGrid public network
  * Horizontally scaling to create dedicated networks tailored to specific needs
* **Performance and Cost Optimization**: The choice between public and dedicated networks is based on developers' assessments of performance requirements and associated costs.
* **Network Independence**: Developers can deactivate their respective networks without affecting others in the ecosystem.

### Operational Framework

* **Validation**: Each network autonomously handles the validation of its transactions and state changes.
* **Logging**: Transaction and state alteration logs are maintained independently by each network.
* **Retrieval**: Data retrieval processes are executed autonomously for each network.

### Integration with Solana

The linkage between HyperGrid and the Solana Base Layer ensures that all operations, while processed independently within each Grid instance, ultimately anchor to Solana for final consensus and security.

This architecture provides a scalable and flexible environment for dApp deployment, allowing developers to optimize their applications' performance while leveraging the security and stability of the Solana blockchain.


# Grids

## Definition

A Grid in the HyperGrid architecture is a semi-autonomous network within the larger HyperGrid framework, designed to host and operate particularly high-demand application-specific use cases. Examples include Gaming, DeFi, on-chain AI Agents or applications-specific networks.

Sonic is an example of a Grid optimized for high-performance gaming. A Grid can take on the form a single node, or an entire cluster

## Characteristics of a Grid

&#x20;Here are the key characteristics of a Grid:

1. **Semi-autonomous operation**: Each Grid functions independently to a large extent, but remains connected to the overall HyperGrid system.
2. **Dedicated resources**: A Grid has its own set of components, including:
   * A ZK-coprocessor for managing grid-specific operations
   * A local BlockStore (also referred to as "Bank - local") for handling account and program data
   * Runtime environments (like Sonic SVM Runtime and Sonic EVM Runtime)
   * A Concurrent Merkle Tree Generator for efficient state transitions
3. **State sharing**: Grids interact with the HyperGrid Shared State Network, synchronizing states to maintain consistency across the system.
4. **User interaction**: Users can interact directly with a Grid, sending transactions and receiving responses.
5. **Scalability**: Grids allow for horizontal scaling, enabling developers to create dedicated networks tailored to their specific requirements.
6. **Performance isolation**: By separating dApps into different Grids, the system can mitigate performance conflicts between applications and reduce strain on the Solana Base Layer.
7. **Flexibility**: Developers can choose to use the public HyperGrid network or create their own dedicated Grid based on performance needs and cost considerations.
8. **Independent lifecycle**: A Grid can be activated or deactivated without affecting other Grids in the system.
9. **SVM Client Diversity:** HyperGrid is client-agnostic, meaning that it can be used with any SVM client implementation. This makes it possible for network operators on Solana to implement high-performance SVM clients while relying on HyperGrid's Shared State Network (HSSN) for consensus and interoperability.

In essence, a Grid serves as a scalable, flexible, and semi-independent cluster of nodes or an environment within the HyperGrid system, designed to host and manage specific dApps while maintaining a connection to the overall HyperGrid architecture and the Solana Base Layer.


# Interoperability with Solana

Seamless asset and data exchange, cross-layer operations, and ecosystem expansion

## Interoperability with Base Layer

The interoperability between HyperGrid and Solana refers to the capability of the two systems to communicate and exchange information and assets seamlessly. This integration enables users and developers to operate across different layers without friction, significantly enhancing the overall capabilities of the Solana blockchain ecosystem.

### Key Aspects of Interoperability

1. **Cross-Layer Operations**:
   * Deploy once. Run forever – Deploy programs in Solana, while executing your transactions on your Grid.
   * Engage in high-performance transactions (e.g. trading) on HyperGrid Networks with secure settlement on Solana Base Layer.
2. **Inter-Grid Asset Transfer**:
   * Transfer assets and data across different Grids within HyperGrid.
3. **Seamless User Experience**:
   * Users can interact with both systems as if they were a single, unified platform.

### Benefits of Interoperability

1. **Enhanced Scalability**:
   * HyperGrid extends Solana's transaction processing capabilities.
2. **Improved Security**:
   * Leverages Solana's robust security for final settlement.
3. **Increased Liquidity**:
   * Allows for fluid movement of assets between layers.
4. **Higher Availability**:
   * Distributes load across multiple systems, reducing downtime risks.
5. **Ecosystem Growth**:
   * Fosters collaboration and development among dApps running on HyperGrid.

### Impact on Solana Ecosystem

Interoperability is crucial for expanding the overall capabilities of the Solana blockchain. It allows the ecosystem to:

* Handle a higher volume of transactions
* Support more complex applications
* Provide a more diverse range of services
* Attract a wider user and developer base

By enabling seamless interaction between HyperGrid and Solana, the interoperability feature creates a more robust, flexible, and powerful blockchain environment, capable of meeting the diverse needs of modern decentralized applications.


# Data Synchronization Between HyperGrid and Solana Base Layer

Step-by-step flow of reading data from and synchronizing updates to the Solana Base Layer within the HyperGrid architecture.

## Reading Data from Solana to HyperGrid

<figure><img src="/files/dl834RtW8VQS6IVx0GO4" alt=""><figcaption><p>Reading Data from Solana to HyperGrid</p></figcaption></figure>

The diagram above illustrates the following flow when performing state synchonization from Solana to a Grid on HyperGrid, like Sonic.

1. Initial loading: A pre-existing Solana program is loaded from Storage into HyperGrid's Cache.
2. User sends a read request for a specific program to HyperGrid's Sonic RPC.
3. Synchronization Program checks the Cache for the requested Program, but it's not found.
4. Synchronization Program sends a request to Solana Base Layer RPC for the Program.
5. Solana Base Layer responds with the Program data.
6. Synchronization Program receives the response and updates HyperGrid's Cache with the new Program data.
7. Synchronization Program sends the read response back to Sonic RPC.
8. Sonic RPC forwards the read response to the User.

## Synchronizing Updates Back to the Solana Base Layer

<figure><img src="/files/CwyhrQOwvw7T8Wevo5VP" alt=""><figcaption><p>Synchronizing Updates from Grid to Base Layer</p></figcaption></figure>

The diagram above illustrates the following flow when performing state synchonization from a Grid on HyperGrid \[like Sonic], back to Solana.

1. Initial loading: A pre-existing Program is loaded from Storage into HyperGrid's Cache.
2. User sends a write request for a specific Program to HyperGrid's Sonic RPC.
3. Synchronization Program checks the Cache for the requested Program, but it's not found.
4. Synchronization Program sends a request to lock the program on the Solana Base Layer.
5. Solana Base Layer RPC locks the requested Program.
6. Solana Base Layer responds with the Program data.
7. Synchronization program receives the response and updates HyperGrid's Cache with the new program data.
8. Synchronization Program sends a request to release the lock and write the updated data for the Program to the Solana Base Layer.
9. Solana Base Layer RPC releases the lock and writes the updated data.
10. Synchronization Program sends the write response back to Sonic RPC.
11. Sonic RPC forwards the write response to the User.


# HyperGrid Shared State Network (HSSN)

Overview of the HyperGrid Shared State Network (HSSN), its architecture, and its role in managing state and communication across Grids and the Solana base layer.

## Introduction

The HyperGrid Shared State Network (HSSN) is a crucial component in the Grid ecosystem. It serves as a consensus layer, communication hub and state management cluster, facilitating interactions between Grids and the Solana base layer. This network manages the state for all communications, including periodic synchronization of block data from Grid Rollups to the Solana base layer.

![HSSN Architecture Overview](/files/WAQdg4W6BgkgA60aviS8)

### Key Components and Features

1. **HSSN Architecture**: Built on the Cosmos framework, ensuring reliability and security in cross-chain communications.
2. **Data Structures**: Manages states between Grids and the Solana base layer, including:
   * Grid registration
   * Communication data sources
   * Versioning
   * Read/write states
3. **Extended Account Data Fields**: Augments native Solana base layer account data fields to accommodate new fields managed by HSSN, ensuring synchronization with Grid account states.
4. **Refactored Grid RPC**: Enables direct communication between Grids and the HSSN, facilitating interoperability within the ecosystem.
5. **Gas Charging and Allocation Mechanism**:
   * Users pay gas fees for certain Grid requests
   * A specialized Grid (Sonic Grid) runs a gas calculation program
   * Centrally manages gas across the entire Grid ecosystem

![Gas Charging and Allocation Mechanism](/files/bfCkZhq2VbMUHVUTPOE9)

### Interactions and Data Flow

1. **Grid-to-HSSN Communication**:
   * Grids send state updates to HSSN
   * HSSN synchronizes states across Grids
2. **HSSN-to-Solana Base Layer**:
   * Periodic synchronization of block data as rollups
   * Management of extended account data fields
3. **Inter-Grid Communication**:
   * HSSN facilitates state sharing between different Grids
4. **Gas Management**:
   * Sonic Grid calculates and allocates gas fees
   * Regular synchronization of gas billing records with HSSN
   * Allocation of funds to Grid accounts, HSSN accounts, and official accounts based on billing records

### Relationship to Other Components

The HSSN plays a central role in the Grid ecosystem, interacting closely with:

* Individual Grids
* Solana Base Layer
* Gas Calculation Program (Sonic Grid)

By serving as a consensus layer for state management and communication, the HSSN enhances the scalability, interoperability, and efficiency of the entire Grid ecosystem.


# HSSN Explorer Overview

Comprehensive guide to the Hypergrid Shared State Network (HSSN) dashboard, detailing its key features and data visualization across multiple pages.

## Introduction

The Hypergrid Shared State Network (HSSN) is a Cosmos-based network that operates between the Grid and the Solana Base Layer. It manages state for all communications, including inter-grid interactions and periodic synchronization of block data from the grid as a rollup to the Solana base layer.

To monitor the HSSN's operations, a dedicated dashboard has been provisioned.&#x20;

{% hint style="info" %}
You can access the HSSN Explorer dashboard at: <https://explorer-hssn.hypergrid.dev/>
{% endhint %}

{% embed url="<https://drive.google.com/file/d/13y-B5pgrdlKZ5HvMqUvviO-uPJCg_ike/view?usp=sharing>" %}

## Dashboard Pages

### 1. Home Page

<figure><img src="/files/Ao9IZMdiikngHOUz2R05" alt=""><figcaption></figcaption></figure>

The Home page provides an overview of the entire HSSN:

* Latest Block Height
* Latest Block Time
* Network Name (currently "hypergridssn")
* Number of Validators
* Connection diagram showing communication flow between grids and Solana through the HSSN

### 2. Grids Page

Displays all nodes in the HSSN:

* Name
* Role (Solana, HSSN, Sonic Grid, or Grid)
* RPC interface
* Public key
* Data account
* Start time

### 3. Syncs Page

<figure><img src="/files/gh6i8IGFTQAgGi3NWcJQ" alt=""><figcaption></figcaption></figure>

Shows synchronization data between Grid nodes and Solana:

* ID
* Grid name
* Account information
* Slot number
* Transaction hash
* Creator account

### 4. Blocks Page

<figure><img src="/files/ktlALy6zQtpfij88w8Wh" alt=""><figcaption></figcaption></figure>

Presents blockchain information within the HSSN:

* Block tab: Height, App Hash, Number of transactions, Creation time
* Transactions tab: TX Hash, Result, Messages, Height, Time

<figure><img src="/files/dFCim4et7loAVlZHl914" alt=""><figcaption><p>Transactions Tab</p></figcaption></figure>

### 5. Validators Page

<figure><img src="/files/MDKiEF7GJ1v1tXDCEkGd" alt=""><figcaption></figcaption></figure>

Provides information about HSSN validators:

* Validator name
* Status
* Voting power

### 6. Shared Accounts Page

<figure><img src="/files/IrbK8XtscfK0Ci3tvtDW" alt=""><figcaption></figcaption></figure>

Lists communication status information within the HSSN:

* Address
* Source node
* Slot
* Account info
* Creator
* Version

### 7. Fee Page

Displays fee bills and settlement records:

* Grid Block Fee tab: Original transaction fee records
* Fee Settlement tab: Periodic settlement records based on fee bills

<figure><img src="/files/2vwx2oWoGjPfpEBvlLBR" alt=""><figcaption><p>Fee Page</p></figcaption></figure>

<figure><img src="/files/VFYt2t99jK1dkQHwD4j9" alt=""><figcaption><p>Fee Settlement Page</p></figcaption></figure>

## Relationship to Other Components

The HSSN Dashboard provides crucial insights into the operations of the HSSN, which plays a central role in the Grid ecosystem. It offers visibility into:

* Communication between Grids
* Synchronization with the Solana Base Layer
* Gas fee calculations and settlements

By providing this comprehensive view, the explorer dashboard enhances transparency and facilitates efficient management of the entire Grid ecosystem.


# HSSN Gas Fee Mechanism

Detailed explanation of the HSSN gas fee distribution process, including transaction request handling, bill generation, forwarding, execution, and final distribution across the Grid ecosystem.

## Overview

In the HSSN architecture, gas fees for user-initiated transactions are distributed into four parts. It's important to note that gas fee distributions can vary between transactions. Below is a sample transaction to illustrate how fees are distributed:

### Sample Transaction

| Recipient  | Amount (SOL) | Percentage |
| ---------- | ------------ | ---------- |
| Burned     | 0.00000125   | 50%        |
| HSSN Fees  | 0.00000313   | 12.52%     |
| SONIC Fees | 0.00000313   | 12.52%     |
| GRID Fees  | 0.00000625   | 25%        |
| Total Fee  | 0.00000250   | 100%       |

This transaction can be viewed on the [Sonic Explorer](https://explorer.sonic.game/tx/5r5tiPMrktPnroaNuexYvHS57ujRmuPEtU6Yr4d3WUK5FuyerBRe4Gi2TYAYaKd3QhhNNgaAZoA5j2h4wepZueTv).

#### Distribution Explanation:

1. **Burned Fees**: A portion of the gas fee is burned, effectively removing it from circulation. This can help control token supply and potentially increase the value of remaining tokens.
2. **HSSN Fees**: This portion goes to the Hypergrid Shared State Network validators for their role in managing and transmitting transaction information.
3. **SONIC Fees**: This is allocated to the Sonic Grid, which is responsible for packaging and executing bills.
4. **GRID Fees**: This portion is allocated to the Grid nodes that initially receive and process user transaction requests.

It's crucial for users to understand that this is just an example, and actual gas fees and their distribution may vary in live transactions. Factors such as network congestion, transaction complexity, and current gas prices can influence both the total fee and how it's distributed.

Always refer to the most current information provided by the network for accurate gas fee estimates and distributions.

<figure><img src="/files/bfCkZhq2VbMUHVUTPOE9" alt=""><figcaption></figcaption></figure>

## Gas Fee Distribution Process

### 1. Transaction Request and Bill Generation

When a Grid node receives a user's transaction request:

* It calculates the required gas fee
* Distributes this fee among participating nodes based on predefined rules
* Generates a detailed bill record

### 2. Bill Forwarding and Viewing

* Grid nodes run the `hypergrid-aide` program
* This program periodically forwards gas fee bills to HSSN validators
* Users can view transaction order details on the [HSSN Dashboard](https://explorer-hssn.hypergrid.dev/fee) under the "Grid Block Fee" tab

<figure><img src="/files/yRndUFyuvOmbIDxUQQ9a" alt=""><figcaption></figcaption></figure>

### 3. Execution and Viewing of Bills by Sonic Grid

* Sonic Grid, a special service node, packages forwarded bills
* It periodically executes these bills in batches
* Users can view packaged and executed bill details on the [HSSN Dashboard](https://explorer-hssn.hypergrid.dev/fee) under the "Fee Settlement" tab

<figure><img src="/files/IFuTJODhA9cLxFx2UPjt" alt=""><figcaption></figcaption></figure>

### 4. Final Gas Fee Distribution

When Sonic Grid executes bill distribution:

* It transfers corresponding gas fees to participating nodes' wallets
* This includes Grid nodes, HSSN validator nodes, Sonic Grid official nodes, and Solana base layer nodes
* The distribution is based on the pre-calculated plan

## Transparency and Efficiency

This process ensures:

* Efficient gas fee distribution
* Transparency in transactions
* Easy access to bill information for users via the HSSN Dashboard

## Relationship to Other Components

The HSSN gas fee system is integral to the overall Grid ecosystem:

* It interacts closely with individual Grids for initial fee calculation
* Utilizes the HSSN for bill forwarding and validation
* Involves the Solana Base Layer in the final distribution
* Leverages the HSSN Dashboard for transparency and user access to fee information

By providing a clear and fair gas fee distribution mechanism, this system contributes to the overall efficiency and sustainability of the Grid ecosystem.


# Operator Guides


# Deploying a New Grid

Step-by-step guide for deploying a new Sonic RPC Node, including system requirements, hardware configurations, and setup instructions.

## System Requirements

### Operating System

* Ubuntu Server 22.04.4 LTS

### Hardware Requirements

| Configuration | CPU      | RAM   | SSD  |
| ------------- | -------- | ----- | ---- |
| Low-End       | 64-core  | 128GB | 5TB  |
| Mid-Range     | 128-core | 384GB | 10TB |

## Install Grid Validator Client

#### Option 1: Pre-built Binary Package

```bash
wget https://grid-sonic.hypergrid.dev/downloads/hypergrid-rpcnode.tar.gz
tar -zxvf hypergrid-rpcnode.tar.gz
```

#### Option 2: Build from Source Code

Install dependencies:

```bash
curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
rustup component add rustfmt

sudo apt-get update
sudo apt-get install libssl-dev libudev-dev pkg-config zlib1g-dev llvm clang cmake make libprotobuf-dev protobuf-compiler

git clone https://github.com/mirrorworld-universe/hypergrid-sonic-origin-grid
cd hypergrid-sonic-origin-grid

mkdir ~/grid_node
./scripts/cargo-install-all.sh ~/grid_node
cp ./run_rpcnode.sh ~/grid_node/
```

### Initialization

```bash
cd grid_node
./bin/solana-keygen new --no-passphrase
./bin/solana config set --url http://127.0.0.1:8899

./init_validator.sh
./bin/solana address
```

{% hint style="info" %}
**Note:** Use the account address obtained from the last command to get SOL tokens from the Sonic grid faucet.
{% endhint %}

### HSSN Client Setup

```bash
cd ..
wget https://grid-sonic.hypergrid.dev/downloads/hypergrid-ssn_client.tar.gz
tar -zxvf hypergrid-ssn.tar.gz

cd .hypergrid-ssn
./bin/hypergrid-ssnd init
```

Modify the `config/client.toml` file:

```toml
node = "tcp://172.31.10.244:26657"
```

Create a key pair:

```bash
./bin/hypergrid-ssnd keys add my_key --keyring-backend test
./bin/hypergrid-ssnd keys show my_key -a --keyring-backend test
```

{% hint style="info" %}
**Note:** Use the account address obtained from the last command to get HSOL tokens from the HSSN faucet.
{% endhint %}

### Run the Validator

```bash
cd ../grid_node
./run_validator.sh
```

### Register Node

```bash
./bin/solana validators
```

Send the Identity information to [**operators@sonic.game**](mailto:operators@sonic.game)

## Post-Deployment

After successfully deploying your new Grid, it becomes part of the HSSN, participating in the broader Grid ecosystem. Your Grid will:

* Process transactions and interact with users
* Participate in the gas fee distribution process
* Sync with the Solana Base Layer through the HSSN

For monitoring your Grid's performance and interactions within the network, refer to the [HSSN Dashboard Explorer](/architecture/hypergrid-framework/hssn-explorer-overview).

{% hint style="info" %}
Learn more about the [HSSN Explorer Overview](/architecture/hypergrid-framework/hssn-explorer-overview)
{% endhint %}

## Operator Guides

It is recommended to read the [guides and operator best practices](https://docs.solanalabs.com/operations/best-practices/general) outlined in the official Solana documentation.

## Support

For support or questions, contact the Sonic Operators team at <operators@sonic.game> or DM [@codebender828](https://x.com/codebender828) on X.


# Deploying a Sonic RPC Node

Step-by-step guide for deploying a new Sonic RPC Node on Testnet V1, including system requirements, hardware configurations, and setup instructions.

## Table of Contents

1. [System Requirements](#system-requirements)
2. [Server Port Policy](#server-port-policy)
3. [System Tuning](#system-tuning)
4. [Install Sonic Devnet Validator](#install-sonic-devnet-validator)
5. [Initialization](#initialization)
6. [Configuration](#configuration)
7. [Running the Node](#running-the-node)
8. [Shutting Down the Node](#shutting-down-the-node)
9. [Operator Guides](#operator-guides)
10. [Support](#support)

## System Requirements

### Operating System

* Ubuntu Server 22.04.4 LTS

## Hardware Requirements

| Configuration | CPU      | RAM   | SSD  |
| ------------- | -------- | ----- | ---- |
| Low-End       | 64-core  | 512GB | 10TB |
| Mid-Range     | 128-core | 1T    | 15TB |

###

## Server Port Policy

* Open ports 80 and 443 for RPC external services.
* Open TCP and UDP protocol ports in the range of 8000 to 9000.
* Whitelist IP addresses 52.13.90.86.

After configuration, send your server's public IP address to <operators@sonic.game>.

## System Tuning

Your system needs to be tuned to run properly. Your RPC validator may not start without these settings.

### Optimize sysctl knobs:

```bash
sudo bash -c "cat >/etc/sysctl.d/21-solana-validator.conf <<EOF
# Increase UDP buffer sizes
net.core.rmem_default = 134217728
net.core.rmem_max = 134217728
net.core.wmem_default = 134217728
net.core.wmem_max = 134217728

# Increase memory mapped files limit
vm.max_map_count = 1000000

# Increase number of allowed open file descriptors
fs.nr_open = 1000000
EOF"

sudo sysctl -p /etc/sysctl.d/21-solana-validator.conf
```

### Increase systemd and session file limits:

Add to the `[Service]` section of your `systemd` service file:

```sh
LimitNOFILE=1000000
```

Or add to the `[Manager]` section of `/etc/systemd/system.conf`:

```sh
DefaultLimitNOFILE=1000000
```

Then run:

```bash
sudo systemctl daemon-reload

sudo bash -c "cat >/etc/security/limits.d/90-solana-nofiles.conf <<EOF
# Increase process file descriptor count limit
* - nofile 1000000
EOF"
```

{% hint style="warning" %}
**Important**: Close all open sessions. Log out then log in again after making these changes.
{% endhint %}

## Install Sonic Testnet Validator

### Option 1: Pre-built Binary Package

```bash
wget https://grid-sonic.hypergrid.dev/downloads/sonic_testnet_grid_v1.tar.gz
tar -zxvf sonic_testnet_grid_v1.tar.gz
```

### Option 2: Build from Source Code

#### 1. Install dependencies:

```bash
curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
rustup component add rustfmt

sudo apt-get update
sudo apt-get install libssl-dev libudev-dev pkg-config zlib1g-dev llvm clang cmake make libprotobuf-dev protobuf-compiler
```

#### 2. Download the source code:

```bash
git clone https://github.com/mirrorworld-universe/hypergrid-grid
cd hypergrid-grid
git checkout base_on_1.18.23
```

#### 3. Build

```sh
mkdir ~/sonic_node
./scripts/cargo-install-all.sh ~/sonic_node
cp ./start_node.sh ~/sonic_node/
cp ./stop_node.sh ~/sonic_node/
```

## Initialization

```bash
cd ~/sonic_node
mkdir config
mkdir logs

./bin/solana-keygen new --no-passphrase
./bin/solana config set --url http://127.0.0.1:8899
./bin/solana-keygen new -o ./config/validator-keypair.json
```

## Check System Variables

```bash
cat /proc/sys/net/core/rmem_default
cat /proc/sys/net/core/rmem_max
cat /proc/sys/net/core/wmem_default
cat /proc/sys/net/core/wmem_max
cat /proc/sys/vm/max_map_count
cat /proc/sys/fs/nr_open
cat /proc/sys/fs/file-max
cat /proc/sys/vm/swappiness
```

## Configuration

Edit the `start_node.sh` file and replace **`YOUR_PUBLIC_IP`** with your machine's public IP address.

This script contains various configuration options. Ensure you replace **`YOUR_PUBLIC_IP`** with your actual public IP address, **`VALIDATOR_ID`**, with the public address of the known validator on the cluster, and **`VALIDATOR_GENESIS_HASH`** with the genesis hash of the cluster you are deploying for.

```sh
mkdir -p /data/logs
mkdir -p /data1/accounts
mkdir -p /data/ledger

#!/bin/bash
export PATH=/bin:/usr/bin:/root/sonic_node/bin
export RUST_LOG=${RUST_LOG:-solana=info,solana_runtime::message_processor=info,solana_metrics::metrics=warn}
export RUST_BACKTRACE=full
export SONIC_FEE_MULTIPLIER=5000

exec solana-validator \
    --identity ./config/validator-keypair.json \
    --known-validator VALIDATOR_ID \
    --repair-validator VALIDATOR_ID \
    --ledger ./ledger \
    --rpc-port 8899 \
    --full-rpc-api \
    --no-voting \
    --rpc-bind-address 0.0.0.0 \
    --only-known-rpc \
    --gossip-host YOUR_PUBLIC_IP \
    --gossip-port 8001 \
    --entrypoint 52.13.90.86:8001 \
    --public-rpc-address YOUR_PUBLIC_IP:8899 \
    --enable-rpc-transaction-history \
    --enable-extended-tx-metadata-storage \
    --no-wait-for-vote-to-start-leader \
    --no-os-network-limits-test \
    --rpc-pubsub-enable-block-subscription \
    --rpc-pubsub-enable-vote-subscription \
    --account-index program-id \
    --account-index spl-token-owner \
    --account-index spl-token-mint \
    --accounts-db-cache-limit-mb 102400 \
    --accounts-index-memory-limit-mb 40960 \
    --accounts-index-scan-results-limit-mb 40960 \
    --limit-ledger-size 500000000 \
    --expected-genesis-hash VALIDATOR_GENESIS_HASH \
    --wal-recovery-mode skip_any_corrupted_record \
    --log ./logs/validator.log &
```

Make sure to replace **`YOUR_PUBLIC_IP`** with your actual public IP address, and replace **`VALIDATOR_ID`** and **`VALIDATOR_GENESIS_HASH`** with the right values.

### Testnet V1 Variables:

* **`VALIDATOR_ID`**: `Ci2TRaVpJoNmTUVhw5tkTVnskXVJ7FQHCMKRFGrQSHJB`
* **`VALIDATOR_GENESIS_HASH`** : E8nY8PG8PEdzANRsv91C2w28Dbw9w3AhLqRYfn5tNv2C

### Devnet Variables (Deprecated):

* **`VALIDATOR_ID`**: `CQqu5MsTpH1mTwEsZ75QzPtXGTz9ziEvKwpcAstKG9WJ`
* **`VALIDATOR_GENESIS_HASH`** : BsJstMXKW4DpjzHPsSCdEcAn4YtpNiLFRFa5M5L7UxFx

## Configuring Domain Name for your RPC Node

At this point, you should be ready to configure a domain name for your service. You may use Nginx or any reverse proxy of your choice.

## Running the Node

```bash
./start_node.sh
```

## Shutting Down the Node

You can gracefully shut down the node by running the following command inside the `~/sonic_node`directory

```bash
./stop_node.sh
```

## Operator Guides

It is recommended to read the [guides and operator best practices](https://docs.solanalabs.com/operations/best-practices/general) outlined in the official Solana documentation.

## Support

For support or questions, contact the Sonic Operators team at <operators@sonic.game> or DM [@codebender828](https://x.com/codebender828) on X.


# Deploying an HSSN Validator

Step-by-step guide for deploying a new HSSN Validator Node, including system requirements, hardware configurations, and setup instructions.

## Operating System Requirements

* **Ubuntu Server 22.04.4 LTS**

## Hardware Requirements

| Configuration | CPU     | RAM   | SSD  |
| ------------- | ------- | ----- | ---- |
| **Low-End**   | 32-core | 128GB | 5TB  |
| **Mid-Range** | 64-core | 256GB | 10TB |

### Key Things To Note

1. **This document is a work in progress**. Some parts of it may change as it's progressively polished. However, the bulk of will remain the same.
2. HSSN validator setup is currently only being gradually rolled out to selected Sonic's Ecosystem Partners, and will gradually be publicly rolled. If you would like to run an HSSN Node, please contact our team on [**Discord**](https://discord.gg/mApwvpm5E8)**.**
3. Please make use of the [**Discord**](https://discord.gg/mApwvpm5E8) chat to follow any new developments, as well as for node operator support.

## HSSN Validator Setup

### 1. Download and Install the Package

```bash
wget https://grid-sonic.hypergrid.dev/downloads/hypergrid-ssn_testnet_v1.tar.gz
tar -zxvf hypergrid-ssn_testnet_v1.tar.gz
```

### 2. Initialization Settings

Navigate to the extracted directory:

```bash
cd .hypergrid-ssn
```

Create a key pair:

```bash
./bin/hypergrid-ssnd keys add my_validator --keyring-backend test
```

Initialize the configuration (replace `<NODE_NAME>` with your node name):

```bash
./bin/hypergrid-ssnd init <NODE_NAME> --default-denom hsol --chain-id hypergridssn
```

Copy the `~/.hypergrid-ssn/genesis.json` file and overwrite the the contents of the file generated at `~/.hypergrid-ssn/config/genesis.json`.

Modify `config/app.toml`:

```toml
minimum-gas-prices = "0hsol"
```

Modify `config/config.toml`:

Update the external IP. Make sure to replace the `<YOUR_NODE_IP_ADDRESS>` with your node's external IP address.&#x20;

```toml
external_address = "<YOUR_NODE_IP_ADDRESS>:26656"
persistent_peers = "9a32c2bc295c9e3aec50449373b3c4e9acf84a0f@35.166.61.86:26656"
```

### 3. Run the Validator

{% hint style="info" %}
Make sure to replace`<NODE_NAME>` with the name you configured in Step 2.
{% endhint %}

```bash
./bin/hypergrid-ssnd start --moniker <NODE_NAME>
```

{% hint style="warning" %}

1. Please share your validator's public IP address to our team on [**Discord**](https://discord.gg/mApwvpm5E8).
2. Allow the `start` command to run until your node has fully indexed and caught up with all the rest of the HSSN network's block height. This may take a couple of hours.\
   \
   You can see the current block height of the HSSN network on the [Blocks page of the HSSN Explorer Dashboard](https://explorer-hssn.hypergrid.dev/blocks).
   {% endhint %}

After your node has caught up with the rest of the network, please proceed to the next steps.

### 4. Networking

Display your validator's account address:

```bash
./bin/hypergrid-ssnd keys show my_validator -a --keyring-backend test
```

Use the account address obtained from the command above to get HSOL tokens from the HSSN faucet.

{% hint style="info" %}
**Important**: The following steps require you to fund your validator account.\
\
The HSSN Faucet UI is currently under development and will be added to this document soon. \
\
For now, please contact our team on [**Discord**](https://discord.gg/mApwvpm5E8) and we can airdrop you some HSOL manually.
{% endhint %}

Show your HSSN validator public key:

```bash
./bin/hypergrid-ssnd tendermint show-validator
```

{% hint style="info" %}
Replace the `pubkey` in `validator.json`  with the the public key you obtained above and update the `moniker` with the corresponding node name you configured in Step 2.\
\
Please make sure to replace the `"pubkey"` and `"moniker"` fields.
{% endhint %}

```json
{
    "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"KRrCrMHaeog5IAwSxFsUk/teRwDaZIhHQ5gFkrqcums="},
    "amount": "100000000hsol",
    "moniker": "<NODE_NAME>",
    "commission-rate": "0.1",
    "commission-max-rate": "0.2",
    "commission-max-change-rate": "0.01",
    "min-self-delegation": "1"
}
```

Stake as a validator:

```bash
./bin/hypergrid-ssnd tx staking create-validator ./validator.json --from my_validator --keyring-backend test --chain-id hypergridssn
```

Check if the operation was successful:

```bash
./bin/hypergrid-ssnd q staking validators
```

### 5. Install and Configure Solana Client

Install the Solana client:

```bash
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
```

Verify the installation:

```bash
solana --version
```

Set the Solana configuration:

```bash
solana config set --url http://api.testnet.sonic.game
solana-keygen new --no-passphrase
solana address
```

Use the account address obtained from the command above to get SOL tokens from the Sonic grid faucet and the [Solana Testnet faucet](https://faucet.sonic.game/#/?network=testnet).

### 6. Register Node

{% hint style="info" %}
Make sure to replace `<NODE_NAME>` with the name you configured in Step 2, and change the `"https://your-node-rpc-url.com/"` to the rpc URL of your choice for your node. (The url is not required at this step. You can configure this later using [NGINX](https://ubuntu.com/tutorials/install-and-configure-nginx#1-overview)).
{% endhint %}

```bash
./bin/hypergrid-ssnd tx hypergridssn create-hypergrid-node $(solana address) "<NODE_NAME>" "https://your-node-rpc-url.com/" 1 "" $(date +%s) --from my_validator -y --chain-id hypergridssn --keyring-backend test
```

### 7. Confirm Validator Node Registration

You can confirm that your node was successfully registered with the following command:

```shell
./bin/hypergrid-ssnd query hypergridssn list-hypergrid-node
```

You should be able to see your validator node in the list of validators. You should also see your validator in the [Validators page of the HSSN Explorer](https://explorer-hssn.hypergrid.dev/validators).

Congratulations! You should now be successfully running your HSSN node at this stage.

***

### 8. Community / Support

Please join the [HyperGrid Discord](https://discord.gg/mApwvpm5E8) to get more updates on latest changes as well as to get faster support responses.

For more official queries, please email <operators@sonic.game> for assistance.


# Mainnet


# Deploying an HSSN Validator

Step-by-step guide for deploying a new HSSN Validator Node, including system requirements, hardware configurations, and setup instructions.

## Operating System Requirements

* **Ubuntu Server 22.04.4 LTS**

## Hardware Requirements

| Configuration | CPU      | RAM   | SSD  |
| ------------- | -------- | ----- | ---- |
| **Low-End**   | 64-core  | 128GB | 7TB  |
| **Mid-Range** | 128-core | 256GB | 10TB |

### Server Port Policy

* Open ports 80 and 443 to support RPC external services.
* Open TCP and UDP protocol ports 1317, 9090, 26656, 26657

### Key Things To Note

1. **This document is a work in progress**. Some parts of it may change as it's progressively polished. However, the bulk of will remain the same.
2. HSSN validator setup is currently only being gradually rolled out to selected Sonic's Ecosystem Partners, and will gradually be publicly rolled. If you would like to run an HSSN Node, please contact our team on [**Discord**](https://discord.gg/mApwvpm5E8)**.**
3. Please make use of the [**Discord**](https://discord.gg/mApwvpm5E8) chat to follow any new developments, as well as for node operator support.

## HSSN Validator Setup

### 1. Download and Install the Package

```bash
wget https://distribution.sonic.game/hypergrid-ssn_mainnet_alpha.tar.gz
tar -zxvf hypergrid-ssn_mainnet_alpha.tar.gz
cp .hypergrid-ssn/.hypergrid.yaml ~/
```

### 2. Initialization Settings

Navigate to the extracted directory:

```bash
cd .hypergrid-ssn
```

Create a key pair:

```bash
./bin/hypergrid-ssnd keys add my_validator --keyring-backend test

MY_VALIDATOR_ADDRESS=$(./bin/hypergrid-ssnd keys show my_validator -a --keyring-backend test)
```

Initialize the configuration (replace `<NODE_NAME>` with your node name):

```bash
./bin/hypergrid-ssnd init <NODE_NAME> --default-denom hsol --chain-id hypergridssn

sed -i '/\[api\]/,+3 s/enable = false/enable = true/' config/app.toml
```

Copy the `~/.hypergrid-ssn/genesis.json` file and overwrite the the contents of the file generated at `~/.hypergrid-ssn/config/genesis.json`.

Modify `config/app.toml`:

```toml
minimum-gas-prices = "0hsol"
```

Modify `config/config.toml`:

Update the external IP. Make sure to replace the `<YOUR_NODE_IP_ADDRESS>` with your node's external IP address.&#x20;

```toml
external_address = "<YOUR_NODE_IP_ADDRESS>:26656"
persistent_peers = "d7b3d837af78dd806a4a4553f1824fe5a5a8131c@54.245.12.4:26656"
```

Create or Modify `~/.hypergrid.yaml` <br>

```bash
sonic:
  fee_program_id: SonicFeeSet1ement11111111111111111111111111
  fee_data_account_id: SonicFeeSet1ementData1111111111111111111112
  private_key: /home/ubuntu/.config/solana/id.json
  state_oracle_url: https://oracle.mainnet-alpha.sonic.game
  inbox_program_id: inboxov93C8R7uijTMTLtdNWqa1uzUdHXo3zpgL5a7j
```

### 3. Run the Validator

{% hint style="info" %}
Make sure to replace`<NODE_NAME>` with the name you configured in Step 2.
{% endhint %}

Create or Modify `~/.hypergrid-ssn/start.sh`

```
cd /home/ubuntu/.hypergrid-ssn
nohup ./bin/hypergrid-ssnd start --moniker <NODE_NAME> > ./logs/hssn.log 2>&1 &
cd -
```

Start service:

```bash
./start.sh
```

Check log:

```
tail -f /home/ubuntu/.hypergrid-ssn/logs/hssn.log
```

{% hint style="warning" %}

1. Please share your validator's public IP address to our team on [**Discord**](https://discord.gg/mApwvpm5E8).
2. Allow the `start` command to run until your node has fully indexed and caught up with all the rest of the HSSN network's block height. This may take a couple of hours.\
   \
   You can see the current block height of the HSSN network on the [Blocks page of the HSSN Explorer Dashboard](https://explorer-hssn.mainnet-alpha.sonic.game).
   {% endhint %}

After your node has caught up with the rest of the network, please proceed to the next steps.

### 4. Networking

Display your validator's account address:

```bash
cd /home/ubuntu/.hypergrid-ssn
./bin/hypergrid-ssnd keys show my_validator -a --keyring-backend test
```

Use the account address obtained from the command above to get HSOL tokens.

{% hint style="info" %}
**Important**: The following steps require you to fund your validator account.\
\
Please contact our team on [**Discord**](https://discord.gg/mApwvpm5E8) and we can airdrop you some HSOL manually.
{% endhint %}

Because the new validator needs to sync and replay all blocks from the main validator, it will take a while to do that. Till you can query valid balances of the new account.

```
./bin/hypergrid-ssnd q bank balances <ACCOUNT_ADDRESS>
```

Display your HSSN validator public key:

```bash
cd /home/ubuntu/.hypergrid-ssn
./bin/hypergrid-ssnd tendermint show-validator
```

Create file `validator.json`, replace the `<VALIDATOR_PUBKEY>` in validator.json with the public key you obtained above and update the `<NODE_NAME>`with the corresponding node name you configured in Step 2.

{% hint style="info" %}
Please make sure to replace the \<VALIDATOR\_PUBKEY> and \<NODE\_NAME> fields.
{% endhint %}

```json
{
   "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"<VALIDATOR_PUBKEY>"},
   "amount": "100000000hsol",
   "moniker": "<NODE_NAME>",
   "commission-rate": "0.1",
   "commission-max-rate": "0.2",
   "commission-max-change-rate": "0.01",
   "min-self-delegation": "1"
}
```

Stake as a validator:

```bash
./bin/hypergrid-ssnd tx staking create-validator ./validator.json --from my_validator --keyring-backend test --chain-id hypergridssn
```

press `y` to sign the transaction.\
Check if the operation was successful:

```bash
./bin/hypergrid-ssnd q staking validators
```

### 5. Install and Configure Solana Client

Install the Solana client:

```bash
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
```

Verify the installation:

```bash
solana --version
```

Set the Solana configuration:

```bash
solana config set --url https://api.mainnet-alpha.sonic.game
solana-keygen new --no-passphrase
solana address
```

Use the account address obtained from the command above to get SOL tokens from the Sonic grids and Solana Mainnet-Beta.

### 6. Register Node

{% hint style="info" %}
Make sure to replace `<NODE_NAME>` with the name you configured in Step 2, and change the `"https://your-node-rpc-url.com/"` to the rpc URL of your choice for your node. (The url corresponding service at port 1317, which is not required at this step. You can configure this later using [NGINX](https://ubuntu.com/tutorials/install-and-configure-nginx#1-overview)).
{% endhint %}

```bash
cd /home/ubuntu/.hypergrid-ssn

./bin/hypergrid-ssnd tx hypergridssn create-hypergrid-node $(solana address) "<NODE_NAME>" "https://your-node-rpc-url.com/" 1 "" $(date +%s) --from my_validator -y --chain-id hypergridssn --keyring-backend test
```

### 7. Confirm Validator Node Registration

You can confirm that your node was successfully registered with the following command:

```shell
./bin/hypergrid-ssnd query hypergridssn list-hypergrid-node
```

You should be able to see your validator node in the list of validators. You should also see your validator in the [Validators page of the HSSN Explorer](https://explorer-hssn.mainnet-alpha.sonic.game/validators).

Congratulations! You should now be successfully running your HSSN node at this stage.

***

### 8. Community / Support

Please join the [HyperGrid Discord](https://discord.gg/mApwvpm5E8) to get more updates on latest changes as well as to get faster support responses.

For more official queries, please email <operators@sonic.game> for assistance.


# Verifiable Compute & Zero-Knowledge Proofing on HyperGrid

An abstract of Sonic’s zk proving strategy

## Introduction

The purpose of this document is to provide insight on HyperGrid's zk proving strategy. This concise document aims to address due diligence questions and, if satisfactory, will be expanded into the working architecture document. Relevant resources will be hyperlinked inline or at the end of this document.

## About the Grid zk-coprocessor Component

Sonic’s batch transaction processing layer for commitment to Solana L1 will be orchestrated into a component currently referred to as the **Sonic zk-coprocessor**. This unit will run on Sonic’s Grid instance, as well as on other grids orchestrated by HyperGrid.

{% hint style="info" %}
It is important to note that despite the current name (co-processor), this component's implementation paradigm differs from corresponding networks on other chains at various phases. \
\
Therefore, the name might change in the future, though it currently aligns well with our long-term strategy.
{% endhint %}

## Core Functions of the zk-coprocessor:

* **Processing and compression of all transactions.**
* **Generation of proofs for state transitions in each block.**
* **Commitment of proofs to Solana mainnet.**

This document will elaborate on the following topics:

* **Implementation phases of the Sonic zk-coprocessor.**
* **Runtime Primitives & Protocols used.**
* **A high-level breakdown of the implementation phases accompanied by relevant diagrams.**

## Implementation Phases

As the Solana ecosystem is still in the early phases of developing zero-knowledge runtime primitives, emerging solutions like **Light Protocol** provide frameworks that make a fully composable zkSVM a realistic possibility. Sonic's zk-Coprocessor implementation strategy is divided into two phases:

### Phase 1: HyperGrid Optimistic Rollup

In our upcoming mainnet release, the HyperGrid Optimistic Rollup Implementation will take priority due to its shorter implementation time. This will enable us to onboard games currently integrating with Sonic, fulfilling our minimum viable product requirements. Subsequently, we will focus on the full zero-knowledge rollup implementation of the Sonic co-processor, extending transaction processing on Sonic to achieve instantaneous finality.

#### Implementation Steps:

1. **Transactions are compressed and aggregated into a Merkle tree.**
2. **For each block, the corresponding root state hash is committed.**
3. **Zero-knowledge proofing is performed and committed to the mainnet.**

### Phase 2: Full Zero-Knowledge Rollup Integration

After launch, we plan to integrate a full zero-knowledge rollup, combining validity and consistency proofs into a single zero-knowledge proof. This will involve building zk-circuits for the SVM, leveraging tools provided by either Light Protocol or native Solana zk primitives.

## Sonic zk-Coprocessor Primitives

### Compressed Accounts

Each transaction within the Sonic rollup is represented as a **compressed account**. These accounts can be program-owned and optionally have a **permanent unique address (PDA)**. Sonic will use the **Light Compressed Account** implementation.

### Concurrent Merkle Trees

Compressed transaction states will be stored in a **Concurrent Merkle tree** data structure. Each piece of data created or consumed in a transaction represents a single leaf of a state tree. All tree leaves are recursively hashed, so only the final 32-byte root hash needs to be stored on-chain.

To verify the validity of many pieces of state (Compressed Accounts) within a single Solana transaction, Sonic will leverage **Light’s Zero-Knowledge Cryptography** to compress all state proofs into one small validity proof (about 128 bytes).

## Phase 1 – HyperGrid Optimistic Rollup

Our Go-To-Market (GTM) implementation will feature an optimistic rollup strategy that submits a validity proof to our verifier program on L1. The steps can be summarized as follows:

1. **Transactions are compressed and aggregated into a Merkle tree.**
2. **For each block, we commit the corresponding root state hash.**
3. **The Validity Proof for this block is computed on Sonic.**
4. **This new state and proof are validated through our Sonic verifier program on Solana L1.**

<figure><img src="/files/4Ebq1klcgl4ICVvJZLzh" alt=""><figcaption></figcaption></figure>

#### Protocols Considered:

* **Light Protocol’s Verifier**
* **In-house Verifier (either built in-house or using Light Protocol’s verifier)**

If the consistency proof is valid, the latest record is committed to the base layer. If the proof is invalid, the witness/observation nodes initiate a challenge.

## Phase 2: Full Zero-Knowledge Rollup Integration

After the launch, this phase involves integrating a full zero-knowledge rollup by combining the validity and consistency proofs into a single zero-knowledge proof. The implementation steps are outlined as follows:

1. **Transactions are compressed and aggregated into a Merkle tree.**
2. **For each block, the corresponding root state hash is committed.**
3. **Zero-knowledge proofing is performed and committed to the mainnet.**

Additionally, the plan is divided into three major milestones:

* **Augment runtime to support transaction processing (building zk-circuits).**
* **zk runtime tracing by analyzing the output of zk-circuits.**
* **Proof generation from runtime execution trace.**

This phase is aimed at facilitating the instant finality of L2 transactions on Sonic.

<figure><img src="/files/wVDfIHOQuQWH9JQK1JJL" alt=""><figcaption></figcaption></figure>

### Why Light Protocol?

In the phase where we build our own zkSVM, **Light Protocol** has already built a significant portion of the primitives required to implement a zkSVM. We are in communication with their team and are following new developments closely.

### References

* **Light Protocol Official Documentation**
* **Light Protocol System Overview**
* **Compressed Account**
* **Merkle Tree Primitive**


# Sorada

Sorada – Sonic's Archival Data Solution

<figure><img src="/files/7DyAiO4bJINHHHj6oYNx" alt=""><figcaption></figcaption></figure>


# Introduction

A comprehensive introduction to Sorada, Sonic SVM's archival RPC data indexing and read-optimization solution

## Blockchain's Data Layer Problem

Blockchain networks aggregate data through `blocks`, `transactions`, and `metadata`.

Querying APIs are openly available and well-documented for fetching these data directly from the network.

This may work for small decentralized applications (DApps) with minimal historical data needs, but for bigger historical data requirements the baseline APIs fail to meet 2 main business requirements:

* Performance
* Scalability

### Performance

Companies have barely any control over the response times and the data operation optimizations of the baseline querying API endpoints provided by the network.

This is critical for business requirements because performance greatly impacts [website speed, search engine optimization (SEO), and conversion rate](https://www.cloudflare.com/learning/performance/more/website-performance-conversion-rates/).

### Scalability

Similar to performance, companies cannot optimally adapt to the demands of their users with elastic provisioning due to the limitation of the baseline Querying API endpoints provided by the network.

This is another critical business requirement because scalability goes beyond performance and impacts the financial feasibility of operating.

## How Blockchain Indexing solves this problem

Blockchain Indexing is the process of querying historical data directly from the network and storing them in in-house provisioned infrastructure.

A typical and simplified Blockchain Indexing pipeline would have the following flow:

1. Use network API to fetch `blocks` and `transactions`.
2. Store `blocks` and `transactions` to internal storage infrastructure.
3. Use internally provisioned data query endpoints for products as opposed to querying directly from the network

This way, the Company has internal control over the Performance and Scalability of its historical data needs.

## Case Study – Sonic SVM's 85% Archival Reads

According to Sonic's internal [Hypergrid](https://docs.sonic.game/developers/hypergrid-framework/hypergrid-infrastructure) Infrastructure monitoring, Sonic experienced around **85% Archival Read Requests vs 15% Write Requests**.

These read requests span across `getTransaction`, `getBlock`, `getSignaturesForAddress`.

While this is a solid metric of demand for Sonic, the engineering team started experiencing bottlenecks around `Bandwidth` and `Storage` costs for requests directly funneled towards the Hypergrid infrastructure.

These bottlenecks were solved by decoupling typical archival read requests away from Sonic's main Hypergrid infrastructure and into **Sorada**.

## What is Sorada?

Sorada is Sonic's **Data Solution** with the main objective of decoupling **Archival Read Requests** away from **Network Write Requests.**

By decoupling archival read requests away from the main Sonic validator and into a separate data-optimized infrastructure, `Bandwidth` and `Storage` bottlenecks were mitigated.

Sorada enables SVM validators to release more compute resources to transaction processing, while optimizing read performance of archival requests by 30 – 40x.


# Architecture

This page illustrates a simplified high-level architecture diagram of Sorada.

<figure><img src="/files/zL4jParl9rX8iAoD6yos" alt=""><figcaption><p>Sorada Architecture Diagram</p></figcaption></figure>

## Services

Sorada is composed of multiple services that enable Sonic to optimize read requests

<figure><img src="/files/2sQtzY9v7SBwcw2yQjgC" alt=""><figcaption><p>Sorada Services</p></figcaption></figure>

### Lite RPC

The Lite RPC service is an optimized Solana RPC service stripped away from a Solana full node only maintaining data retrieval endpoints such as `getBlock` and `getTransaction`.

### Ingestor

The Ingestor service pulls real-time data from the Sonic Hypergrid and persists data on the big table storage.

### Replicator

The Replicator service replicates the indexed data from the big table storage to a distributed filesystem for more resilient data preservation.

## Data Repositories

Sorada utilizes three (3) different data repository types for a robust data preservation infrastructure.

<figure><img src="/files/2Zr8QqE3NUaZkcjKf3bD" alt=""><figcaption><p>Sorada Data Repositories</p></figcaption></figure>

### Cache

Sorada utilizes a cache for an efficient retrieval of repetitive requests.

### Big Table

Sorada utilizes a big table database as its primary data store.

### Distributed Filesystem

Sorada utilizes a self-replicating distributed filesystem to ensure data is safely persisted across multiple data nodes.


# How to Deploy Sorada

A comprehensive guide on how to deploy Sorada for yoru own SVM instance

## System Requirements

### Operating System

* Ubuntu Server 22.04 LTS

### Hardware Requirements

* CPU: 2-core
* RAM: 8GB
* SSD: 16GB

### Server Port Policy

* Open port 80 to support RPC external services.

## System Tuning

Optimize `sysctl` knobs

```bash
sudo bash -c "cat >/etc/sysctl.d/21-haproxy.conf <<EOF
# Increase system level number of allowed open file descriptors
fs.nr_open=1100000
fs.file-max=1100000

# Set tcp config
net.ipv4.ip_local_port_range=5000 65000
net.ipv4.tcp_syncookies = 1
net.core.somaxconn = 4096
EOF"

sudo sysctl -p /etc/sysctl.d/21-haproxy.conf
```

Increase `systemd` file limits

```bash
sudo mkdir /etc/systemd/system/haproxy.service.d
sudo bash -c "cat >/etc/systemd/system/haproxy.service.d/21-override.conf <<EOF
[Service]
# Increase user level number of hard limit and soft limit of file descriptors
LimitNOFILE=1000000
EOF"
sudo systemctl daemon-reload
sudo systemctl enable haproxy
```

### Install `HAProxy`

```bash
sudo apt-get install --no-install-recommends software-properties-common
sudo add-apt-repository ppa:vbernat/haproxy-3.0
sudo apt-get install haproxy=3.0.\*
```

## Configure Routing

Edit `/etc/haproxy/haproxy.cfg`, routing archival requests to archival RPC endpoint and other requests to HyperGrid.

```
    acl methodGetBlock req.body -m reg \"getBlock\"
    acl methodGetBlocks req.body -m reg \"getBlocks\"
    acl methodGetBlocksWithLimit req.body -m reg \"getBlocksWithLimit\"
    acl methodGetBlockTime req.body -m reg \"getBlockTime\"
    acl methodGetSigsForAddr req.body -m reg \"getSignaturesForAddress\"
    acl methodGetTransaction req.body -m reg \"getTransaction\"
    use_backend archival if methodGetBlock
    use_backend archival if methodGetBlocks
    use_backend archival if methodGetBlocksWithLimit
    use_backend archival if methodGetBlockTime
    use_backend archival if methodGetSigsForAddr
    use_backend archival if methodGetTransaction
    default_backend HyperGrid
```

## Start Service

```bash
systemctl start haproxy
```


# Resources

This page contains useful references to know more about Sorada.

## HAProxy

<https://docs.haproxy.org>

## Apache HBase

<https://hbase.apache.org/>

## Hadoop Distributed File System (HDFS)

<https://hadoop.apache.org/docs/r1.2.1/hdfs_design.html>


# Rush ECS Framework

Introducing the Rush Entity-Component-System framework.

{% hint style="warning" %}
🚧 Rush is under heavy development. Expect bugs, crashes, breaking changes, and partial experiences so we can ship fast, break things, and iterate to bring you **the best onchain game development experience**. \
\
This page is <mark style="color:orange;">**Updated Daily**</mark>.
{% endhint %}

<figure><img src="/files/Kk3k21ySuDI1c9SE4E2T" alt=""><figcaption><p>Peepo moving at Super Sonic speed</p></figcaption></figure>


# Introduction

This page introduces Rush and its core concepts.

{% hint style="warning" %}
🚧 Rush is under heavy development. Expect bugs, crashes, breaking changes, and partial experiences so we can ship fast, break things, and iterate to bring you **the best onchain game development experience**. \
\
This page is <mark style="color:orange;">**Updated Daily**</mark>.
{% endhint %}

Rush is a declarative and rapid Entity-Component-System (ECS) framework completely built with Rust that obsessively pursues a single goal: use already-proven techniques of developer experience abstractions to reduce the complexity of integrating with blockchain technology into already-known developer tooling: Game Engine SDKs and APIs.

<figure><img src="/files/fMMqaRRqAtyTe4I5n9Jb" alt=""><figcaption><p>Peepo loves the Rush way</p></figcaption></figure>

Rush envisions a future where any game that’s already built or going to be built can easily be turned into a Fully-Onchain Game / Autonomous World simply by using Rush with their favorite Game Development stack.<br>

## How Rush Works

Typically, a Game Developer uses a Game Engine to create games. With a Game Engine, the complexity of the underlying logic is greatly reduced. Game Developers can focus on their Game Design and Game Mechanics because the Game Engine is designed to take on the complexity.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdoDbN0yy-Fh4NEsXjoNxtq4gAYkGSLTMwDVlek3Oo3LVMThSWTxMt7qoyjTuiBMaX0nTridE0JXG78t5-VjDRL9mqSqAL_x6kqWPvmxzp0Ti53jy0l7PPErAd8FOIyKyb_EI6uil5LD-MeJOibrh3iuP-p?key=hFrDrzYNUz8HnM_yQC-GsA" alt=""><figcaption><p>Figure 1: Typical Game Developer and Game Engine Relationship</p></figcaption></figure>

On the other hand, Full Onchain Games (FOCG) and Autonomous Worlds (AW) are only possible with a decentralized data store such as the Blockchain because its decentralized nature allows data to persist much more resiliently than if it was stored on a single data repository.\
\
However, this doesn’t come without a cost.

**The Game Developer must now worry about the implementation details of the Blockchain end-to-end tech stack.**

\
This can be solved either by the Game Developer learning it or hiring an already expert both of which cost resources and are often big hurdles for Game Developers to overcome before they consider FOCGs or AWs.

\
**This is why Rush came to be.**\
\
Rush intends to remove all of this complexity by using already-proven effective developer experience abstractions.<br>

With **Declarative Configuration**, **Entity-Component-System (ECS)**, and **Code Generation** being the main developer experience abstraction strategies used.

\
The Game Developer doesn’t have to learn Blockchain technology’s end-to-end stack.

**The Game Developer just needs to use Rush.**

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdsItB1RMIRyNbyVYRYpBYKqWuE7E06vRlzqKx5MyAfP7AnvjLI70fxnH5AxVIZBQSJ_JyFygLQMQyVobqo8jSieR4PhpRqMh1x89h3wapAZO0gUS_tWPv3L37mg31TYM_zJ1CC9HD7chq5Bolyl5X9PnJY?key=hFrDrzYNUz8HnM_yQC-GsA" alt=""><figcaption><p>Figure 3: Game Developer using Rush to Create an FOCG/AW</p></figcaption></figure>

## The Rush User Journey

To paint a better picture of how Rush works, here’s a typical user journey of a Game Developer using Rush.

1. Build a game with their favorite Game Engine
2. Download the Rush CLI tool from the Sonic repository
3. Create Blueprints of their Game World to be stored onchain with Rush TOML DSL
4. Use Rush CLI to parse Blueprints and generate the following:
   1. Smart Contract Code
   2. SDKs that can interact with the Smart Contract
5. Use the SDKs generated for their favorite Game Engine
6. Use Rush CLI to deploy and manage the onchain program

## The Rush Way

The following principles drive Rush:

1. Declarative - no knowledge of control flow and logic is required to be productive.
2. Rapid - iterating should be easy with lightweight tooling and loosely coupled integration.
3. Entity-Component-System (ECS) - games are reduced to simple and digestible pieces of data.
4. Simple - developer experience is the top priority
5. Product-First - value is accrued by Product-Community fit and not by Complexity and Confusion driving short-term FOMO.
6. Ship faster, break things - the goal is to reduce assumptions and increase facts by iterating with lightning speed even at the expense of things breaking
7. Fun - I mean… why not?<br>

## Rush Subatomics

Rush as a tool comprises 7 subatomic concepts called the Rush Subatomics.

Much like how neurons, protons, and electrons make up an atom Rush is made up of its World, Entities, Components, Systems, Instances, Blueprints, and Gaming Primitives.<br>

### World

Onchain data tracking the state of instances in the Game World.

### Entities

Entity is a structure of data that represents a certain Gaming Primitive. For example, a Sheep entity may have an X, Y, Width, Height, and Speed.

### Components

Components determine the data that the Entity holds. For example, a Sheep entity's X or Y position is each a component.

### Systems

Systems take a set of inputs and define the allowed state transitions that can occur onchain with those inputs. For example, a MoveForward system can only allow a Sheep entity to move forward.

### Instances

Instances are actual data in an Entity.\
\
For example, a Sheep entity could be represented like below:<br>

```
Sheep Entity
X: float
Y: float
W: float
H: float
```

An instance on the other hand instantiates this Entity’s data structure into actual data like below:

```
Sheep Instance
X: 123.0
Y: -10.0
W: 32.0
H: 32.0
```

### Blueprints

Blueprints define the structure of a Game World in Rush DSL format, with TOML being the only one currently supported. It specifies what data should be stored per Entity that is available in the World.

#### Sample Blueprint

```toml
[world]
name = "Your Farmland"
description = "Land of the farm"
entities = ["player"]
regions = ["farm"]

[entity]
player = { x = "f64", y = "f64" }

[farm]
player = [
	{ x = 0.0, y = 0.0 },
]
```

### Gaming Primitives

Gaming Primitives are a certain definition of an entity onchain. For example, a Sheep Gaming Primitive can be represented via the Blueprint.

#### Sample Sheep Gaming Primitive

```toml
[entity.sheep]
x = "f64"
y = "f64"
w = "f64"
h = "f64"
```

## Where is Rush currently?

Rush is currently in **Prerelease** to gather feedback and feature requests directly from the community.


# Features

This page outlines the currently released features of Rush.

{% hint style="warning" %}
🚧 Rush is under heavy development. Expect bugs, crashes, breaking changes, and partial experiences so we can ship fast, break things, and iterate to bring you **the best onchain game development experience**. \
\
This page is <mark style="color:orange;">**Updated Daily**</mark>.
{% endhint %}

## Prerelease

### Features

These are Rush's current features.

<table data-full-width="false"><thead><tr><th width="231">Feature</th><th width="369">Description</th><th>Status</th></tr></thead><tbody><tr><td>Rush Core</td><td>Rush core data types and design structures.</td><td>✅ Stable</td></tr><tr><td>Rush Manifest</td><td>Rush workspace standard.</td><td>✅ Stable</td></tr><tr><td>Rush Parser</td><td>Rush DSL TOML parser.</td><td>✅ Stable</td></tr><tr><td>Rush CLI</td><td>Rush CLI tool for interacting with Rush ecosystem and tooling.</td><td>⚠️ Prerelease</td></tr><tr><td>Rush Store Program</td><td>Rush Onchain Solana program for facilitating onchain data.</td><td>⚠️ Prerelease</td></tr><tr><td>Rush Bevy SDK</td><td>Rush Bevy SDK</td><td>⚠️ Prerelease</td></tr><tr><td>Rush Installer</td><td>Rush install script.</td><td>⚠️ Prerelease</td></tr><tr><td>Rush Keystore</td><td>Rush authentication mechanism</td><td>🚧  In Progress</td></tr><tr><td>Rush Proxy Program</td><td>Rush Onchain Solana program for customizable user flows.</td><td>🚫 Broken</td></tr></tbody></table>

### SDKs

Rush Game Engine SDKs.

| Game Engine | Status         |
| ----------- | -------------- |
| Bevy        | ⚠️ Prerelease  |
| Godot       | 🚧 In Progress |
| Unity       | 🚧 In Progress |

### Platforms

Rush-supported platforms.

<table><thead><tr><th width="367">Platform</th><th>Status</th></tr></thead><tbody><tr><td>Desktop</td><td>⚠️ Prerelease</td></tr><tr><td>Web</td><td>🚧 In Progress</td></tr><tr><td>Mobile</td><td>🚧 In Progress</td></tr></tbody></table>


# Quickstart

This page lists the steps on how to setup Rush.

{% hint style="warning" %}
🚧 Rush is under heavy development. Expect bugs, crashes, breaking changes, and partial experiences so we can ship fast, break things, and iterate to bring you **the best onchain game development experience**. \
\
This page is <mark style="color:orange;">**Updated Daily**</mark>.
{% endhint %}

## Prerequisite: Install the Rust and Solana toolchain

* [Install the Rust toolchain](https://www.rust-lang.org/tools/install)
* [Install the Solana toolchain](https://docs.solanalabs.com/cli/install)

## Install Rush CLI with Cargo

```bash
cargo install rush-ecs-cli
```

Check for successful installation by running

```bash
rush
```

If successfully installed it should print out the following

```bash
Rapid and Declarative development framework for Fully Onchain Games (FOCG) and Autono
mous Worlds (AW) by SonicSVM.

Usage: rush [COMMAND]

Commands:
  new     Create a new Rush project.
  deploy  Deploy current Rush project
  view    Create a new Rush project.
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

```

## Build Your Game

{% hint style="info" %}
Rush is currently at prerelease and only supports the [Bevy Game Engine](https://bevyengine.org/).
{% endhint %}

Clone the [`rush-quickstart`](https://github.com/mirrorworld-universe/rush-quickstart) repository to study a barebones scaffolding of a simple Player movement game.

## Create a new Rush Workspace

Using the Rush CLI, create a new Rush workspace to generate the **Rush Manifest** and initial **Rush Gaming Blueprint.**

Use the following command

```bash
rush new <NAME>
```

For example

```
rush new my-onchain-game
```

A successful Rush workspace creation will display the following

```bash
⠀[SUCCESS] Rush project created.
```

It will also create a new folder with the following folder structure

```
my-onchain-game/
    Rush.toml
    blueprint/
        world.toml
```

Where `Rush.toml` is your **Rush Manifest** and `world.toml` is your **Rush Gaming Blueprint**.

## Configure Rush Manifest

After creating your Rush workspace, modify the `Rush.toml` and replace the fillers with actual values.

See **References** for **recommended values**.

```toml
[workspace]
name = "my-onchain-game"

[storage]
repository = "solana"

[solana]
store = "<STORAGE_PROGRAM_ADDRESS>"
rpc = "<HTTPS_RPC_URL>"
keypair = "<KEYPAIR_PATH>"

```

## Configure Gaming Blueprint

Next, configure your Gaming Blueprint to define the data you are able to interact with in your Onchain World using the Rush SDKs.

```toml
[world]
name = "My Onchain World"
description = "My Onchain World Description"
entities = ["player"]
regions = ["base"]

[entity]
player = { name = "String", x ="f64", y = "f64"}

[base]
player = [
	{ name = "Player1", x = 0.0, y = 0.0 }
]
```

For example the Gaming Blueprint above defines a 1 Entity `player`, 1 Region `base`, 1 Instance `player` under the Region `base`.

## Deploy Your Onchain World

Now that you're done configuring your Rush Manifest and Rush Gaming Blueprint, it's time to deploy your Onchain World (migration) with the **Rush CLI.**

```bash
rush deploy
```

A successful deployment would yield a similarly looking output below.

```bash
> $ rush deploy                                                            ⬡ 18.19.1 
[SUCCESS] Created world: 8b4ywLN4SCKKNJRECcg9CZ8XR1XWdEGDCv4dY5yeRAS2, Signature: 5Jag
sxDmpmXq86JiLDnRDanovwZGFxvFi4hAUogaHNV3xySYa3hykyuvrKBsZ5xvh5tB84WWGTneHQeT9U71K1Mm
[SUCCESS] Spawned #1: 2hTonMZgSyiPuG7Y4XWSiy7eeh4jTL29826rr5LLpQYb, Signature: 23e1aBj
fQjj7DZDyHn2P3f5N3LhKRwXHtd46ABE62zbBoYaUpiSEuH1aFneFfqxyAhnxu5PzKj5VMta5nR2X9P8Q
```

## Interact with your Onchain World

To interact with your Onchain World, you need to add the `rush_ecs_core` package and `rush_ecs_sdk` package with the command below.

```bash
cargo add rush_ecs_core rush_ecs_sdk
```

Import them into your Bevy game.

```rust
use rush_ecs_core::blueprint::{Component, ComponentValue};
use rush_ecs_sdk::bevy::BevySDK;
```

Instantiate the SDK and use it to interact with your Onchain World.

```rust
fn update(mut player_query: Query<(&mut Transform, &Position), With<Player>>) {
    let mut sdk = BevySDK::new(
        "https://devnet.sonic.game".to_string(),
        "8npxEZiWoi6zcBQ4Pw2e5enC1Av4UhzA2ZtPn1fKeciU",
        "onchain/blueprint",
        "/Users/user/.config/solana/id.json",
    );

    let x_value = sdk
        .get("farm".to_string(), "player".to_string(), 1, "x".to_string())
        .unwrap();
    let y_value = sdk
        .get("farm".to_string(), "player".to_string(), 1, "x".to_string())
        .unwrap();

    let x = x_value.unwrap_float();
    let y = y_value.unwrap_float();

    for (mut transform, position) in &mut player_query {
        transform.translation.x = x as f32;
        transform.translation.y = y as f32;
    }
}

```

See **Reference** to see more available SDK functions.


# Reference

This page serves as a reference for Rush and its functions.

{% hint style="warning" %}
🚧 Rush is under heavy development. Expect bugs, crashes, breaking changes, and partial experiences so we can ship fast, break things, and iterate to bring you **the best onchain game development experience**. \
\
This page is <mark style="color:orange;">**Updated Daily**</mark>.
{% endhint %}

To interact with the onchain **Rush Store Program**, Rush has a provided prerelease SDK with the following functions below.

## Rush Manifest

```toml
[workspace]
name = "my-onchain"

[storage]
repository = "solana"

[solana]
store = "<STORAGE_PROGRAM_ADDRESS>"
rpc = "<HTTPS_RPC_URL>"
keypair = "<KEYPAIR_PATH>"

```

The Rush Manifest defines the project configurations to be used for your Rush project.

### Recommended Values

#### Sonic Devnet

`store` = `8npxEZiWoi6zcBQ4Pw2e5enC1Av4UhzA2ZtPn1fKeciU`

`rpc` = <https://devnet.sonic.game>

## Rush Gaming Blueprint: TOML DSL

Supported Types: `i64`, `f64`, `bool`, and `String`

```toml
[world]
name = "My Onchain World"
description = "My Onchain World Description"
entities = ["player"]
regions = ["base"]

[entity]
player = { name = "String", x ="f64", y = "f64"}

[base]
player = [
	{ name = "Player1", x = 0.0, y = 0.0 }
]
```

The Rush Gaming Blueprint greatly influences how your game interacts with the Onchain World.

In the example above, the Onchain world has a player entity with a `name`,`x`, and `y` component that can be interacted with the Rush SDKs.

## Rush Onchain Data Layout

{% hint style="danger" %}
Rush is currently in prerelease, this Onchain Data Layout is bound to change in the future.
{% endhint %}

### World

```rust
pub struct World {
    /// Identifier for this specific structure
    pub discriminator: [u8; 8],

    /// Description of the world
    pub name: String,
    /// Description of the world
    pub description: String,
    /// Onchain record of what Entity types exist in the world
    pub entities: Vec<Entity>,
    /// Onchain record of what Regions exist in the world
    pub regions: Vec<Region>,
    /// Source of truth for what Instances exist in the world
    pub instances: BTreeMap<Region, BTreeMap<Entity, u64>>,
    /// Determines if the World is already launched and
    /// instances can now be Created, Updated, and Deleted
    /// outside of the CreateWorld (Initialization) Instruction
    pub is_launched: bool,
    /// Overaching authority who has access to state changing
    /// operations
    pub world_authority: Pubkey,

    /// Canonical bump for World
    pub bump: u8,
}

```

### Instance

```rust
pub struct Instance {
    /// Identifier for this specific structure
    pub discriminator: [u8; 8],

    /// Source of truth for what the values of the components are
    pub components: BTreeMap<Component, ComponentValue>,
    /// Nonce to allow multiple Instances
    pub nonce: u64,
    /// Instance authority who has access to state changing
    /// operations in this specific Instance
    pub instance_authority: Pubkey,

    /// Canonical bump for Instances
    pub bump: u8,
}

```

## Bevy SDK

```rust
pub struct BevySDK {
    keypair: Keypair,
    storage: Box<dyn Storage>,
}


impl BevySDK {
    pub fn new(
        rpc_url: String,
        program_id: &str,
        blueprint_path: &str,
        keypair_path: &str,
    ) -> Self {}

    pub fn migrate(&mut self) -> Result<()> {}

    pub fn create(&mut self, region: Region, entity: Entity) -> Result<u64> {}

    pub fn get(
        &mut self,
        region: Region,
        entity: Entity,
        nonce: u64,
        component: Component,
    ) -> Result<ComponentValue> {}

    pub fn set(
        &mut self,
        region: Region,
        entity: Entity,
        nonce: u64,
        component: Component,
        value: ComponentValue,
    ) -> Result<()> {}

    pub fn signin(&self) -> Keypair {}
}

```


# Demo

Rush Prerelease demo video

{% hint style="warning" %}
🚧 Rush is under heavy development. Expect bugs, crashes, breaking changes, and partial experiences so we can ship fast, break things, and iterate to bring you **the best onchain game development experience**. \
\
This page is <mark style="color:orange;">**Updated Daily**</mark>.
{% endhint %}

{% embed url="<https://drive.google.com/file/d/1VC_lSliGMn2S8gU2cy7DVZgBhJy89wT3/view?usp=sharing>" %}
Rush Workshop / Demo Video
{% endembed %}


# Sonic Mainnet Infrastructure Upgrade Notice

Communication Timeline for Sonic SVM Mainnet Infra Upgrade

Date: February 2, 2026\
Version: v2.3.0 Runtime Upgrade

### Summary

Sonic SVM is upgrading its mainnet infrastructure to high-efficiency hardware. It is also upgrading the runtime from v1.18.23 to v2.3.0. This upgrade enhances network performance, reliability, and positions Sonic for continued growth.

### Pre-Migration Testing ✓

Our core team has completed successful dry runs on both testnet and a local replica of mainnet:

* Migration duration: \~3 hours (confirmed)
* Network performance: High performance maintained post-upgrade
* v2.3.0 runtime: Validated and stable

### Timeline

Note: RPC endpoints will be temporarily unavailable during the 3-hour maintenance window. We will announce the exact start time 24 hours in advance.

| Date          | Time (UTC)     | Event                            |
| ------------- | -------------- | -------------------------------- |
| Feb 4, 2026   | 12:00 (UTC)    | Migration begins                 |
| Feb 4-5, 2026 | \~3 hours      | Planned downtime window          |
| Feb 5, 2026   | Post-migration | Network restoration & monitoring |

{% hint style="info" %}
Note: RPC endpoints will be temporarily unavailable during the 3-hour maintenance window. We will announce the exact start time 24 hours in advance.
{% endhint %}

### What This Means for the Ecosystem

#### RPC Consumers

* Expect brief service interruption (\~3 hours)
* No endpoint URL changes required
* [https://api.mainnet-alpha.sonic.game](https://api.mainnet-alpha.sonic.game/) remains the primary RPC

#### Node Operators & Partners

* Upgrade to v2.3.0 after the migration completes
* Our team will provide direct support during your upgrade
* Contact us if you need assistance

#### Application Developers

* No code changes required
* Implement retry logic during the maintenance window
* Testnet remains available: [https://api.testnet.sonic.game](https://api.testnet.sonic.game/)

### Partner Support Contacts

For upgrade assistance or questions, reach out via:<br>

* Telegram:
  * Jonas ([@jesusjonas](https://t.me/jesusjonas))
  * Collins ([@collinsabt](https://t.me/collinsabt))
  * Ivan ([@i1i1r](https://t.me/i1i1r))
* X/Twitter: [@SonicSVM](https://twitter.com/SonicSVM)

### Post-Migration

Once the migration completes, we will:

1. Announce network restoration on all ecosystem channels
2. Provide direct support for ecosystem operator upgrades
3. Monitor network health throughout the week

***

May the Sonic Boom be with you!

<br>


# Sonic SVM Testnet Upgrade Notice

Communication Timeline for Sonic SVM Testnet Upgrade

We will be upgrading our testnet to Agave 3.0 on March 4th starting at 12:00 UTC. The upgrade is expected to take no more than 30 minutes.

#### **Affected Endpoint**

* [https://api.testnet.sonic.game](https://api.testnet.sonic.game/)

#### What’s New in Agave 3.0

* Consensus upgraded to Alpenglow for significantly faster finality
* CPI nesting limit increased to 8 (previously 4)
* Per-account CU limit increased by 40% of block CU
* Block compute limit increased to 100M CU
* AccountDb rewritten:
  * Merkle trees replaced with LT hash
  * Optimized to utilize io\_uring
  * Multiple additional performance improvements

***

#### Partner Support Contacts

For upgrade assistance or any questions, please reach out via:

Telegram:

* Jonas ([@jesusjonas](https://t.me/jesusjonas))
* Collins ([@collinsabt](https://t.me/collinsabt))
* Ivan ([@i1i1r](https://t.me/i1i1r))

X (Twitter):

* [@SonicSVM<br>](https://twitter.com/SonicSVM)

***

Please plan accordingly if you rely on the affected RPC endpoint during the upgrade window.

<br>


# Audit Reports

All related Audit reports for Sonic and HyperGrid

1. [Sonic SVM Grid Audit Report](https://github.com/mirrorworld-universe/reports/blob/master/Solana%20Hypergrid-SSC.pdf)
2. [HyperGrid Shared State Network (HSSN) Audit Report](https://github.com/mirrorworld-universe/reports/blob/master/Hypergrid%20SSN-SSC.pdf)
3. [Sonic SVM Token Contract Audit Report](https://github.com/mirrorworld-universe/reports/blob/master/Quantstamp_MirrorWorld_TokenVesting_FinalReport.pdf)
4. [veSonic Contract Audit Report](https://github.com/mirrorworld-universe/reports/blob/master/veSonic%20Smart%20Contract%20Security%20Audit%20Report.pdf)
5. [Sonic Staking Contract Audit Report](https://github.com/mirrorworld-universe/reports/blob/master/Sonic%20Staking%20Smart%20Contract%20Security%20Audit%20Report.pdf)


# We're Hiring!

Sonic, backed by Mirror World is at the forefront of enhancing research in decentralized gaming by engineering for unparalleled speed and performance with our gaming SVM rollup orchestration framework, HyperGrid.

We are looking for forward-thinking engineers to contribute to a platform bringing the best of Solana's high-throughput and low-cost transaction capabilities to games around the world.

Backed by leading investors, like Galaxy Interactive, OKX Ventures, Mirana, Republic, Big Brain Holdings, Sky9 Ventures, and Everyrealm among others, we are actively recruiting and looking forward to collaborating with great talent that is excited about this!

If this excites you, feel free to check out the Sonic Careers Page to see if there's a suitable position for you! 👇

{% embed url="<https://jobs.solana.com/companies/mirror-world-2>" %}
View careers at Sonic
{% endembed %}