Sonic offers developers robust infrastructure with 400,000 transactions per second and sub-second finality, ensuring your apps are both fast and scalable.
With full EVM compatibility and support for Solidity and Vyper, Sonic seamlessly integrates with common developer tools such as Chainlink, Safe, Pyth, Alchemy, and more. Additionally, Sonic provides the incentives, such as , necessary to innovate and thrive in the ecosystem.
Test your contracts on the first, then deploy to the mainnet when ready. Dive in and explore how you can leverage Sonic's powerful features to bring your ideas to life.
To meet other builders and receive support, join the .
For the Sonic testnet, you can use the Sonic testnet dashboard to obtain an initial amount of S to execute transactions on the testnet.
Here are example configurations for Hardhat to deploy on the Sonic mainnet or testnet:
require("@nomicfoundation/hardhat-toolbox");// Replace this private key with your Sonic account private keyconst SONIC_PRIVATE_KEY =
require("@nomicfoundation/hardhat-toolbox");// Replace this private key with your Sonic account private keyconst SONIC_PRIVATE_KEY =
To deploy, execute npx hardhat run scripts/deploy.js --network sonic.
Please note that the Sonic testnet is a testing playground designed to showcase technology capabilities. The data stored on the network might eventually be deleted, with or without notice.
Introduction
Sonic is the highest-performing EVM layer-1 blockchain, combining speed, incentives, and world-class infrastructure, powering the next generation of DeFi applications. The chain provides 400,000 TPS and sub-second finality.
By combining a novel consensus mechanism with full EVM compatibility, Sonic delivers unparalleled speed, security, and scalability. The S token is Sonic's native token, used for paying transaction fees, staking, running validators, and participating in governance.
Key Features:
Sub-Second Finality
Transactions are confirmed and irreversible in under a second.
Full EVM Compatibility
Deploy your existing Ethereum app on Sonic without changing your code.
Developers earn 90% of the network fees generated by their applications.
Network Information
Network name: Sonic
RPC URL:
Explorer URL:
S Token
The S token is the native token of Sonic. It has multiple roles within the network, such as paying for transaction fees, staking, , and participating in governance.
You can help secure the network and earn rewards by staking your S tokens.
Wallets
Sonic supports a range of popular wallets, both for users and institutions. Use the network information below to add Sonic to your wallet.
Network name: Sonic
RPC URL:
Overview
Sonic is the highest-performing EVM L1, combining speed, incentives, and world-class infrastructure for DeFi. The chain provides 400,000 TPS and sub-second finality.
Developers and users on Sonic are supported by several incentive programs, including:
Sonic delivers exceptional performance, enabling developers to scale their applications without limits while ensuring smooth user experiences.
400,000 Transactions per Second
Sonic Gateway
—
—
—
—
—
—
Quick Overview
The is our native bridge that facilitates token transfers between Ethereum and Sonic. The bridging process consists of three steps:
Choose a reputable validator and delegate your stake.
Staking your S involves a 14-day waiting period if you choose to withdraw. When staking your S, choose a reputable validator carefully. If your validator is penalized for misconduct or errors in their setup, it could impact your delegated S stake as well.
Supply and Tokenomics
The current total supply of S is approximately 3.8 billion. As decided by multiple governance proposals, the following adjustments have been or will gradually be integrated into the tokenomics of S.
Institutional Expansion
A governance proposal approved the issuance of $50M in S for the pursuit of an ETF, $100M in S for the pursuit of a Nasdaq DAT, and 150M S tokens for the newly established Sonic USA entity, as part of our institutional expansion into the U.S. capital markets.
The first issuance of 472,372,662.8 S occurred on September 4, 2025. This covered the full allocation for our Nasdaq DAT and Sonic USA entity. An additional $50 million in S may also be issued to support our pursuit of an S ETF.
The following transactions provide transparency into how the issued funds have been used to date, mainly involving SonicStrategy.
Importantly, if a Nasdaq DAT is not achieved during SonicStrategy’s pursuit, all funds will be returned to the Sonic Foundation to be leveraged for an alternative DAT or burned.
Airdrop
190.5 million S will be issued in phases exclusively used for the airdrop program. The airdrop features an innovative burn mechanism that rewards active participation and gradually reduces the total supply of S tokens.
Grow the team and scale operations to drive increased adoption
Implement robust marketing initiatives and DeFi onboarding campaigns
To fund this program, 47,625,000 tokens will be issued annually for six years, starting six months after Sonic's mainnet launch. Issued tokens will be sent to this wallet. The first issuance of 47,625,000 S occurred on June 18, 2025.
However, to guard against inflation, the network will burn newly issued tokens not used during the year, ensuring that 100% of all newly issued tokens from this initiative are allocated toward network growth rather than being held by the treasury for later use.
For example, if Sonic Labs uses only 5,000,000 tokens in the first year, the network will burn the remaining 42,625,000 tokens.
Block Rewards
Block rewards were migrated Fantom Opera to Sonic. As validators and stakers moved to Sonic, Opera's block rewards were reduced to zero, and the saved funds are used to reward Sonic validators. The Sonic Foundation will maintain Opera validators for now.
To achieve a 3.5% APR for Sonic without causing further inflation in the first four years, we're reallocating the remaining block rewards from Opera to Sonic, comprising around 70 million tokens per year, which will be distributed as validator rewards over the first four years, avoiding the need to issue new S tokens during this period for block rewards.
As a result, Opera's APR dropped to zero upon Sonic's launch. To preserve value and avoid new inflationary rewards at Sonic's inception, we will not issue new tokens for block rewards during the initial four years, as stated. After that period, S block rewards will resume by issuing new tokens at a rate of 1.75% per year to reward validators.
Token Burn
We have two burn mechanisms in place that will decrease the emission of new S tokens.
Validator Rewards
To help secure the Sonic network by running a validator and staking a certain amount of S, you can earn block rewards as well as transaction fees paid by users on Sonic.
Block Rewards
The target reward rate for validators on Sonic is 3.5% when 50% of the network is staked. The network issues tokens each epoch to provide this, except during Sonic's first four years when rewards stem from block rewards migrated from Opera, as outlined above.
The reward rate adjusts proportionally, e.g. if all S tokens are staked, the annual reward is 1.75%. Conversely, if only 25% of S tokens are staked, the annual reward is 7%.
Network Fees
Network fees are generated when users pay gas to interact with the network. Validators earn a percentage of these fees, which are distributed equally among all staked S tokens. For a detailed breakdown of how much a validator earns from gas fees, see here.
The native token of Sonic is S, which is used for transaction fees, staking, running validators, and participating in governance.
Furthermore, the Sonic Gateway provides developers and users with seamless access to vast liquidity through a secure bridge connected to Ethereum. With a unique fail-safe mechanism, it ensures user assets are protected in all circumstances.
Developers earn 90% of the network fees their apps generate.
Up to 200 million S to onboard apps to Sonic and support new ventures.
~200 million S to incentivize users of Sonic via an innovative points program.
Deposit
Deposit your assets into the bridge, which takes ~15 minutes on Ethereum to achieve finalization and only ~1 second on Sonic.
Heartbeat
After your deposit is confirmed, your assets will be bridged at the next heartbeat, which are intervals that bridge user assets in batches to ensure gas efficiency. A heartbeat occurs every ~10 minutes from Ethereum to Sonic and ~1 hour the other way. You can pay a Fast Lane fee to trigger an immediate heartbeat.
Claim
Claim your bridged assets on the destination chain. That’s it! You’re now free to explore the Sonic ecosystem with your new assets.
In today’s evolving blockchain landscape, a native, secure bridge is critical for ecosystem health, ensuring true interoperability and preventing network isolation. Yet, many current solutions on both layer 1S and layer 2S compromise security and speed —resulting in over $2.5 billion lost to bridge hacks.
The Sonic Gateway is a revolutionary, secure bridge between Ethereum and Sonic that offers:
Security: The Gateway includes a fail-safe mechanism that safeguards user assets. If the Gateway experiences prolonged failure (14 consecutive days), users can recover their bridged funds on Ethereum.
Speed: Asset bridging is processed in intervals called "heartbeats" to ensure gas efficiency — every 10 minutes from Ethereum to Sonic and hourly in reverse.
Additionally, the Gateway makes Sonic an active participant on Ethereum as it spends ETH through its contracts.
Credit:
Fail-Safe Mechanism
The Sonic Gateway includes a fail-safe mechanism that allows users to retrieve bridged assets on the original chain if the Gateway experiences a failure. In the highly unlikely event that the Gateway or the Sonic chain is down for 14 consecutive days, users are able to reclaim their bridged assets on Ethereum.
The 14-day period is immutable and cannot be altered by Sonic Labs or any third party after deployment. Importantly, this period is not intended as a contest period but rather as an essential feature that ensures users retain custody of their bridged funds on the originating chain.
Credit:
Fast Lane
Assets bridged through the Sonic Gateway are processed in intervals called "heartbeats", ensuring gas efficiency by bundling bridging transactions together. For assets moving from Ethereum to Sonic, these heartbeats occur every 10 minutes, while Sonic to Ethereum heartbeats occur every hour.
During each interval, all queued transactions are processed simultaneously. While this system reduces costs, it may introduce waiting periods for users needing their assets bridged immediately. To address this, Fast Lane allows users to bypass the wait for a small fee and have their bridge transaction processed instantly.
Fast Lane works by adding an additional heartbeat to the Gateway. This means all other queued assets waiting to be bridged are also processed immediately, effectively accelerating the entire network. By using Fast Lane, users not only avoid delays and seize timely opportunities but also contribute to the broader ecosystem's efficiency, ensuring faster bridging for everyone involved.
Looking Into the Future
By enabling canonical access to native assets from other layer-1 platforms, the Gateway fosters a secure and thriving economy on the Sonic network.
Users can directly access these canonical assets on Sonic while maintaining asset security. The Sonic Gateway thus provides safe access to high-demand assets that natively exist outside the Sonic network.
Frequently Asked Questions
Does the Sonic Gateway also secure third-party bridges?
No, only assets bridged through the Sonic Gateway are secured by the fail-safe mechanism. Additionally, if a user spends the tokens bridged through the Sonic Gateway, e.g. by swapping to another token, these tokens may not be recoverable. In the future, Sonic Labs may provide specific recovery mechanisms for some financial protocols on Sonic.
Does Sonic rely on the state of Ethereum?
No, Sonic operates independently as its own layer-1 platform and does not rely on Ethereum’s state. Instead, the Sonic Gateway uses Merkle proofs on both Ethereum and Sonic to verify the rightful owners of bridged assets. These assets can be redeemed on Ethereum by their rightful ownership regardless of the Sonic Gateway’s status.
Does Sonic store data on Ethereum?
L2 platforms store their transactions on Ethereum, using methods like blobs, which allow these transactions to be reconstructed and contested. This is crucial for resolving any security issues that may arise after the transaction is submitted by the user (e.g. if a transaction is challenged during the 7-day period). However, this approach leads to substantial storage demands on Ethereum, costing millions annually.
Our approach is more efficient as we store only a Merkle root hash (256-bit) and the block heights of both blockchains (2x64-bit) at regular intervals (e.g. hourly) through the Sonic Gateway, which uses Sonic’s own trusted validator set. This significantly reduces data storage, requiring only about 1 KB per day (or 407 KB per year).
Note: We do not retain previous hashes; each new update through the Sonic Gateway overwrites the existing hash and block heights in the Gateway’s smart contracts. The full historical states and transactions remain accessible via an untrusted channel as an archive node.
Troubleshooting
Transaction Stuck in Heartbeat
The relay service that processes heartbeats may occasionally experience downtime. If your transaction appears stuck for more than an hour, please check our official channels for status updates. The service is monitored and will be brought back online promptly.
Claiming From a Multisig
While possible, it requires careful proof generation. For the smoothest experience, we recommend using a standard EOA wallet with our Gateway UI.
Sonic offers developers two distinct networks to build and deploy their apps. First, the Sonic testnet serves as a dedicated environment where you can rigorously test your smart contract code and deployments, ensuring everything functions correctly using faucet tokens.
Once your contracts are thoroughly vetted on the testnet, you can confidently deploy your live apps to the Sonic mainnet, the production environment where end users will interact with your apps.
The following are the network details:
Network name: Sonic
RPC URL:
Explorer URL:
Explorer API:
Chain ID: 146
Currency symbol: S
Network name: Sonic Testnet
RPC URL:
Explorer URL:
Network name: Sonic Blaze Testnet
RPC URL:
Explorer URL:
To meet other builders and receive support, join the .
Users who choose not to wait for the full 270-day maturation period for 75% of their airdrop will lose a portion of their S tokens, which will be burned.
From the 47,625,000 S tokens issued annually in the first six years of Sonic to fund growth, the network will burn any of the tokens not used during the year.
Sonic is fully compatible with the Ethereum Virtual Machine (EVM). Any smart contract that runs on Ethereum can be deployed on Sonic without modification.
Supported Languages
Solidity and Vyper
Supported EIPs
Sonic supports Ethereum's Cancun hard fork features, including PUSH0 opcode (EIP-3855), with the exception of EIP-4844 data blobs. All transactions must have a Chain ID (EIP-155 is enforced).
Note on PUSH0 Opcode: Sonic's EVM supports the PUSH0 opcode. RPC tests that fail with eth_call are often missing the required block parameter (e.g., "latest"). A correctly formatted call like eth_call with params [{"to": null, "data": "0x5f"}, "latest"] will succeed.
Proof of Stake
The Sonic chain is secured using a proof-of-stake (PoS) mechanism.
In PoS on Sonic, validators must lock their S (Sonic's native token); if they act maliciously in the network, they lose their tokens. Validators are incentivized to act in the network's best interest as their own funds are at stake. Since validators do not need to perform computations, this approach is a much more energy-efficient alternative to proof-of-work for achieving resistance to Sybil attacks.
A Sybil attack is an attack where a malicious actor runs a large number of validators to allow them an unsafe amount of influence over the network. PoS makes it costly to set up these validators and allows the network to punish validators for malicious behavior, increasing the costs of attacks.
Sonic requires nodes to lock up at least 500,000 S to validate transactions and produce blocks.
Dispute
If a contract is already registered under a different app in Fee Monetization, your registration attempt will fail with ContractAlreadyRegistered(contract, projectID).
If you believe the contract rightfully belongs to you, file a dispute using the steps below.
Enter your dispute contact email address and the contracts you wish to dispute
Click Submit and pay the 50 S fee, which will be refunded if the dispute is accepted
Once submitted, we will process your dispute as quickly as possible and notify you via email. If resolved in your favor, the dispute fee is refunded and the disputed contracts are moved to your app.
To manually dispute a contract, use the to open a dispute. Attach a refundable dispute fee and call openDispute() providing all the details required to resolve the issue. If resolved in your favor, the dispute fee is refunded back to you and the disputed contracts are moved to your app.
Verify Contracts
Verifying your smart contract makes its source code publicly visible and auditable on the block explorer, creating transparency and trust. Here are the recommended methods to verify contracts on the and the .
—
— —
—
—
Method 1. Hardhat Verification (Recommended)
The most streamlined way to verify contracts is using Hardhat with hardhat-toolbox:
Learn Solidity
Sonic Labs has partnered with HackQuest to offer a learning track for anyone who is eager to learn Solidity on Sonic, whether they are a beginner or advanced. .
Upon completing the course outlined below, graduates will receive a Sonic Developer Certificate.
1
Sonic & Sodas
.
The Sonic & Sodas program empowers our community to host developer-focused networking events around the world, funded by Sonic Labs.
Think of Sonic & Sodas events as grassroots gatherings where collaboration, networking, and innovation thrive, all within the Sonic ecosystem. You host the event, and we provide the funding. Our aim is to cultivate local communities, particularly in tech hubs and around major conferences.
Node Deployment
Nodes are interconnected devices, usually software run on servers, that maintain the Sonic network by storing a full or partial copy of the chain, validating transactions, and ensuring consensus to keep the system secure and decentralized.
Visit the pages below to learn how to deploy archive and validator nodes on Sonic.
Innovator Fund
.
The Sonic Labs Innovator Fund offers up to 200,000,000 S from the Sonic Foundation treasury to expedite the immediate adoption of apps to the Sonic chain and support new innovative ventures.
Claim (Season 1)
Claims for the airdrop's first season are now live. Users earned S through Sonic Points and Sonic Gems.
Earned directly by users holding and using whitelisted assets across apps on Sonic.
Earned by apps that drove user activity, based on their performance across key metrics.
Sonic Points
Overview
The Sonic chain provides developers with exceptional scalability and storage capabilities while delivering a fast and seamless user experience.
Sonic achieves 10,000 transactions per second with sub-second finality for immediate, irreversible transactions. There is zero risk of rollbacks or reorganizations, making every transaction final and tamper-proof. Sonic's cutting-edge storage system ensures efficient data management.
Learn more about the Sonic technology stack:
Database Storage
Sonic uses database storage to store its world state, which includes account information, virtual machine bytecode, smart contract storage, etc. This database has a feature called live pruning, which removes historical data automatically, reducing storage needs for validators as the blockchain grows.
Previously, pruning required validator nodes to go offline, risking financial and operational issues for them. Now, validators can use live pruning without going offline, ensuring continuous operation and saving on disk space and costs by discarding historical data in real-time.
Live pruning works by splitting the database into two types: LiveDB and ArchiveDB. The LiveDB contains the world state of the current block only, whereas the ArchiveDB contains the world states of all historical blocks. Validators use only LiveDB, while have both LiveDB and ArchiveDB to handle historical data requests through the RPC interface.
Sonic's database storage uses efficient tree-like or hierarchical structures, which simplifies data retrieval. Importantly, it still provides cryptographic signatures for a world state and archive capabilities using an incremental version of a prefix algorithm. Additionally, it utilizes a native disk format instead of storing the world state indirectly through key-value stores like LevelDB or PebbleDB.
The process for organizing a Sonic & Sodas event is detailed below.
1
Submit Event Proposal
Got an idea for an event? Awesome! Just submit an application or drop into our Telegram chat first for any questions. Tell us how many people you’re expecting, where it’s happening, and any specific support you need.
2
Plan Event
Once your proposal is approved, start planning. Choose a time that works best — whether it’s breakfast, lunch, or dinner. Select a venue that’s easily accessible and fosters a welcoming atmosphere for networking.
3
Get Support
We’re all in to make your Sonic & Sodas a hit. We’ll boost your event with marketing support, provide promotional materials, and offer educational content tailored to our ecosystem. We’ll also send stickers and swag whenever we can.
4
Be Reimbursed
Once your event’s over, submit your reimbursement request through Request Finance. We’ll get your payment to you in crypto within a week.
5
Be Consistent
Hosting Sonic & Sodas regularly can significantly strengthen the developer community as consistent meetups enable ongoing collaboration and innovation. As your events grow, you may be able to become a community ambassador.
Funding from the Innovator Fund is being used to secure the best infrastructure and applications for Sonic, ensuring builders have the tools and capabilities to thrive within today’s ever-challenging marketplace.
We’re actively engaging with dozens of apps across the industry and top-tier infrastructure providers across on-chain tooling, compliance, native assets, cross-chain technology, wallets, indexes, strategic Web2 partnerships, and more.
Tokenized Gems
If you used apps that tokenized Gems for their users, head to MySonic to deposit your tokenized Gems and claim wS. 50% is available now, with the rest vesting over 3 months. No minimum claim.
Non-Tokenized Gems
If you used apps that did not tokenize Gems, we will send S directly to them.
They will handle distribution to their users, with 50% available to apps immediately and the rest vesting over 3 months via LlamaPay. No minimum claim.
Gems are distributed entirely by developers, not by Sonic Labs.
Explore the tooling and infrastructure platforms currently available on Sonic below. This list is regularly updated as new projects integrate the Sonic chain.
The second season of the airdrop and Kaito program are ending on November 1, 2025. Future incentive programs will be announced at a later stage.
Game Gems mark the beginning of a new chapter on Sonic, where blockchain games are not just part of the ecosystem, but central to its growth.
Just like DeFi apps earn Sonic Gems, eligible games on Sonic earn Game Gems, unlocking a share of the S token airdrop. Similar to the existing Sonic Gems, these allocations are designed to be distributed to players, helping bootstrap in-game activity and drive lasting engagement.
Game Gems Calculation
1. Growth Score
The growth score uses a transaction-weighted Quick Ratio to evaluate a game’s player dynamics. Specifically, it measures how many new and returning players a game attracts compared to how many users it’s losing or failing to retain.
This formula is designed to reward both new and established games fairly. To prevent manipulation, the score is capped, and scores cannot fall below zero. The metric is dynamic, with flexibility to adjust time windows, weighting, and inputs as new games join the program.
2. Activity Score
The activity score tracks relative player engagement across the ecosystem. It rewards games that command a larger share of total active users in the Game Gems program.
This helps ensure the reward distribution reflects real-time network activity and user interest.
3. Score and Final Allocation
Each game (denoted as g) will receive an overall score, calculated as a weighted blend of the growth and activity scores. These weights (wg and wa) are chosen by Sonic Labs to reflect strategic goals and may evolve over time.
Game Gems are separate from and come from a separate prize pool as part of the airdrop.
FeeM Vault
The FeeM Vault is a multisig operated by Sonic Labs. It accumulates 90% of transaction fees generated by core token contracts on Sonic:
wS
USDC
USDT
EURC
WETH
WBTC
Funds in the FeeM Vault will be strategically deployed to strengthen the Sonic ecosystem, provide targeted support where apps need it most, and enhance asset incentives.
The tokens that generate the revenue for the FeeM Vault will also shape how it is spent. Apps that integrate and optimize for the tokens above will be first in line to benefit.
Key areas of deployment include:
More information about the distribution of funds from the FeeM Vault will be available soon.
FeeM Vault Flywheel
The FeeM Vault is designed to compound growth across Sonic apps. As activity around key tokens increases, the Vault fills, and a self-reinforcing flywheel begins to spin:
More usage of key tokens increases the transaction fees redirected to the FeeM Vault.
More revenue in the FeeM Vault means more funding available for apps on Sonic.
More funding for apps leads to more integrations and incentives involving key tokens, attracting more users.
Integrating Staking
You can build apps on top of Sonic's staking system, such as liquid staking tokens or vaults. All staking operations are managed by the SFC (Special Fee Contract).
Constants
Economic parameters like withdrawal period and reward rates are available by calling the constsAddress() on the SFC to get the ConstantsManager contract address.
See the for the full SFC ABI.
FAQ
Check out the most frequently asked questions about Sonic and its S token.
S Token
Where can I buy or sell S?
You can acquire S on decentralized exchanges (DEXs) on Sonic and most centralized exchanges (CEXs).
Will the S token have any inflation?
The S token will not experience inflation during the first six months after Sonic's launch. Following that period, per previously approved governance votes to enable an airdrop, ecosystem growth, and validator rewards. To ensure efficient use of any additional tokens, a number of new burn mechanisms and improvements are also outlined in the votes.
Is there an S airdrop?
Yes. We're planning an to incentivize users of Sonic.
Sonic Chain
Is Sonic EVM compatible?
Yes. The Sonic chain is fully EVM compatible, allowing any app developed for other EVM chains to be deployed on Sonic without changes in their code.
Can apps on Sonic be coded with Solidity and Vyper?
Yes. Since Sonic is EVM compatible, apps can be coded with both Solidity and Vyper.
How many transactions per second (TPS) can Sonic handle?
Sonic can process around 400,000 TPS with complete 1-block finality.
Is there a Sonic testnet?
Yes. You can immediately access to deploy your apps and experience the speed of Sonic.
Is there an incentive program for developers to build on Sonic?
Yes. Sonic Labs is running a massive incentive program, which includes the program that rewards developers with up to 90% of the fees their apps generate, and the that offers up to 200,000,000 S to expedite the immediate adoption of apps to Sonic and support new ventures.
What are the tooling/infrastructure apps available on Sonic?
Check out all the tooling and infrastructure in our on MySonic.
I’m a developer who wants to launch on Sonic, how do I start?
.
Pectra Compatibility
With the Ethereum Pectra upgrade supported in Sonic release 2.1, the network gains full compatibility with ERC-4337, a transformative framework originally introduced on Ethereum.
ERC-4337 replaces traditional externally owned accounts (EOAs) with smart contract wallets that have programmable authorization logic. This enables advanced features such as:
Social Recovery
Restore access with help from trusted guardians.
Multi-Signature Security
Require multiple approvals before executing transactions.
Spending Limits
Enforce daily/weekly caps on outgoing funds.
Token-Based Gas Payments
Pay fees in ERC-20 tokens instead of the native token.
Unlike protocol-level changes, ERC-4337 operates entirely on top of the blockchain. No network hard fork is required, making it immediately compatible with Sonic post-Pectra. It works through a specialized flow involving UserOperations, an alternative mempool, bundlers, and optional paymasters for gas fee handling.
This upgrade fundamentally improves the Sonic user experience, unlocking customizable, secure, and user-friendly wallets without sacrificing decentralization or performance.
Core Concepts
Smart Wallet
An ERC-4337 smart wallet extends the functionality of a standard EOA by delegating control to a smart contract. This enables transaction batching, gas sponsorship, and custom permission logic while still functioning like a traditional wallet.
EntryPoint
The EntryPoint contract is the core of ERC-4337. It validates signatures, nonces, and logical rules defined by each wallet. It can also enforce custom conditions such as balance checks, restricted contract calls, or app-specific rules.
UserOperation
A UserOperation is a generalized transaction format for ERC-4337. It contains standard fields like sender, recipient, calldata, maxFeePerGas, maxPriorityFeePerGas, signature, and nonce, along with additional fields such as callGasLimit, verificationGasLimit, and paymasterAndData to support advanced execution logic.
Bundler
A bundler collects UserOperations from the alternative mempool, simulates them for validity, and packages them into a single transaction sent to the EntryPoint. Bundlers may also forward standard transactions to a full node for normal blockchain processing.
Paymaster
A paymaster is a smart contract that sponsors gas fees on behalf of users, allowing them to transact without holding the network’s native token. During validation, the paymaster checks if the operation qualifies for sponsorship and covers the gas cost. To prevent abuse, paymasters stake collateral with the EntryPoint and must maintain a sufficient deposit.
Related Topics
Customize transaction authorization logic with smart contract wallets.
Let users interact with an app without paying gas themselves.
Monetize app usage via increased gas consumption.
Account Abstraction
Objective
Account abstraction enables users to customize how transactions from their account are authorized. This flexibility supports alternative signing methods, multi-signature requirements, and account recovery mechanisms. Examples include:
Alternative Signing Methods
Passkey, YubiKey, or TouchID to sign transactions directly in the browser without extensions like MetaMask.
Multi-Signature Wallets
Requiring multiple signatures before a transaction can be executed.
Social Recovery
Allowing a group of trusted contacts to override or replace the account’s controlling key.
Solution
ERC-4337 introduces a framework where user wallets are implemented as smart contracts. This allows the wallet’s transaction authorization logic to be fully customizable. Transactions are sent as UserOperations and processed according to the smart account’s rules.
EIP-7702 extends this flexibility by allowing a regular externally owned account (EOA) with a standard ECDSA private key to deploy a smart contract directly into its account. Once a smart account implementation is deployed, the user can send transactions in two ways:
Regular Transactions
Signed with their private key.
UserOperations
Authorized according to the custom logic defined in their smart account.
Example Authorization Logic Options
Passkey / YubiKey / TouchID []
Signs UserOperations directly in the browser, without extensions like MetaMask.
Currently a research project—experimental and not recommended for production.
Audits
Sonic has undergone extensive security audits across its core components to ensure the highest level of security for our users and developers.
Sonic Gateway
The Sonic Gateway is our native bridge between Ethereum and Sonic.
Fee subsidies enable users to interact with an app without paying gas fees themselves. Users do not need to hold any native tokens to execute transactions with the app’s contracts. Instead, gas costs are covered by a third party, typically the app’s developers.
Solution
Fee subsidies can be built on ERC-4337 account abstraction. Rather than broadcasting transactions directly to the blockchain, users submit UserOperations to a bundler. The bundler aggregates these operations into a single transaction and sends it on-chain.
Within each UserOperation, the user specifies a paymaster contract. This paymaster (not the sender) pays the bundler for the gas used by the UserOperation.
The paymaster’s primary function is to determine whether a UserOperation qualifies for sponsorship, typically by checking if the operation interacts with the subsidized app. This verification is non-trivial, since users can deploy arbitrary smart account implementations. To prevent abuse, the paymaster must:
Inspect the UserOperation’s calldata to confirm it targets the sponsored contract(s).
Verify that the user’s account is running a pre-approved smart account implementation.
An example paymaster for sponsoring a single-contract app might look like this:
Alternative Fee Payments
Objective
Alternative fee payments enable users to interact with an app without holding the network’s primary token (S) to cover gas fees. Instead, gas costs are paid using an alternative method, such as ERC-20 tokens (e.g. stablecoins) or even off-chain settlement. This removes the requirement for users to maintain a balance of the native token.
Solution
An alternative fee payment system can be built on the same ERC-4337 account abstraction principles used in the .
As with subsidies, users submit UserOperations to a bundler rather than sending transactions directly on-chain. The paymastercontract specified in the UserOperation determines whether to cover the gas cost, typically by interacting with the user’s credit source, most commonly an ERC-20 token.
The paymaster:
Verifies the user has sufficient available credit to cover the estimated gas cost.
Deducts or reserves the required amount from the user’s credit source.
For ERC-20 token payments, the user must first approve an allowance for the paymaster. When assessing a UserOperation, the paymaster transfers the maximum token amount needed to cover gas fees. Once execution is complete and the actual gas usage is known, the paymaster refunds any unused portion to the user.
For popular stablecoins (e.g. USDC), a paymaster is by the token issuer. For other ERC-20 tokens, developers can implement a custom paymaster by extending, for example, PaymasterERC20 from OpenZeppelin community-contracts:
A guide for creating similar paymasters can be found in the .
Archive nodes store the entire history of the Sonic chain, including all historical states, transactions, and blocks since the genesis block.
These nodes handle historical data requests, useful for chain explorers or apps that require historical chain information. However, they do not validate transactions or create new blocks, which is the role of validator nodes.
To run an archive node on the Sonic mainnet or testnet, follow the steps below.
1. Build Sonic Client and Tooling
The minimal configuration for a Sonic archive node is a Linux server with 4 vCPU, 32 GB of RAM, and local SSD storage. We recommend at least 8 vCPU and 64 GB of RAM, but 128GB of RAM is generally preferable for high-demand nodes.
You will need ≈1TB of free local SSD space to achieve good performance and speed. The configuration details depend on your specific use case.
The IOPS throughput and random access latency of the state DB persistent storage determine the performance of Sonic. For a smooth installation and fast response time, we recommend a local NVMe or a local SSD drive.
A remote block device, e.g. AWS Elastic Block Store (EBS), does not provide the required latency and IOPS performance.
The system firewall must allow TCP and UDP connections from/to port 5050.
Building the Sonic binary requires the essential software compilation tools and the language version 1.22 or newer to be available. Please refer to your Linux distribution manuals to obtain the development tools installed on your system.
Build Sonic Client
Download the Sonic source code from the following GitHub repository.
Switch to the most recent .
Build the Sonic binary using the provided configuration.
Transfer the new binaries to the bin folder for system-wide access (optional).
2. Prime Sonic State DB
Download the most recent network archive genesis file for the .
The genesis file will be used to prime your local state database and will allow you to join the network and synchronize with it. Please check the downloaded genesis file using the provided checksum.
The expected output is sonic.g: OK.
Prime Sonic Database
Use the sonictool app (created during the building process as build/sonictool) to prime a validated archive state database for the Sonic client. Start the genesis expansion.
The last step of the genesis processing is the state validation. Please double-check that the output log contains the following messages with details about the verified state:
3. Synchronize Sonic Node With Network
With the Sonic app created and the database primed in the previous step, you are ready to start the node and synchronize its state with the network.
Use the node database path (<datadir>) from the previous step.
Use ≈90% of the RAM as the GOMEMLIMIT value.
Use ≈12 GiB of the RAM as the --cache value.
Additional starting flags may need to be added to start Web3 RPC and WebSocket interfaces on the node. Add the following flags to enable the Web3 HTTP interface. Adjust your listening IP address, port, CORS, and list of enabled APIs for your specific needs.
Add the following flags to enable the WebSockets interface. Adjust your listening IP address, port, origin, and list of enabled APIs for your specific needs.
Please obtain and explicitly specify the external IP address of your node as a starting flag to help with the inter-node peer-to-peer connectivity.
Fee Monetization (FeeM) on Sonic lets builders earn 90% of the network fees their apps generate — creating a sustainable revenue stream without relying on fundraising. Inspired by Web2 models like YouTube, FeeM rewards developers for the traffic they drive.
FeeM also challenges the extractive "app chain" model by allowing builders to earn 90% of their app's network fees without the need to launch a separate chain. This approach removes the high costs, infrastructure overhead, and interoperability challenges typically associated with app chains.
By integrating monetization directly into the network layer, FeeM simplifies revenue capture and supports scalable, efficient app development within a unified, developer-friendly ecosystem.
Flow of Fees
1
Transaction Submitted
A user initiates a transaction on an app and pays a gas fee in S tokens.
2
Double-Spend Dilemma
In Fee Monetization, double counting is prevented by accurately tracking gas consumption within the virtual machine. The system traces all internal calls in a transaction and splits the reward based on the gas each sub-operation consumes.
This ensures that the sum of rewards across different projects never exceeds the total transaction fee. An example is given below.
A trade consumes 100,000 units of gas with a total FeeM reward of 0.017 S.
Inside this transaction, there are operations related to two projects: Project A and Project B.
Project A, the DEX aggregator, is responsible for consuming 37,000 units of gas, while Project B, the liquidity pool on the DEX with which the aggregator interacts, uses 63,000 units of gas.
The chart below illustrates how the FeeM oracle infrastructure traces each sub-operation and distributes the transaction fee spent on the calls based on gas consumed.
Frequently Asked Questions
My app uses an upgradeable (proxy) contract. Should I register the implementation too?
Typically, you only need to register the proxy. Gas consumed by the implementation via delegate-call will be attributed to the proxy address.
What if my app deploys many user-specific contracts?
If those user contracts act as proxies calling a small set of implementations, you only need to register the main implementation proxies. You’ll receive rewards for all the gas consumed within them.
How do I claim my rewards?
You initiate a claim transaction on the FeeM contract. The oracles confirm your gas usage, and after enough confirmations, your share is transferred to your rewards recipient. You may want to check the for a user-friendly claim UX.
What if I don’t claim my rewards immediately?
There is no deadline. Unclaimed rewards stay in the FeeM contract until the rightful project claims them.
Why do my rewards stay the same over a longer time period?
FeeM processes rewards similarly to the staking rewards via the SFC contract. The accumulated rewards are updated after the active epoch is sealed and confirmed.
Questions? Join on Telegram.
Sonic Points
This page is specific to season 2 of the airdrop.
The second season of the airdrop and Kaito program are ending on November 1, 2025. Future incentive programs will be announced at a later stage.
Sonic Points are user-focused airdrop points that can be earned as part of the ~200 million S airdrop. Designed to boost liquidity on Sonic and strengthen its ecosystem, our points program positions Sonic as a premier hub for DeFi enthusiasts and users seeking to maximize the potential of their assets.
To earn Sonic Points, deploy whitelisted assets across various DeFi apps. These points will be distributed over multiple seasons as , ensuring long-term sustainability and preventing sudden supply shifts.
Apply
All apps on Sonic are eligible to participate in Fee Monetization. To apply, visit the and click Apply for FeeM.
The application process consists of registering your app to participate in FeeM, followed by registering your app's associated contracts to verify ownership.
Step 1 — App Registration
Visit the , connect your admin wallet, and click Apply for FeeM. The registration form will request several details from you.
Consensus
Consensus in a decentralized system is not just a process but a cornerstone of the system. Its mechanism guarantees a consistent and secure blockchain among all participants and ensures the system's integrity and reliability. Consensus ensures that transactions are consistently and securely validated and added to the blockchain.
It's a critical element for effectively thwarting attempts by malicious actors to manipulate the network or its data. Sonic uses Asynchronous Byzantine Fault Tolerance in combination with directed acyclic graphs to achieve consensus.
Practical Byzantine Fault Tolerance
Practical Byzantine Fault Tolerance (PBFT) is a consensus mechanism designed to enable decentralized systems to function correctly in the presence of malicious or faulty nodes. It is named after the
Version History
The following version history documents the Sonic client (the node software that powers the Sonic mainnet) including its virtual machine, database storage, and consensus mechanism.
By deploying whitelisted assets as liquidity on participating apps, users will earn points. A list of participating apps is available on the points dashboard.
To earn points for providing liquidity (LPs), both tokens in the pair must be whitelisted. If only one or neither token is whitelisted, no points will be earned. Points are calculated as the average of the two asset multipliers. For example, an S/USDC LP would earn 10x points (average of 12x and 8x).
2. App Gems — Earn Further Allocation
The S airdrop includes a developer-focused portion, where apps compete for an airdrop allocation known as Sonic Gems. Apps can redeem these Gems for S tokens, which they can then distribute to their users however they want.
To decide how these S tokens are distributed to their users, each app will run its own independent points program, entirely at its discretion. The app may consider various things, such as the amount of liquidity a user has deployed, the duration of deployment, and the specific pools to which a user has added liquidity.
As a user, you will be earning points regardless if you've deployed your assets on an app. Your goal is to identify which app has the points program that will offer the highest return for your liquidity. The challenge lies in maximizing your overall rewards by combining the yield earned from providing liquidity with the points earned from the app's points program.
Loyalty Multiplier
To encourage consistency and prevent farming or drop-off cycles, a loyalty multiplier is in place.
Your season 1 performance sets your initial multiplier (from 1.0–2.0x), and your ongoing activity in season 2 can increase or decrease that value, up to a maximum of 3.0x and a minimum of 1.0x.
The multiplier applies to EOAs only (for now) and updates automatically based on your activity. It will be visible in MySonic once available (not immediately at launch). This loyalty program will carry forward into future seasons.
Whitelisted Assets
To qualify for the S airdrop, you must deploy the whitelisted assets listed in the table below as liquidity on participating apps. The multipliers are applied to the points you earn.
Asset
Multiplier
S, wS, stS, beS, anS, wanS, OS, wOS, vS, Origin ARM
The multipliers for each asset above are decided by which category the fall under in the table below.
Token Type
Multiplier
Sonic Tokens
12x
Ecosystem Tokens
10x
Yield Bearing Stablecoins
10x
Pegged Stablecoins
8x
ETH/BTC
4x
Yield Bearing ETH/BTC
4x
Sonic reserves the right to determine the appropriate category for any app.
Whitelisted assets and their multipliers are subject to change. S tokens staked through MySonic are not eligible for points. Users who wish to stake can instead use liquid staking tokens.
Learn more about scUSD/scETH by Rings. Sonic Labs makes no guarantee to the safety or peg of third-party assets, such as Rings. Use them at your own risk.
Sonic automatically allocates 10% of this fee to the network validators.
3
FeeM Allocation
The remaining 90% is sent to the specialized Fee Monetization (FeeM) contract (sometimes referred to as the fee treasury).
4
Off-Chain Oracle Tracking
Multiple off-chain servers (oracles) monitor every transaction on-chain, tracing gas consumption for each registered contract (including sub-calls).
5
Rewards Distribution
When an app claims rewards, the FeeM oracles confirm the gas usage on-chain. Once a quorum of oracles confirms, the FeeM contract releases the app’s accumulated rewards.
The total reward is split based on the gas consumption:
Project A receives 37% of the reward (0.00629 S).
Project B receives 63% of the reward (0.01071 S).
The total reward still adds up to 100% of the 0.017 S FeeM reward, ensuring no over-distribution.
Owner address
Wallet that will manage your FeeM registration.
Rewards recipient address
Address that will receive FeeM revenue when claimed.
Dispute contact
Email to be used for communication if you dispute a contract.
Metadata
Information about your app, such as logo, name, and website.
After completing this step, the UI will guide you through registering your app's associated contracts to verify ownership.
The 25 S registration fee will be refunded once your app has been added to FeeM.
Step 2 — Contract Registration
To verify ownership of the contracts you want to include in your FeeM application, you’ll need to add a small code snippet to them.
Choose the Auto-verify option
Copy and paste the code snippet into your contract
Deploy your contract and run the new registerMe function
Your contracts are now verified and included in FeeM, and you can proceed to the next step.
If your contract is not upgradable or you're unable to interact with them from an EOA or through other means, please choose the Manual verification option and follow the steps.
Step 3 — Claim Revenue
Once your app is approved to FeeM, you will start earning 90% of the network fees it generates.
To claim, visit the Fee Monetization dashboard, connect with your admin wallet, and claim your rewards. These will be sent to the recipient address you provided during the initial application step.
If you prefer to register your app and its contracts manually instead of using the UI described above, follow the instructions below. However, we recommend using the Fee Monetization dashboard to register.
Create a metadata config file in JSON format with the following parameters:
Host the file in a publicly accessible location. Ensure that anyone can download the JSON file via a browser and that the hosting site supports HTTPS. A 200×200px PNG logo, no larger than 32 KiB, is sufficient.
Go to the FeeM ProjectsRegistrar smart contract and execute the register function providing all the required information. A unique Project ID will be assigned to your registration in response. Use this ID to identify your project in subsequent calls.
Include the code snippet below directly in your contract and run the new function. Replace the <Your FeeM Project ID> placeholder with your actual FeeM Project ID.
Your app and its contracts are now integrated into FeeM. Proceed to Step 3 above to learn how to claim your rewards.
If your contract is not upgradable or you're unable to interact with them from an EOA or through other means, please contact Sam Harcourt on Telegram for manual contract verification.
Contracts to Interact With
The FeeM Core: 0x0b5f073135df3f5671710f08b08c0c9258aecc35
My app uses an upgradeable (proxy) contract. Should I register the implementation too?
Typically, you only need to register the proxy. Gas consumed by the implementation via delegate-call will be attributed to the proxy address.
What if my app deploys many user-specific contracts?
If those user contracts act as proxies calling a small set of implementations, you only need to register the main implementation proxies. You’ll receive rewards for all the gas consumed within them.
How do I claim my rewards?
You initiate a claim transaction on the FeeM contract. The oracles confirm your gas usage, and after enough confirmations, your share is transferred to your rewards recipient. You may want to check the Fee Monetization dashboard for a user-friendly claim UX.
What if I don’t claim my rewards immediately?
There is no deadline. Unclaimed rewards stay in the FeeM contract until the rightful project claims them.
Why do my rewards stay the same over a longer time period?
FeeM processes rewards similarly to the staking rewards via the SFC contract. The accumulated rewards are updated after the active epoch is sealed and confirmed.
, which is an idea that illustrates the difficulties of achieving consensus in a decentralized system when some of the participants may be acting in bad faith.
In a PBFT system, nodes in a network communicate with each other to reach a consensus on the system's state, even when malicious actors are involved. To achieve this, they send messages back and forth that contain information about the system's state and the actions they propose.
Each node verifies the message it receives, and if it determines the message is valid, it sends a message to all the other nodes to indicate its agreement. In the context of cryptocurrencies, the message with which all nodes must agree is the blockchain, a ledger that stores a history of transactions.
Before the invention of cryptocurrencies, the major flaw with PBFT systems was their susceptibility to Sybil attacks. If an attacker controlled a sufficient number of nodes, they could control the entire system; there needed to be a deterrent to launch many nodes. Bitcoin first solved this problem with proof-of-work, forcing nodes to invest considerable energy to partake in the consensus.
Since then, many new solutions have been developed, such as proof-of-stake, which forces nodes to deposit tokens with monetary value, which Sonic uses.
Hence, Practical Byzantine Fault Tolerance (PBFT) is a mechanism to achieve consensus. It forms a functioning decentralized system when coupled with proof-of-work or proof-of-stake to deter participants from messing with the network. However, Sonic has decided to innovate on this mechanism by using Asynchronous Byzantine Fault Tolerance.
Asynchronous Byzantine Fault Tolerance
With Asynchronous Byzantine Fault Tolerance (ABFT), nodes can reach consensus independently and are not required to exchange final blocks sequentially to confirm transactions. At the same time, they exchange blocks, which is required to achieve consensus, and this is done asynchronously. Each node verifies transactions independently and is not required to incorporate blocks created by other miners or validators in sequential order.
This is opposed to PBFT systems, such as Bitcoin, in which the majority of nodes must agree to a block before it becomes final, which they must then sequentially order into their blockchain record. This slows down the network during high traffic; more on this in the consensus mechanism section further below.
Now that we have a basic understanding of Byzantine fault tolerance, let’s delve into the second part of Sonic’s consensus mechanism, directed acyclic graphs.
Directed Acyclic Graphs
A graph is a non-linear data structure used to represent objects, called vertices, and the connections between them, called edges. A directed graph dictates that all its edges, the connections between objects, only flow in a certain direction. An acyclic graph does not contain any cycles, which makes it impossible to follow a sequence of edges and return to the starting point. As such, a directed acyclic graph (DAG) only flows in a certain direction and never repeats or cycles.
The diagram below is an example of a directed acyclic graph. Each oval is a vertex, and the lines connecting them are edges. The vertices only connect in one direction, downwards, and never repeat.
In our consensus algorithm, an event containing transactions is represented by a vertex in a DAG, and edges represent the relationships between the events. The edges may represent the dependencies between events indicating the order in which they were added to the DAG.
Events can be created and added to the DAG concurrently. The blocks do not need to be added in a specific order, which enables the system to achieve faster transaction times. It is not limited by the requirement to incorporate blocks sequentially, as is the case with many of the biggest blockchains currently available.
Sonic's Consensus Mechanism
Sonic uses a proof-of-stake, DAG-based, ABFT consensus mechanism. In this mechanism, each validator has its own local block DAG and batches incoming transactions into event blocks, which they add to their DAG as vertices — each event block is a vertex in the validator’s DAG that is full of transactions.
A validator’s block DAG
Before creating a new event block, a validator must first validate all transactions in its current event block and part of the ones it has received from other nodes; these are the event blocks it has received during the asynchronous exchange of event blocks explained in the section above. The new event block then is communicated with other nodes through the same asynchronous event communication.
During this communication, nodes share their own event blocks, and the ones they received from other nodes, with other validators that incorporate them in their own local DAGs. Consequently, this spreads all information through the network. The process is asynchronous as the event blocks shared between validators are not required to be sequential.
Unlike most blockchains, this DAG-based approach does not force validators to work on the current block that is being produced, which places restrictions on transaction speed and finality. Validators are free to create their own event blocks that contain transactions and share these with other validators on the network asynchronously, creating a non-linear record of transactions. This increases transaction speed and efficiency.
As an event block is sent and propagated across validators, it becomes a root event block once the majority of validators have received and agreed upon it. This root event block will eventually be ordered and included in the main chain, which is a blockchain that contains the final consensus among all event blocks that have become root event blocks.
Every validator stores and updates a copy of the main chain, which provides quick access to previous transaction history to process new event blocks more efficiently. As such, Sonic's consensus mechanism combines a DAG-based approach that allows validators to confirm transactions asynchronously, which greatly increases speed, with a final blockchain that orders and stores all final transactions immutably and indefinitely.
Currently, the process of submitting a transaction and having it added to the Sonic main chain through the consensus mechanism takes approximately 1-2 seconds. This involves the following steps:
A user submits a transaction
A validator node batches the transaction into a new event block
The event block becomes a root event block once the majority of nodes have received it
The root event block is ordered and finalized into the main chain as a block
When a user explores Sonic through a block explorer, they view the final blocks on the Sonic main chain. Event block generation and exchange in validators' DAGs is an internal process only and is not visible to end users.
To better understand the technical aspects of Sonic's consensus mechanism, review the paper on Fantom Opera's consensus mechanism, as Sonic's design is a continuation of it:
325fb5ea – Implement SetStorage on Carmen adapter (#2)
v2.0.2
Jan 23, 2025
Jan 31, 2025
Enhanced RPC gas capping
Added getAccount RPC method
Improved finalized/safe block tag handling
19dc2691 – Remove dev from meta version (#394)
3f86ba1c – RPC gas capping (#391)
b9545c63 – Implement getAccount RPC (#370)
v2.0.1
-
Dec 2, 2024
-
-
v2.0.0
-
Nov 29, 2024
-
-
v2.0.7
June 26, 2025
TBA
• Improved error handling in debug_traceBlock — now uses error field and supports empty blob cases
252c9ee0 – Fix error handling in debug_traceBlock (#307)
v2.0.6
Gas Pricing
Gas and Fees
Fee Model
Sonic uses a Base Fee + Priority Fee model similar to Ethereum's EIP-1559.
Fee Distribution
Unlike Ethereum, the Base Fee is not burned. Instead, 90% of all transaction fees are sent to the FeeM treasury for developers and 10% are distributed to validators.
Gas Power
Each validator has a "gas power" budget that refills over time, based on their stake. This prevents any single validator from congesting the network. If a validator runs out of gas power, they may temporarily be unable to emit events containing large transactions, resulting in a Not enough gas power to emit event warning.
Gas Estimation (eth_estimateGas)
While eth_estimateGas is fully supported, its estimates can sometimes be inaccurate for complex transactions whose gas usage depends on the current on-chain state.
The Problem
The state of the chain can change between the time of gas estimation and the time of transaction execution. For contracts like a UniswapV3Pool, a change in the pool's state can alter the execution path and, consequently, the gas required.
The Symptom
This can lead to random out of gas transaction reversions.
Frequently Asked Questions
Why does eth_maxPriorityFeePerGas sometimes return 0x1 (1 wei) while other times it returns larger values?
This is expected behavior on Sonic. The value 0x1 (1 wei) is the correct minimum gas tip estimation. Unlike Ethereum where users compete for block space, Sonic has much higher throughput, so there's usually no competition. The method returns the minimum tip needed for inclusion in a block. It only returns higher values when the network experiences higher load, which is rare on Sonic.
Isn't 1 wei too low? Gas tips are usually in GWei magnitude on other chains.
While it may seem unusually low compared to Ethereum, 1 wei is sufficient on Sonic because:
Sonic has significantly higher throughput than Ethereum
What's the difference between the block base fee and the fee returned by eth_feeHistory?
Block base fee: Usually at it’s current minimum of 50 GWei (0xbebc200 in hex) on Sonic
eth_feeHistory and/or eth_gasPrice: Returns 55 GWei (0xcce416600 in hex), which is base fee + 10% buffer
Why are my transactions being rejected as "underpriced"?
This typically happens when you use the raw block base fee (50 GWei) without adding a buffer. To avoid this:
Use eth_feeHistory which already includes a 10% buffer (55 GWei)
How should I calculate gas fees for Sonic transactions?
For Type 1 transactions:
Gas Price = Base Fee + >5% Buffer (10% recommended) + Priority Fee
Why doesn't the base fee change dynamically on Sonic?
The base fee on Sonic is configured with a minimum of 50 GWei and doesn't change because:
Network bandwidth is nowhere near saturated
The algorithm only increases fees when network gas budget spendage exceeds 50%
Why does gasUsedRatio show 99% if the network isn't congested?
This is due to how Sonic builds blocks:
Blocks are fitted to transactions, not pre-allocated
Unlike Ethereum's EIP-1559 premise, this doesn't indicate congestion
What's the recommended approach for gas pricing on Sonic?
Use RPC suggestions directly:
eth_gasPrice or eth_feeHistory for base fee (includes 10% buffer)
Why does Sonic add a 10% buffer to gas price suggestions?
The buffer exists because:
Validators reject transactions with less than 2% buffer above the previous block's base price
The transaction pool requires 5% buffer to accept and advertise transactions
Common Troubleshooting Tips
Hex Conversion Issues
Ensure proper hex to decimal conversion (0xcce416600 = 55,000,000,000 wei, not 54,816,600,000)
Use Suggested Values
Don't use raw block base fee; use RPC-suggested values that include buffers
Minimum Tip Is Fine
Don't increase priority fee unless you specifically need priority during high load
Upgrade Instructions (2.1.2)
This guide describes the steps for upgrading a Sonic mainnet node to the latest 2.1.2 version, which introduces the Ethereum Prague feature set to the Sonic network.
Once upgraded, your nodes will continue to operate on the current mainnet until the full transition. The upgrade is backward compatible, meaning you can upgrade now without any interruption.
Verify the version and upgrade the version to v1.24 or newer as needed.
Obtain the new source code from GitHub.
1. Build Sonic Client and Tooling
Building the Sonic client binary requires the essential software compilation tools and the language version 1.24 or newer to be available. Please refer to your Linux distribution manuals to obtain the development tools on your system.
Make sure you use a clean copy of the Sonic client source code from the official GitHub repository. A modified client may lead to an inconsistent state, which will disconnect your node from the network.
Build the Sonic client:
Download the latest Sonic client source code from the official GitHub repository.
git clone https://github.com/0xsoniclabs/sonic.git
Switch to the most recent Sonic release.
cd sonic && git fetch --tags && git checkout -b v2.1.2 tags/v2.1.2
(Optional) Verify your source code consistency.
git status && git log -n1
If you are reusing your existing Sonic client source code clone with a patch applied, this patch may prevent you from properly switching to the latest release.
We recommend either deleting the old source code repository and downloading the latest one or cleaning up your local copy using: git checkout -- .
2. Prime Sonic State DB From Genesis File (Optional)
This step applies only if you did not run the client before or you want to launch with a new, clean copy of the Sonic database.
Note that the database of the Sonic client versions 2.0.1 to 2.0.7 is fully compatible with the new Sonic client version v2.1.2. If your node has been running one of the versions v2.0.1 to v2.0.7, and the node has been shut down gracefully, your database can be reused, and you can skip this step.
Download the most recent Sonic network genesis file. Based on your node designated feature set, you need to choose between “pruned” and “full” versions of the genesis file. The pruned one is used by validators so that the database footprint is minimal. The full version contains all the network history and is used for the archive node.
The genesis file will be used to prime your database and will allow you to join the network and synchronize with it after priming. Please double-check the downloaded genesis file using the provided checksum.
You can obtain the selected genesis file here:
Download the genesis file.
wget https://genesis.soniclabs.com/sonic-mainnet/genesis/sonic-38000-full.g
(Optional) Download the genesis checksum file.
wget https://genesis.soniclabs.com/sonic-mainnet/genesis/sonic-38000-full.g.md5
(Optional) Validate the genesis file consistency.
md5sum --check sonic-38000-full.g.md
Expected output is: sonic-38000-full.g: OK
Prime Sonic Database From Downloaded Genesis
Use the sonictool app (created during the building process as build/sonictool) to prime a validated archive state database for the Sonic client.
Start the genesis expansion for archive mode.
GOMEMLIMIT=50GiB sonictool --datadir --cache 12000 genesis --mode rpc
Start the genesis expansion for validator mode.
GOMEMLIMIT=50GiB sonictool --datadir --cache 12000 genesis --mode validator
The last step of the genesis processing is the state validation. Please check that the output log contains a message with the correct root hash:
3. Restart Sonic Node With New Version and Synchronize
With the Sonic node binary created and the state database available, you are ready to start the node on the new version and synchronize its state with the network.
1. Stop Current Node
Stop the running instance gracefully. If you use Systemd manager to handle the Sonic node control, execute the stop procedure: systemctl stop sonicd
Other management systems may require different shutdown procedures. You may also use the general OS termination signal via pkill sonicd. But in this case, you need to make sure the client was terminated, and the control system did not attempt to restart it automatically.
Your Sonic node may need up to several minutes to close gracefully based on your system, configuration, and load. Please make sure your node is not closed forcefully. Your database would become corrupted otherwise.
Wait until the node terminates gracefully. Make sure the node is not running: ps aux|grep sonicd.
This step is . If you run more than one client instance with the same validator key unlocked, your nodes may unintentionally violate the network rules, and your stake may be lost.
2. Start New Node
Use the node database path (<datadir>) from the previous installation or the new expansion created in .
Start the node using the new client version.
systemctl start sonicd
Runtime Settings
Use ≈90% of the RAM as the GOMEMLIMIT value. The limit should always be set. If not done correctly, your node may experience random crashes and subsequent state database corruption. Use ≈12 GiB of the RAM as the --cache value.
Replace the <datadir> with the correct path to the database. We recommend that validators use the --mode validator flag to obtain a smaller database footprint. Different starting flags may need to be added to start an archive node with Web3 RPC and WebSocket interfaces on the node.
Please obtain and explicitly specify the external IP address of your node as a starting flag to help with the inter-node peer-to-peer connectivity.
The second season of the airdrop and Kaito program are ending on November 1, 2025. Future incentive programs will be announced at a later stage.
The S airdrop will distribute 190,500,000 S tokens to incentivize users of Sonic. The airdrop will be distributed using Sonic Points, Sonic Gems, and Game Gems.
Sonic Gems
This page is specific to season 2 of the airdrop.
The second season of the airdrop and Kaito program are ending on November 1, 2025. Future incentive programs will be announced at a later stage.
Sonic Gems are developer-focused airdrop points designed to reward apps for driving user engagement and innovation. These Gems can be redeemed for S tokens, which apps can then distribute as rewards to their users.
This system helps apps grow by driving consistent user activity and maintaining long-term engagement.
/// @dev Register my contract on Sonic FeeM
function registerMe() external {
(bool _success,) = address(0xDC2B0D2Dd2b7759D97D50db4eabDC36973110830).call(
abi.encodeWithSignature("selfRegister(uint256)", <Your FeeM Project ID>)
);
require(_success, "FeeM registration failed");
}
The Solution
For transactions with state-dependent gas costs, it is best practice to add a buffer (e.g., 20-30%) to the estimated gas limit to ensure successful execution. Unused gas is refunded.
There's rarely competition for block space
Transactions are included so quickly that tipping for priority is usually irrelevant
The method name is somewhat misleading - it returns an estimate for inclusion, not a maximum you can set
The 10% buffer is added to prevent transaction rejection due to potential price fluctuations
This buffer ensures transactions won't be rejected as "underpriced"
Or use eth_gasPrice which also returns the buffered value
If calculating the gas fee cap manually, add at least 6% to 10% buffer to the base fee
The transaction pool requires at least 5% buffer above the base fee to accept transactions
The S airdrop spans multiple seasons, with an undisclosed amount of the total airdrop allocated to each season. The first season ended on June 18, 2025, and the second season began immediately after.
The airdrop will also reward historical activity on Opera, participation on Sonic Arcade, and minters of the exclusive Shard NFT.
Distribution
For season 1 of the airdrop, 25% of your allocation is immediately available, while the remaining 75% vests over 270 days as NFT positions that are tradable on the Airdrop Order Book by Paintswap.
A linear decay mechanism applies to the vested portion, allowing you to claim early at the cost of a penalty that burns a portion of your tokens. This approach prevents sudden surges in circulating supply by burning tokens from users who choose to claim early. It also incentivizes recipients to stay active on-chain while waiting for an optimal time to claim the remainder of their allocation.
The chart below illustrates how many tokens will be burned based on when users choose to claim their vested airdrop allocation.
Burn amount of the vested airdrop allocation if claimed early
The above structure currently applies only to season 1, and the distribution for season 2 may differ as we evaluate the impact of the distribution model and optimize the reward structure accordingly.
Burn Amount and Examples
Day
Burn Amount
0–30
100%–88.9%
31–60
88.9%–77.8%
61–90
77.8%–66.7%
91–120
66.7%–55.6%
121–150
55.6%–44.4%
151–180
44.4%–33.4%
Andrew earns 1,000 S in the Sonic airdrop. Andrew can claim his 25% liquid allocation immediately and receive 250 S in his wallet. 90 days pass and Andrew returns to the claim portal, deciding he would like the rest of his airdrop. As 90 days have passed by, he can claim 249.75 S tokens (33.3 of the remaining 750 token allocation) but must burn 500.25 S (66.7% of his locked allocation).
Bob earns 10,000 S in the Sonic airdrop. Bob can claim his 25% liquid allocation immediately and receive 2,500 S. Bob is excited to use his S in the ecosystem and decides he would like all of his eligible airdrop allocation after day 30. Bob claims again (the final 75% portion), receiving 1,110 S and burning 6,667.5 S (88.9% of the final portion).
Data Collection
We are working with OpenBlock and Sentio to manage and oversee our points and airdrop designs through data-backed decision-making.
OpenBlock’s data-driven incentive modeling platform powers over $2B in annual incentive spend and has been a leading provider of rewards design and efficacy analysis for leading protocols in the space including EigenLayer, Lido, Linea, Mode, Arbitrum, Solana, Sui, and many others. To initiate and sustain its ecosystem, Sonic will utilize OpenBlock’s incentive modeling frameworks, ensuring continuous and balanced growth for all actors in the system.
Sentio is an industry-leading indexing service that aids in streamlining continuous point tracking, helping retrieve historical states of all user positions to update user points upon every interaction. With its high-performance database infrastructure, engineered to handle queries at unprecedented speeds, Sentio enables the onboarding of tens of thousands of new users easily and efficiently.
Legal Provisions
As part of the Sonic Foundation’s research and commitment to this airdrop, we have sought legal opinions to ensure its success.
The program will likely need to exclude any sanctioned country or person including all those who are citizens or residents of or residing in (the “Restricted Countries”): Belarus, Burundi, Central African Republic, Congo, Cuba, DPRK (North Korea), Guinea, Guinea-Bissau, Iran, Iraq, Lebanon, Libya, Mali, Myanmar (Burma), Republic of South Sudan, Russia, Somalia, Sudan, Syria, Ukraine, the Crimea, Donetsk, and Luhansk regions of Ukraine, Venezuela, Yemen, or Zimbabwe.
These potential provisions may include:
Geoblocking: Implementing geo-blocking measures for all restricted countries
Self-declaration: Requiring participants to say they are not from one of the restricted countries
Discretionary exclusion: The Sonic Foundation reserves the right to exclude any wallet address at its sole discretion
There will be a comprehensive set of terms and conditions provided at the program’s launch.
Sonic Gems are airdrop points exclusively designed for apps. Each season, a fixed supply of Gems is allocated to apps based on performance metrics. Apps can track their progress through the points dashboard.
To distribute the S tokens earned through Gems to their users, apps must manage the process independently. For example, an app could:
While there’s no strict requirement for apps to share a specific percentage of their claimed S tokens with their users, the design of Gems incentivizes generosity. Apps that share a larger portion of their claimed S with their communities are rewarded more favorably compared to those that do not.
Tokenizing Gems is strictly prohibited. Any app that does so will be instantly disqualified from the entire season.
Distribution of Gems
Sonic Gems are distributed by considering factors such as category type, Sonic exclusivity, revenue generation, and effective reward distribution, promoting fairness and incentivizing active participation.
The competitive PvP nature and fixed supply of Gems mean that an app's Gem balance may fluctuate daily, influenced by the performance of other apps on the platform.
Below are the key criteria that will determine an app's share of Gems in season 1.
Apps are assessed across several weighted categories, with each app assigned a weight based on its primary category. For season 1, the specific weights are detailed below. If an app falls into multiple categories, the weight of its dominant category will be applied.
Category
Weight
Yield Tokenization
4
Isolated / Modular Lending
4
Spot / CLOB DEX
3
Pooled Lending / CDPs
3
Apps are assigned different weights depending on their level of exclusivity to Sonic:
Weight 2: Exclusively available on Sonic
Weight 1: Primarily on Sonic but accessible elsewhere
Weight 0.5: Available across multiple chains
This assesses how effectively an app distributes its claimed S to its users. An app's incentive weight is determined by the percentage of its claimed S that was distributed to its users during the previous season.
For example, if an app distributed 100% of its claimed S from season 1 to its users, it’ll receive a weight of 1 in season 2, while distributing only 80% would give it a weight of 0.8.
While there’s no requirement for apps to distribute a specific amount of their claimed S to users, it’s mandatory for all apps to publicly disclose the percentage they intend to share with their communities.
This transparency allows users to make informed decisions about allocating their capital. Any instances of false communication or misuse of claimed S will result in blacklisting for subsequent seasons.
Point score is determined by calculating the total amount of that an app has generated for its users. This score is then divided by the total points generated across all eligible apps.
Revenue score rewards apps that drive real, sustainable usage.
Only fees from whitelisted assets count toward the revenue score. Revenue-generating apps are beneficial to the network as they:
Contribute directly to network fees and long-term value for S holders
Signal stronger product-market fit and user demand
Final Gems Calculation
Apps will receive a pro-rata share of Sonic Gems based on their final weights, determined by the calculations below.
Step A — Gem Score
App Gem Score=Total Gem ScoreCategory Weight×Sonic Native Weight×Incentive Weight(N/A in Season 1)
Step B — Point Score
App Point Score=Points Generated by App for Users
Step C — Revenue Score
App Revenue Score=Revenue Generated by App
Step D — Final Score
App Final Score=(A⋅B)α⋅Cβ
Step E — Share of Gems
Share of Gems=Total Final ScoreApp Final Score×Total Season 2 Gems
In the calculations above, the Total Gem Score is the sum of the App Gem Scores for all apps, and the same applies to the Total Final Score.
Gems Revocation Policy
The following actions by the app can cause their Sonic Gems to be revoked.
Incentivizing Project Tokens or NFTs with Gems
Allocating Gems as rewards for activities like holding, staking, or providing liquidity (LPing) for a project’s token or NFT. For apps that have a voting mechanism to direct emissions, Gems can be used as vote incentives for any pool other than those that contain the project's token.
Suspicious Distribution Practices
Distributing large quantities of Gems non-transparently, such as allocating them disproportionately to insiders or KOLs without clear disclosure.
Misrepresenting Gem Redistribution
Providing false information about the amount of claimed S being distributed to users during any season.
Failure to Integrate OpenBlock
Failing to integrate with OpenBlock or adhere to its guidelines.
Tokenization
Tokenizing Gems in any way.
Users are encouraged to report any suspicious activity or malpractice to Sonic Labs.
Sonic nodes are generally stable and can run for extended periods without operator intervention. However, in rare cases, the software may encounter failures.
This page outlines the most common causes of such failures, suggests configuration adjustments to prevent them, and provides recovery steps to help you get your node back online as quickly as possible.
1. Recognizing a Failed Node
Regardless of the reason, the outcome of a failure is always the same. The node uses a database to track the state of all accounts, smart contracts, transactions, and the consensus data.
Parts of the database is kept in memory during normal operation. Pre-calculated and updated data is eventually pushed into the persistent storage. If the update cannot finish properly, the persistent copy of the database is in an inconsistent state and can be corrupted.
If the node cannot verify the database integrity and consistency, it refuses to start. The sonicd daemon terminates shortly after you attempt to start it, and the output log will contain an error message similar to this:
You may encounter a similar error message:
database is empty or the genesis import interrupted
In this case, check the correct path set for --datadir and the filesystem privileges on the folders and files on the path. The sonicd daemon needs read/write access to the data folder and the files within.
2. Understanding Why the Node Failed
In general, there are three major reasons for Sonic node failure:
The node resource management configuration is intentionally left for the node operator to decide. This opens options for resource sharing and fine tuning your node to the specific use case you need. If not configured properly, it may also lead to unexpected crashes and failures.
There are lots of different scenarios of the node utilization. Some of them are very predictable and easily controllable, others may be more random. This mostly applies to the RPC interface and its operation. If your RPC load can vary greatly, especially if it involves high input/output disparity calls like utilizing the debug namespace, your node may run out of RAM memory and be forcefully terminated by the operating system.
How to Fix Node Misconfiguration
Check for the environment variableGOMEMLIMIT to be present and set correctly. If the sonicd node is the only user space software running on the system, it should be set between 85% and 90% of the available RAM. Make sure to properly account for any other software running on your system, including modules executed only occasionally or on a schedule. The value should include units for clarity and readability — better use GOMEMLIMIT=28GiB instead of a value in bytes without the unit.
Check the cache size to be explicitly specified and set between 12GiB and 20GiB. Values lower than 12GiB may cause potential issues with processing large blocks. There is no real benefit going over 20GiB of cache. The value itself is specified in MiB. For example, --cache 12000
How to Fix Resource Exhaustion
The most common reason for resource exhaustion leading to a forced node termination and the database corruption is the RPC interface utilization. If the allocated memory crosses a system imposed threshold, the node is terminated unexpectedly and your state DB will be corrupted.
Verify what other software components are utilizing the system resources
Repeated crashes of your Sonic node may suggest there is another system component utilizing the system resources. An example may be a cloud scheduled system update, log clean-up process, a solid state drive sweep and optimization, or a planed backup task. If not accounted for, these components may trigger RAM exhaustion. In such cases, the biggest consumer would be the Sonic node, and the system may decide to terminate it to free the resources needed to finish the pending work. Update your Sonic node resource limits, especially the GOMEMLIMIT and --cache , to account for these components.
Check the usage pattern of your node
Some types of RPC API calls have very high ratios between input and output size. An example would be debug and trace
How to Fix Hardware Failures
A hardware failure usually cannot be predicted, but there are some steps you can take to lower the impact of some types of failures.
Configure graceful shutdown, especially on cloud deployments
Cloud-based systems offer obvious benefits compared to bare metal solutions. They can be deployed easily, scaled dynamically, and migrated very quickly between different regions and/or system groups. If you opt for this type of configuration, make sure the shutdown process of the node uses a graceful ACPI shutdown, or its equivalent, and is set to wait for the procedure to finish. If not possible, configure the shutdown timer so that your Sonic node has enough time to sync its cache with the persistent storage. Please refer to the node deployment guidelines for the usual termination times. A non-cloud environment usually does not suffer from migrations, or unexpected resets, however they still may need to be shutdown for a hardware maintenance. Make sure to configure your system timeouts and the shutdown procedure to always allow your Sonic node to close properly.
Use redundant storage (RAID) to prevent single drive failure caused crash
Persistent storage failure is the most common type of hardware issue you may encounter. The node state data can be easily obtained from the Sonic network. There is no exclusive content on your drive beyond the <datadir>/keystore folder. Surely, your account keys and the validator consensus keys are already backed up securely. However, if your storage drive holding the state DB fails, the system will inevitably crash. To prevent the immediate impact of such failure, you should utilize
A validator node must always use a single instance deployment. If you attempt to run multiple validator nodes with the same signing key, your validator will be penalized for double-signing, removed from the network, and your stake will be slashed.
Monitor your system healthand resources
This may be obvious, but your system will age, and it will fail eventually. Modern systems usually do have sensors which can warn you about possible failures and shortages in advance. Refer to your system documentation for the details about available monitoring solutions, and system level alerts, allowing you to take appropriate steps to resolve an imminent crash before it happens.
3. Recovering From the Node Failure
If your node runs in the validator mode, it does not have enough data to recover from the failure on its own. After you of the node crash, you need to download the latest state snapshot and rebuild the corrupted database from it. Please refer to the validator node deployment guide for the the latest snapshot. You should consider to the of the node software before you proceed.
If your node runs in the RPC mode and it did run at least 15 minutes after the initialization from the snapshot before it crashed, you may be able to recover the live state from the archive database. In this case, follow these steps:
Identify and for the crash.
Make sure you have node version. If your local version is outdated, Sonic node software. Use the version command to check your node version:
Try to recover the state from your archive database.
Note: An app's Sonic-native weight cannot be upgraded during a season. However, if an app takes actions that reduce its Sonic nativeness, its weight will be reduced immediately and remain in effect for the following season as well.
Encourage more efficient use of incentives across the ecosystem
If your app creates real volume and generates real fees, you’ll earn more Gems.
Perps
3
Options / Derivatives
2
Yield Aggregators
2
GambleFi
2
Bridges
2
Incentive Weight=S ClaimedS Distributed to Users
Point Score=Total Sonic Points GeneratedSonic Points Generated By App
User-focused airdrop points, earned by deploying assets as liquidity across apps on Sonic.
Sonic Gems
DeFi-focused airdrop points, earned by apps driving user engagement on Sonic.
Game Gems
Game-focused airdrop points, earned by games driving player engagement and retention.
If the path and access rights are correct, check the genesis import logs. It should confirm a successful import when done. If the process was interrupted for some reason, for example due to insufficient storage size, or an I/O error, you need to fix these issues first and then repeat the import process.
Soft failures, for example storage space exhaustion, are usually detected by the node software correctly. In this case, the node tries to terminate gracefully. If an unpredictable issue arises, the node may terminate forcefully leading to the startup failure described above. This usually happens due to a storage device failure, different types of I/O errors, forcefully imposed operating system limits (file descriptors, open sockets, etc.), or forced system restart.
represents 12 GiB.
Check your operating system limits, especially for open file descriptors and/or sockets. Consult your operating system documentation for your case.
If you use Systemd or a similar software lifecycle management tool, check the shutdown timeout of the service. The node shutdown procedure, if deployed on a recommended solid state drive (SSD), usually takes less than 15 seconds. If you use a remotely connected persistent storage, especially if an intermediate layer like cloud virtualization, or Kubernetes is involved, the shutdown may take significantly longer. We recommend setting the timeout to at least 1 minute.
namespaces and batch API calls. The whole output has to be kept in memory until the user request is resolved. Configure your system according to the expected usage pattern. We recommend at least 64 GiB of RAM for regular RPC nodes. High demand nodes should run on 128 GiB RAM or more.
Do not over-provision cache and/or allocation limits
Increasing cache amount above 20GiB has a diminishing return. You should set it between 12 and 20 GiB. The memory allocated for the cache cannot be used to process RPC calls, and to store the responses to be transmitted to end users. Make sure to set the GOMEMLIMIT value so that the system has enough RAM available for the regular operating system tasks. This is usually between 85% and 90% of the available system RAM. A typical server operating system needs only around 1–2GiB to run properly, but the usage can spike up to 4GiB or more. If your node utilizes a software RAID, you should allocate enough RAM for the module to be able to effectively manage the RAID storage read/write operations.
Moderate access to public RPC API
If your node has a public RPC API interface, we strongly recommend to use a middleware layer moderating access to the node RPC port. A great start would be a proxy server, for example HAproxy, or Nginx, configured to limit the number of parallel requests executed on the node interface. The proxy can create a queue for incoming calls before they can be safely pushed to the node for processing. You can also set the proxy to limit number of incoming calls from a single source, or a group of sources, and reject excessive traffic.
Load-balance your traffic
The best approach to handle unpredictable RPC API traffic is to use multiple backend nodes to resolve and balance the traffic based on resource consumption. This usually requires more complex infrastructure setup. The benefit of such approach is that a regular maintenance does not make your interface inaccessible. Using several smaller systems instead of a single overpowered one may allow you to better control your resources cost, and will make your system way more issue resistant as a whole. The downside is much more complex configuration and maintenance which usually requires knowledge of high availability system setup and scalable architecture deployment.
with the redundancy level configured to match your resiliency expectations.
Use high availability deployment setup for up-time sensitive RPC systems
As discussed above, if your RPC node is part of a critical infrastructure, you should always opt for some level of node redundancy. It would not only allow you to recover after an unexpected system failure, but will also help you perform regular maintenance without experiencing the whole system downtime. A great starting point may be a proxy based load balancer, for example HAproxy.
The heal will attempt to recover the state. If the healing succeeds, you can start your node normally and the node will finish syncing from the network. Any failure means your archive state is not consistent and cannot be used to recover from the failure.
If your heal process failed, you need to remove <datadir>/carmen and <datadir>/chaindata folders, download the latest archive or pruned database snapshot, and rebuild your state from them. Refer to the archive node database priming guide for the details of the process.
This page explains how to use the Sonic Gateway in your application or script to transfer ERC-20 assets from Ethereum to Sonic and back.
Sonic Bridge: Programmatic Usage Guide
Contract Addresses
Setup
Bridge Operations
1. Ethereum to Sonic Transfer
2. Claim Tokens on Sonic
3. Sonic to Ethereum Transfer
4. Claim Tokens on Ethereum
Complete Example
Required ABIs
Important Notes
State Updates
Ethereum → Sonic: Monitor StateOracle.lastBlockNum until it's >= deposit block
Sonic → Ethereum: Monitor StateOracle.lastBlockNum until it's >= withdrawal block
Validator Node
Validator nodes are critical to the Sonic chain, responsible for validating transactions and creating new blocks in accordance with the . These nodes ensure the integrity and security of the network by verifying data, participating in block creation, and maintaining the chain’s state.
Unlike , validator nodes focus on real-time operations rather than storing extensive historical data or responding to general API requests.
To run a validator node on the Sonic mainnet or testnet, follow the steps below.
Steps to Run a Validator
Contract Addresses
Below is a list of all important contract addresses relevant to the Sonic network.
Rewards: ~6% APR initially, plus 15% of delegators' rewards and network fees
The minimum self-stake on Sonic is set at 500,000 S to ensure security during the network's early months, with plans to gradually reduce it.
Mainnet RPC:
Testnet RPC:
WebSocket Endpoint: wss://rpc.soniclabs.com
1. Launch a Server Instance
You can run your validator node on dedicated hardware (bare metal) or use a cloud provider. We recommend choosing one of the established providers, such as Google GCP or Amazon AWS.
Node Hardware Specifications
At least 4 vCPUs and 32 GB of RAM
At least 1 Gbps redundant backbone connectivity for stable and uninterrupted network traffic
At least 1 TB of local SSD/NVMe storage. Remote block devices (e.g., AWS EBS) typically do not provide the required latency and random access performance. Google GCP N2D instances with local SSD or AWS i3en.xlarge with instance storage are good options.
Ubuntu LTS Server (64-bit) or a similar Linux distribution is recommended.
Required Storage Capacity
1 TB of local SSD/NVMe is sufficient for a validator database.
Network Settings
A Sonic node requires both TCP and UDP network traffic allowed on port 5050 by default. You can use --port <port> to customize this if needed.
2. Install Required Development Tools
You need the essential build tools and the latest Go compiler, version 1.24 or newer, to build the Sonic client and its bundled tools. Example (Ubuntu/Debian):
Optionally, copy the binaries to a system-wide location:
4. Prime the Sonic Database
To participate in the Sonic network, you need a valid state database. The fastest way is to use a genesis file from the official repository. Download the appropriate genesis file. For the mainnet, for example:
Use sonictool to prime the state database. Adjust GOMEMLIMIT and --cache according to your available RAM size. For the most common cases, use 12GiB as --cache and ~90% of RAM as GOMEMLIMIT.
After processing, you should see a confirmation of a successfully imported state.
5. Synchronize With the Network
Now that your database is primed, start the node to synchronize it with the network. Ensure your firewall is configured correctly.
The Sonic node will connect to the network and advance its state by processing new blocks. Once fully synchronized, the "age" of new blocks should be only a few seconds.
6. Create a Validator Wallet
Your Sonic node is now synchronizing. Next, create a wallet to identify and control your validator account. This wallet must hold the minimum amount you are going to use as the self-stake (500,000 S).
We recommend creating the wallet securely (e.g. a hardware wallet). If you choose to create it locally using sonictool:
Important: Keep your wallet and keys secure. Never share them.
7. Create a Validator Signing Key
A Sonic validator node signs consensus messages. Your node needs a validator signing key to participate. Create it on the server:
Follow the prompts and set a secure password. Note the public key (starts with 0xc00). This key will be used during registration.
Important: Back up your signing key. Although it cannot move funds, misuse could lead to penalties.
8. Register Your Validator
The network must recognize your validator key. Register by invoking the SFC (Staking and Consensus) contract:
Call createValidator with your validator public key and at least the minimum required stake (500,000 S). Sign this transaction with your validator wallet. After confirmation, query your validator ID using the getValidatorID function. The easiest way would be to open the Sonic explorer and navigate to the SFC address.
The contract is validated and you can interact with it using SonicScan and a connected Web3 wallet. The control validator account can be imported into your Web3 wallet either using the generated JSON key store or as your hardware wallet. With the account open, you can sign the createValidator transaction call specifying the amount of stake and the public key obtained in the previous step.
9. Run Your Validator Node
Stop the currently running node:
Wait for it to gracefully shut down. Never force-terminate it, as it could corrupt the database. Restart your node in validator mode, providing the validator ID, public key, and password file:
Your validator node will now participate in consensus and produce blocks.
10. Validator Name and Logo
Create a config file in JSON format that contains the following parameters (you can also leave parameters empty):
Host it somewhere so it is publicly accessible, such as in this example. Make sure anybody can download the JSON file using a browser and that the hosting site supports HTTPS. A 100x100 logo size is sufficient.
Now you need to insert the JSON URL into the STI contract.
USDC by Circle enables the seamless transfer of digital dollars on Sonic using a smart contract. This guide walks you through building a simple React app that lets users connect their wallet and send USDC on the
{
"name": "VALIDATOR_NAME", /* Name of the validator */
"logoUrl": "LOGO_URL", /* Validator logo (PNG|JPEG|SVG 100x100) starting https:// */
"website": "WEBSITE_URL", /* Website icon on the right */
"contact": "CONTACT_URL" /* Contact icon on the right */
}
/* It could look something like this 👇 */
{
"name": "SonicLabs",
"logoUrl": "https://repository.sonic.soniclabs.com/validator/sonic.svg",
"website": "https://www.soniclabs.com",
"contact": "https://www.soniclabs.com/contact"
}
Join Sonic community channels, follow updates, and use your stake to participate in network governance. If you have issues, the community can provide guidance.
Monitoring and Health
If your node goes offline, you stop earning rewards. Extended downtime (e.g. more than 5 days) may result in suspension, requiring you to withdraw and start over. Regular monitoring, maintenance, and backups are essential.
This repository demonstrates account abstraction on Sonic using both EIP-7702 and ERC-4337 standards through a fully functional on-chain tic-tac-toe game.
It showcases how Sonic is upgrading its infrastructure to support Ethereum's account abstraction features, enabling gasless transactions, smart account capabilities, and enhanced user experiences.
Quick Start
Sonic Testnet
Deploy your own contracts using Hardhat Ignition ()
Frontend Demo
Requires a running for UserOperation submission
Bot Demo
Interacts directly with deployed contracts
Table of Contents
Key Features
🎮 On-Chain Tic-Tac-Toe Game
Fully decentralized 5x5 tic-tac-toe game with 4-in-a-row win condition
Prize token rewards (10 tokens for winners, one token for draws)
Time-limited moves (24-hour timeout protection)
🔐 EIP-7702 Account Abstraction
Transform regular EOAs into smart accounts without changing addresses
Enable transaction batching and gas sponsorship for existing wallets
Demonstrate SET_CODE_TX_TYPE transaction format
📦 ERC-4337 UserOperations
Complete implementation of UserOperation flow
EntryPoint interaction for validation and execution
Support for both MetaMask integration and programmatic signing
💰 Paymaster Infrastructure
TargetCheckingPaymaster: Sponsors gas for whitelisted contract interactions
SignatureCheckingPaymaster: Validates authorized transactions with signature verification
Gas-free gameplay for users
🤖 AI Game Bot
Automated tic-tac-toe player using min-max algorithm
Monitors blockchain events and responds to game moves
# For Sonic testnet
npx hardhat ignition verify --network sonic-testnet
# Clone the bundler (if not already done)
git clone https://github.com/eth-infinitism/bundler
cd bundler
# Configure and run
yarn install
yarn run bundler --network https://rpc.soniclabs.com/ \
--mnemonic path/to/mnemonic.txt \
--entryPoint 0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108 \
--unsafe
# Build the bot
cd cmd/tictactoebot
go build
# Run with configuration
./tictactoebot \
--rpcUrl https://rpc.soniclabs.com/ \
--gameAddress 0xYourGameAddress \
--keystore path/to/keystore.json \
--joiningDelay 30s
cd frontenddemo
npm run dev
# Run all tests
npx hardhat test
# Run with gas reporting
REPORT_GAS=true npx hardhat test
# Run with detailed traces
npx hardhat test --fulltrace
# Run specific test file
npx hardhat test test/TicTacToe.ts
struct PackedUserOperation {
address sender; // Smart account address
uint256 nonce; // Anti-replay parameter
bytes initCode; // Account creation code (if needed)
bytes callData; // Execution calldata
bytes32 accountGasLimits; // Verification and call gas limits
uint256 preVerificationGas; // Gas for bundler overhead
bytes32 gasFees; // maxPriorityFee and maxFeePerGas
bytes paymasterAndData; // Paymaster address and data
bytes signature; // Account signature
}
