	Cover image
Learn more about Somnia	/files/CE8JfY9ZOHjTCWkHgv7f	/spaces/hEUf5l6MCgn0iJsSVgmd/pages/FKOgbxLw2NhwK4XlxSf2
Start developing on Somnia	/files/526bRNiZWR0tnuZi1H7n	/pages/4fa9JM2h1uNNHKeqdaIP
Connect To Mainnet	/files/Yhizjf6iPnpNEoI67TxM	/pages/g3kML4YwJXPHEnZfkGiS

Network	Mainnet	Testnet
Chain ID	5031	50312
Block Explorer	https://explorer.somnia.network	https://shannon-explorer.somnia.network/
Symbol	SOMI	STT
RPC	https://api.infra.mainnet.somnia.network/ wss://api.infra.mainnet.somnia.network/ws	https://api.infra.testnet.somnia.network/ wss://api.infra.testnet.somnia.network/ws
MultiCallV3	0x5e44F178E8cF9B2F5409B6f18ce936aB817C5a11	0x841b8199E6d3Db3C6f264f6C2bd8848b3cA64223
EntryPoint v0.7		0x0000000071727De22E5E9d8BAf0edAc6f37da032
Factory Address		0x4be0ddfebca9a5a4a617dee4dece99e7c862dceb
Alternative Testnet Block Explorer		https://somnia-testnet.socialscan.io/
Testnet Faucet		https://testnet.somnia.network/
Stakely Mainnet Faucet	https://stakely.io/faucet/somnia-somi
CreateX	0xD13C575ED5378fd18B100Bd87D5765d9A747358B	0x535822d4b86b2372FBE4fd9d1468318F04A2A640

RPCs
Ankr	https://www.ankr.com/rpc/somnia
Public Node	https://somnia.publicnode.com
Stakely	https://somnia-json-rpc.stakely.io
Validation Cloud	https://www.validationcloud.io/somnia


Google Cloud Faucet	https://cloud.google.com/application/web3/faucet/somnia/shannon
Stakely	https://stakely.io/faucet/somnia-testnet-stt
Thirdweb Faucet	https://thirdweb.com/somnia-shannon-testnet

Unit	Wei Value	Exp	Ethereum synonym
Somi (SOMI)	1,000,000,000,000,000,000	1e18	Ether (ETH)
milliSomi	1,000,000,000,000,000,	1e15
microSomi	1,000,000,000,000	1e12
nanoSomi	1,000,000,000	1e9	gWei
Wei	1	1	Wei


Reactivity	/pages/JDHkSy1BgMgqLw7PtCx9#welcome-to-the-somnia-reactivity-docs

Contract	Address
MultiCallV3	0x5e44F178E8cF9B2F5409B6f18ce936aB817C5a11
WSOMI	0x046EDe9564A72571df6F5e44d0405360c0f4dCab
USDC	0x28bec7e30e6faee657a03e19bf1128aad7632a00
WETH	0x936Ab8C674bcb567CD5dEB85D8A216494704E9D8
WBTC	0xC5098b3cA516784323872F17235fa074E167D3D2
USDT	0x67B302E35Aef5EEE8c32D934F5856869EF428330
USDso	0x00000022dA000002656c64D9eA6011ea952D008A

Mainnet	Address	Type
BNB Chain	0xa9616e5e23ec1582c2828b025becf3ef610e266f	OFT
Base	0x47636b3188774a3E7273D85A537b9bA4Ee7b253	OFT
Ethereum	0x1B0F6590d21dc02B92ad3A7D00F8884dC4f1aed9	OFT
Somnia	0xC3D4E9Ac47D7f37bB07C2f8355Bb4940DEA3bbC3	NativeOFTAdapter

Contract	Address
endpointV2 (main entrypoint)	0x6F475642a6e85809B1c36Fa62763669b1b48DD5B
sendUln302	0xC39161c743D0307EB9BCc9FEF03eeb9Dc4802de7
receiveUln302	0xe1844c5D63a9543023008D332Bd3d2e6f1FE1043
executor	0x4208D6E27538189bB48E603D6123A94b8Abe0A0b
deadDVN	0x6788f52439ACA6BFF597d3eeC2DC9a44B8FEE842

Contract	Address
Oracle	0xbA0E0750A56e995506CA458b2BdD752754CF39C4
Gas Wallet	0x3073d2E61ecb6E4BF4273Af83d53eDAE099ea04a
USDT	0x936C4F07fD4d01485849ee0EE2Cdcea2373ba267
USDC	0x5D4266f4DD721c1cD8367FEb23E4940d17C83C93
BTC	0xb12e1d47b0022fA577c455E7df2Ca9943D0152bE
ARB	0x6a96a0232402c2BC027a12C73f763b604c9F77a6
SOL	0xa4a3a8B729939E2a79dCd9079cee7d84b0d96234
WETH	0x4E5A9Ebc4D48d7dB65bCde4Ab9CBBE89Da2Add52
SOMI	0x1f5f46B0DABEf8806a1f33772522ED683Ba64E27

Type	Selector	Description	Example
`Error(string)`	`0x08c379a0`	Standard revert reason with message	`require(balance > 0, "Zero balance");`
`Panic(uint256)`	`0x4e487b71`	Internal error (e.g., overflow, div/0, invalid enum)	`assert(x > 0);`
Custom Errors	Function selector of custom error	`error Unauthorized(address caller);`

` tags and replace them with the following: ```html

Hello, World!

``` ## Install Viem ```bash npm i viem ``` [Viem](https://viem.sh) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum.\ \ Viem sets up a “`transport`” infrastructure to connect with a node in the EVM Network and the deployed Smart Contracts.\ \ We will use some ViemJS methods to connect to your Smart Contract deployed on the Somnia Network. ViemJS has a \`createPublicClient\` and a \`createWalletClient\` method. The PublicClient is used to perform READ operations, while the WalletClient is used to perform WRITE operations. ## Import Methods The next step is to set up the React State methods and the ViemJS methods that we will require: ```typescript import { useState } from "react"; import { createPublicClient, http, createWalletClient, } from "viem"; ``` The `http` is the transport protocol for interacting with the Node of the Somnia Blockchain via RPC. It uses the default Somnia RPC URL: [`https://dream-rpc.somnia.network`](https://dream-rpc.somnia.network). In the future developers can use RPC providers to avoid rate limiting. ## Import Somnia Import Somnia Testnet ```typescript import { somniaTestnet } from "viem/chains"; ``` ## Declare React States State allows us to manage changing data in the User Interface. For this example application, we are going to manage two states: * When we can read the User's Address * When a User is connected (Authorization) Add the states inside the export statement: ```typescript const [address, setAddress] = useState(""); const [connected, setConnected] = useState(false); ``` Now that the States are declared, we can declare a function to handle the MetaMask authentication process on Somnia Network. ## Connect MetaMask Function Add the function below inside the export statement: ```typescript const connectToMetaMask = async () => { if (typeof window !== "undefined" && window.ethereum !== undefined) { try { await window.ethereum.request({ method: "eth_requestAccounts" }); const walletClient = createWalletClient({ chain: SOMNIA, transport: custom(window.ethereum), }); const [userAddress] = await walletClient.getAddresses(); setClient(walletClient); setAddress(userAddress); setConnected(true); console.log("Connected account:", userAddress); } catch (error) { console.error("User denied account access:", error); } } else { console.log( "MetaMask is not installed or not running in a browser environment!" ); } }; ``` ## Update the UI MetaMask connection is set up, and the final step is to test the connection via the User Interface. Update the `

Hello, World!

` in the return statement to the following: ```typescript {!connected ? ( ) : (

Connected as: {address}

)} ``` Open your terminal and run the following command to start the app: ```bash npm run dev ``` Go to `localhost:3000` in your Web Browser to interact with the app and connect to Somnia Network via MetaMask.\ \ You can read more about using Viem to interact with the deployed Smart Contract methods on Somnia Network [here](/developer/development-frameworks/using-the-viem-library).\ \ Congratulations, you have successfully connected from MetaMask to Somnia Network. 🎉
# Authenticating with ConnectKit In this guide, we'll integrate [ConnectKit](https://docs.family.co/connectkit) with the Somnia Network in a Next.js application. This will enable users to connect their wallets seamlessly, facilitating interactions with the Somnia blockchain. ## Prerequisites Before we begin, ensure you have the following: 1. This guide is not an introduction to JavaScript Programming; you are expected to understand JavaScript. 2. To complete this guide, you will need MetaMask installed and the Somnia DevNet added to the list of Networks. If you have yet to install MetaMask, please follow the [Connect Your Wallet guide](/get-started/connect-your-wallet-to-mainnet). 3. Familiarity with React and Next.js is assumed. ## Create the Next.js Project Open your terminal and run the following commands to set up a new Next.js project: ```bash npx create-next-app@latest somnia-connectkit cd somnia-connectkit ``` Install the required Dependencies, which are **`wagmi`**, **`viem`**, **`@tanstack/react-query`**, and **`connectkit`**. Run the following command: ```bash npm install wagmi viem @tanstack/react-query connectkit ``` ## Set Up Providers in Next.js We'll set up several providers to manage the application's state and facilitate interactions with the blockchain. \ Create a **`components`** directory in the app folder. Inside the components directory, create a file named **`ClientProvider.tsx`** with the following content: ```typescript 'use client'; import { WagmiConfig, createConfig } from 'wagmi'; import { ConnectKitProvider, getDefaultConfig } from 'connectkit'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { somniaTestnet } from 'viem/chains'; const queryClient = new QueryClient(); const config = createConfig( getDefaultConfig({ autoConnect: true, appName: 'Somnia DApp', chains: [somniaTestnet], }) ); export default function ClientProvider({ children }) { return ( {children} ); } ``` In the app directory, locate the **`layout.tsx`** file and update it as follows: ```typescript import ClientProvider from './components/ClientProvider'; export default function RootLayout({ children }) { return ( Somnia DApp {children} ); } ``` ## Build the Home Page We'll create a simple home page that allows users to connect their wallets and displays their address upon connection. In the app directory, locate the **`page.tsx`** file and update it as follows: ```typescript 'use client'; import { useAccount } from 'wagmi'; import { ConnectKitButton } from 'connectkit'; export default function Home() { const { address, isConnected } = useAccount(); return (

Hello, world! {/* Connect Button */}

{/* Show Wallet Address */} {isConnected && (

Connected as: {address}

)}

); } ``` To run the application, start the Development Server by running the following command: ```bash npm run dev ``` Open your browser and navigate to **`http://localhost:3000`**. You should see the ConnectKit button, which allows users to connect their wallets to the Somnia network. ## Conclusion You've successfully integrated ConnectKit with the Somnia Network in a Next.js application. This setup provides a foundation for building decentralized applications on Somnia, enabling seamless wallet connections and interactions with the Somnia Network. For further exploration, consider adding features such as interacting with smart contracts, displaying user balances, or implementing transaction functionalities. If you encounter any issues or need assistance, join the[ Somnia Developer Discord](https://discord.gg/somnia).
# Authenticating with Privy [Privy](https://docs.privy.io/) is a secure, embeddable wallet infrastructure provider that allows developers to authenticate users, manage sessions, and provide seamless wallet experiences within dApps.\ \ Privy embedded wallets can be made interoperable across apps. Somnia has adopted the global wallets setup to foster a cross-app ecosystem where users can easily port their wallets from one app to another in the Somnia Ecosystem. Using **global wallets**, users can seamlessly move assets between different apps and easily prove ownership of, sign messages, or send transactions with their existing wallets. Developers do not have to worry that users will generate a new wallet to sign into different applications. Kindly read more [here](https://docs.privy.io/wallets/global-wallets/overview).\ \ This guide will integrate Privy with the Somnia Testnet, enabling users to create and connect wallets effortlessly.

## Prerequisites * This guide is not an introduction to JavaScript Programming; you are expected to understand JavaScript. * To complete this guide, sign up for [Privy](https://dashboard.privy.io/) and get an AppID and get the Somnia Provider AppID. * Familiarity with React and Next.js is assumed. ## Installation ### Create the Next.js Project Open your terminal and run the following commands to set up a new Next.js project: ```bash npx create-next-app@latest somnia-privy cd somnia-privy ``` Install the necessary packages ```bash npm install @privy-io/react-auth viem ``` ## Set Up PrivyProvider Go to to set up an account. Click "**`New App`**" to create a new application that will connect to the Somnia Provider AppID.

Open the newly created app and in the left side navigation menu navigate to: **`User Management >>>> Global Wallet >>>> Integrations`**
Click the toggle to turn ON the Somnia Provider App.

Wrap your application **`layout.ts`** file with PrivyProvider and supply your PrivateKey from Privy and the Somnia Provider App ID to the **`loginMethods`**: ```typescript 'use client'; import { PrivyProvider } from '@privy-io/react-auth'; import { somniaTestnet } from 'viem/chains'; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( {children} ); } ``` Add your environment variable in .env.local: ```bash NEXT_PUBLIC_PRIVY_APP_ID=your-privy-app-id ``` ## Privy Hooks These hooks make it easy to authenticate users, manage wallets, and interact with the Somnia Network using Privy Global Wallet ```typescript import { useCrossAppAccounts, usePrivy } from '@privy-io/react-auth'; ``` ## Authenticate Use the provided hooks to authenticate users and access their wallets.

page.tsx

export default function Home() {

  const { loginWithCrossAppAccount } = useCrossAppAccounts();
  const { ready, authenticated, user, logout } = usePrivy();
  const disableLogin = !ready || (ready && authenticated);
  
  const [loginError, setLoginError] = useState<string | null>(null);
  const [walletAddress, setWalletAddress] = useState<string | null>(null);
  
  const providerAppId = 'cm8d9yzp2013kkr612h8ymoq8';
  
  const startCrossAppLogin = async () => {
    try {
      setLoginError(null);
      const result = await loginWithCrossAppAccount({
        appId: providerAppId,
      });
      setWalletAddress(result.wallet?.address)
      console.log(
        'Logged in via global wallet:',
        result,
      );
    } catch (err) {
      console.warn('Cross-app login failed:', err);
      setLoginError('Failed to log in with Global Wallet.');
    }
  };
  
......
  
    {!ready ? (
          <p>Loading...</p>
        ) : authenticated ? (
            {walletAddress ? (
              <p>Connected as: {walletAddress}</p>
            ) : (
              <p className='text-gray-600'>No wallet address found.</p>
            )}
            <button
              onClick={logout}
              className='bg-red-600 text-white px-4 py-2 rounded'
            >
              Logout
            </button>
          </div>
          
        ) : (
          <>
            <button
              onClick={startCrossAppLogin}
              className='bg-purple-600 text-white px-4 py-2 rounded'
            >
              Login with Global Wallet
            </button>
            {loginError && <p className='text-red-500 text-sm'>{loginError}</p>}
          </>          </div>
        )}
        
}

## Send Transactions Once authenticated, use the **`useSendTransaction`** hook from `useCrossAppAccount` method to interact with Somnia Testnet: ```typescript const { sendTransaction } = useCrossAppAccounts(); ...... const sendSTT = async () => { if (!walletAddress) return; const txn = { to: '0xb6e4fa6ff2873480590c68D9Aa991e5BB14Dbf03', value: 1000000000000000, chainId: 50312, }; try { const tx = await sendTransaction(txn, { address: walletAddress }); console.log('TX Sent:', tx); } catch (err) { console.error('TXN Failed:', err); } }; ...... ``` ## Complete Code

Complete page.tsx code

```typescript 'use client'; import { usePrivy, useCrossAppAccounts, } from '@privy-io/react-auth'; import { useEffect, useState } from 'react'; import { createPublicClient, http, formatEther } from 'viem'; import { somniaTestnet } from 'viem/chains'; export default function Home() { const { ready, authenticated, user, logout } = usePrivy(); const { loginWithCrossAppAccount, sendTransaction } = useCrossAppAccounts(); const [loginError, setLoginError] = useState(null); const [hydrated, setHydrated] = useState(false); const [walletAddress, setWalletAddress] = useState(null); const [balance, setBalance] = useState(''); const providerAppId = 'cm8d9yzp2013kkr612h8ymoq8'; const client = createPublicClient({ chain: somniaTestnet, transport: http(), }); const startCrossAppLogin = async () => { try { setLoginError(null); const result = await loginWithCrossAppAccount({ appId: providerAppId, }); console.log( 'Logged in via global wallet:', result, ); } catch (err) { console.warn('Cross-app login failed:', err); setLoginError('Failed to log in with Global Wallet.'); } }; useEffect(() => { if (authenticated) { const globalWallet = user?.linkedAccounts?.find( (account) => account.type === 'cross_app' && account.providerApp?.id === providerAppId ); console.log(globalWallet); const wallet = globalWallet?.smartWallets?.[0]; console.log(wallet); if (wallet?.address) { setWalletAddress(wallet.address); setHydrated(true); fetchBalance(wallet.address); } else if (user?.wallet?.address) { setWalletAddress(user.wallet.address); setHydrated(true); fetchBalance(user.wallet.address); } else { setHydrated(true); } } }, [authenticated, user]); const fetchBalance = async (address: string) => { try { const result = await client.getBalance({ address: address as `0x${string}`, }); const formatted = parseFloat(formatEther(result)).toFixed(3); setBalance(formatted); } catch (err) { console.error('Failed to fetch balance:', err); } }; const sendSTT = async () => { if (!walletAddress) return; console.log(walletAddress); const txn = { to: '0xb6e4fa6ff2873480590c68D9Aa991e5BB14Dbf03', value: 1000000000000000, chainId: 50312, }; try { const tx = await sendTransaction(txn, { address: walletAddress }); console.log('TX Sent:', tx); if (walletAddress) fetchBalance(walletAddress); } catch (err) { console.error('TXN Failed:', err); } }; return (

{!ready ? (

) : !authenticated ? ( <> {loginError &&

{loginError}

} ) : hydrated ? (

{walletAddress ? (

Connected as: {walletAddress}

) : (

No wallet address found.

)}

Balance: {balance ? `${balance} STT` : 'Loading...'}

) : (

🔄 Logging in... Please wait

)}

); } ```

By using Privy Global Wallet on the Somnia Testnet, developers can offer a seamless onboarding and wallet experience. This setup is ideal for onboarding Web2 users into Web3 with embedded wallets, abstracting away traditional wallet complexities.
# Authenticating with RainbowKit In this guide, we'll integrate [RainbowKit](https://www.rainbowkit.com/docs/introduction) with the Somnia Network in a Next.js application. This will enable users to connect their wallets seamlessly, facilitating interactions with the Somnia blockchain. ## Prerequisites Before we begin, ensure you have the following: 1. This guide is not an introduction to JavaScript Programming; you are expected to understand JavaScript. 2. To complete this guide, you will need MetaMask installed and the Somnia DevNet added to the list of Networks. If you have yet to install MetaMask, please follow this guide to [Connect Your Wallet guide](/get-started/connect-your-wallet-to-mainnet). 3. Familiarity with React and Next.js is assumed. ## Create the Next.js Project Open your terminal and run the following commands to set up a new Next.js project: ```bash npx create-next-app@latest somnia-rainbowkit cd somnia-rainbowkit ``` Install the required Dependencies, which are **`wagmi`**, **`viem`**, @tanstack/react-query, and rainbowkit. Run the following command: ```bash npm install wagmi viem @tanstack/react-query rainbowkit ``` ### Set Up Providers in Next.js We'll set up several providers to manage the application's state and facilitate interactions with the blockchain. \ Create a **`components`** directory in the app folder. Inside the components directory, create a file named **`ClientProvider.tsx`** with the following content: ```typescript 'use client'; import { WagmiProvider } from "wagmi"; import { RainbowKitProvider, getDefaultConfig, } from "@rainbow-me/rainbowkit"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { somniaTestnet } from "viem/chains"; const queryClient = new QueryClient(); const config = getDefaultConfig({ appName: "Somnia Example App", projectId: "Get_WalletConnect_ID", chains: [somniaTestnet], ssr: true, }); export default function ClientProvider({ children }) { return ( {children} ); } ``` > Every Rainbowkit dApp relies on **WalletConnect** and needs to obtain a **`projectId`** from WalletConnect Cloud. Get one [here](https://cloud.walletconnect.com/). In the app directory, locate the **`layout.tsx`** file and update it as follows: ```typescript import ClientProvider from './components/ClientProvider'; export default function RootLayout({ children }) { return ( Somnia DApp {children} ); } ``` ### Build the Home Page We'll create a simple home page that allows users to connect their wallets and displays their address upon connection. In the app directory, locate the **`page.tsx`** file and update it as follows: ```typescript 'use client'; import { useAccount } from 'wagmi'; import { ConnectButton } from "@rainbow-me/rainbowkit"; export default function Home() { const { address, isConnected } = useAccount(); return (

{isConnected && (

Connected as: {address}

)}

); } ``` ### Run the Application Start the Development Server by running the following command: ```bash npm run dev ``` Open your browser and navigate to . You should see the RainbowKit button, allowing users to connect their wallets to the Somnia network. ## Conclusion You've successfully integrated RainbowKit with the Somnia Network in a Next.js application. This setup provides a foundation for building decentralized applications on Somnia, enabling seamless wallet connections and interactions with the Somnia Network. For further exploration, consider adding features such as interacting with smart contracts, displaying user balances, or implementing transaction functionalities. If you encounter any issues or need assistance, join the[ Somnia Developer Discord](https://discord.gg/somnia).
# OnRamps OnRamps make it easy for users to move from the traditional financial system into the Somnia ecosystem by purchasing tokens directly with their local currency. This section covers how to integrate **Banxa**, Somnia’s trusted onramping service, to enable seamless and secure fiat-to-crypto transactions within your dApps. You’ll learn how to: * Embed Banxa’s checkout flow in your application * Support multiple payment methods (credit/debit card, bank transfer, etc.) * Customize the onramp experience to match your app’s branding * Streamline user onboarding with a direct path from fiat to onchain activity > Banxa provides developers and users with a regulated, global, and developer-friendly solution for accessing the Somnia network — making your application more inclusive and easier to adopt. # Buy SOMI Using Banxa Checkout You can easily buy SOMI tokens using Banxa, a trusted fiat to crypto gateway partner.\ This guide walks you through purchasing SOMI directly from the[ Banxa Checkout Portal](https://checkout.banxa.com/). *** Banxa lets you buy cryptocurrency with local payment methods, including credit/debit cards, bank transfers, and mobile wallets.\ In this guide, you’ll learn how to: * Access the Banxa checkout page * Select SOMI as the token to purchase * Complete payment securely * Receive SOMI in your wallet *** ## Prerequisites Before you start, ensure you have: * Your wallet address handy, this is where SOMI will be sent. * A valid payment method supported in your region (Visa, Mastercard, bank transfer, etc.). *** ## Step 1 — Visit the Banxa Checkout Page Go to[ https://checkout.banxa.com/](https://checkout.banxa.com/).\ You’ll see a simple interface to select your fiat currency and cryptocurrency. ***

## Step 2 — Choose Your Purchase Options * In the “You Pay” field, enter how much fiat (e.g. USD, EUR, NGN) you want to spend. * In the “You Get” field, select SOMI as the token. * Select the network as Somnia Network. Banxa will automatically show the conversion rate, fees, and delivery estimate. *** ## Step 3 — Enter Your Wallet Address Copy your wallet address from your Somnia-compatible wallet (e.g. MetaMask) and paste it into the “Wallet Address” field. {% hint style="danger" %} ***Triple check the address before proceeding. Funds sent to the wrong address cannot be recovered.*** {% endhint %} *** ## Step 4 — Complete KYC Verification Banxa complies with international regulations and may ask you to verify your identity.\ Typical verification steps include: * Uploading a government-issued ID * Taking a selfie * Confirming your billing address This process only needs to be done once per account.

*** ## Step 5 — Select a Payment Method Choose one of the available payment options for your country: * Credit/Debit Card * Bank Transfer * Apple Pay / Google Pay (where supported) Follow the on-screen instructions to complete the payment. *** ## Step 6 — Receive SOMI in Your Wallet Once payment is confirmed: * Banxa will process the transaction. * SOMI tokens will be sent directly to your wallet on the Somnia Network. * You’ll receive a confirmation email once the transfer is complete. This may take a few minutes, depending on network congestion and payment method. *** ## Need Help? If your transaction is delayed or you need assistance, you can contact: * Banxa Support:[ support.banxa.com](https://support.banxa.com/) * Somnia Community:[ Discord → #support](https://discord.gg/somnia) *** ## Disclaimers * Banxa is a third party provider. Always ensure you are using the official[ checkout.banxa.com](https://checkout.banxa.com/) link. * Transaction fees, limits, and verification steps vary by country and payment method. * SOMI purchases are non reversible once processed.
# Cross-chain Swaps and Bridging Most users don't start their journey on Somnia, their assets live on Ethereum, Arbitrum, Base, Solana, and dozens of other chains. To grow your dApp, you need a smooth way to move that liquidity **into, out of, and across** the Somnia ecosystem. There are two ways to bring assets across, depending on who is doing the work: * **For end users (no code):** Somnia's official bridge partners, [**Relay**](https://relay.link/bridge) and [**Stargate Finance**](https://stargate.finance/), let anyone bridge assets through their own interfaces. If you just need users to move funds and don't want to build any UI, point them to the [Bridging Info](/get-started/bridging-info) guide. * **For developers (this section):** embed swaps and bridging **directly inside your dApp** with the [**LI.FI**](https://li.fi/) **SDK**, so users never have to leave your app. *** ## Why LI.FI for in-app bridging LI.FI is the routing and execution layer for cross-chain liquidity. A single integration aggregates dozens of bridges and DEX aggregators across 50+ chains **(including Somnia's official partners Relay and Stargate)** normalises token standards, picks the optimal route, and monitors execution for you. In other words, integrating LI.FI doesn't replace Relay or Stargate, it routes *through* them (and many others) and chooses the best option per transfer. A live USDC transfer from Arbitrum to Somnia, for example, is currently routed via Stargate under the hood. LI.FI is **infrastructure.** It does the routing and execution, while *you* own the user experience. (The same way [Jumper Exchange](https://jumper.exchange/) is LI.FI's own front-end, your dApp becomes its own bridge/swap interface.) You'll learn how to: * [Add cross-chain and same-chain swaps directly inside your Somnia dApp with the **LI.FI SDK**](/developer/building-dapps/cross-chain-swaps-and-bridging/integrating-the-li.fi-sdk) * Let users **bridge assets to and from Somnia** in your own UI * Request **routes and quotes**, execute them, and **track transaction status** in-app * Query supported **chains, tokens, bridges, and exchanges** programmatically *** ## Choosing an integration path LI.FI offers several integration surfaces. This section focuses on the **SDK**, which gives you full programmatic control over the route lifecycle. | Path | Best for | Effort | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------ | | **SDK** (`@lifi/sdk`) | Custom swap/bridge flows where you build the UI and control every step | Medium | | Widget (`@lifi/widget`) | Dropping a ready-made, themeable swap/bridge UI into a React app | Low | | REST API (`li.quest/v1`) | Backend services, bots, and AI agents that construct requests directly | Medium | | Bridge UIs ([Relay](https://relay.link/bridge) / [Stargate](https://stargate.finance/)) | End users moving funds manually — no integration needed | None | > Whichever path you choose, LI.FI's official documentation is the source of truth for the latest implementation details: [https://docs.li.fi](https://docs.li.fi/). {% hint style="info" %} **Somnia at a glance** — when configuring LI.FI for Somnia, use Chain ID **`5031`**, native currency **SOMI** (18 decimals), RPC `https://api.infra.mainnet.somnia.network/`. Always confirm live route and token support with the LI.FI API before going to production (see the SDK guide). {% endhint %} # Integrating the LI.FI SDK The [**LI.FI**](https://li.fi/) **SDK** lets you add cross-chain and same-chain swaps and bridging directly inside your Somnia dApp. Instead of redirecting users to an external bridge, you request a route, execute it, and track its status. All from your own interface. Under the hood, LI.FI aggregates dozens of bridges and DEX aggregators across 50+ chains, normalises token standards, and picks the optimal route. Your dApp only talks to one SDK. In this guide, you'll learn how to: * Install and configure the LI.FI SDK for Somnia * Request a quote to **bridge assets into Somnia** * Execute the route and **track its status** in your app * Query supported **chains, tokens, and tools** to keep your UI accurate {% hint style="info" %} The LI.FI SDK is a JavaScript/TypeScript toolkit that runs in both front-end and back-end environments. This guide shows the front-end (browser wallet) flow. For the full API surface and the latest details, always refer to the official docs: . {% endhint %} ## Prerequisites Before you start, ensure you have: * A working JavaScript/TypeScript dApp (React or Next.js recommended). This guide assumes familiarity with both. * Wallet connection already set up. If not, see [Wallet Integration and Auth](/developer/building-dapps/wallet-integration-and-auth). * [Node.js](https://nodejs.org/) 18+ and a package manager (npm, pnpm, or yarn). * The Somnia network details on hand: | Property | Value | | --------------- | ------------------------------------------- | | Chain ID | `5031` | | Native currency | SOMI (18 decimals) | | RPC URL | `https://api.infra.mainnet.somnia.network/` | | Explorer | `https://explorer.somnia.network` | ## Step 1: Install the SDK The SDK uses [Viem](https://viem.sh/) under the hood, so install it alongside. ```bash npm install @lifi/sdk viem ``` {% hint style="info" %} This guide was written and verified against `@lifi/sdk` v3.16.x and `viem` v2.x. API surfaces evolve — if a signature differs in your version, the [official SDK docs](https://docs.li.fi/sdk/overview) are the source of truth. {% endhint %} ## Step 2: Configure the SDK Call `createConfig` once when your app boots. The `integrator` string identifies your app to LI.FI (and is used for fee monetisation later). Because Somnia may not ship in Viem's default chain list, define it explicitly with `defineChain` so the SDK's wallet provider can switch to it. {% code title="lib/lifi.ts" %} ```typescript import { createConfig, EVM, ChainId } from '@lifi/sdk'; import { createWalletClient, custom, defineChain } from 'viem'; import { mainnet, arbitrum, optimism, base } from 'viem/chains'; import { switchChain } from 'viem/actions'; // Somnia may be newer than the ChainId enum in your installed SDK version, // so cast the numeric id where the SDK's TypeScript types expect a ChainId. const SOMNIA = 5031 as ChainId; // Define Somnia Mainnet for Viem export const somnia = defineChain({ id: 5031, name: 'Somnia', nativeCurrency: { name: 'Somnia', symbol: 'SOMI', decimals: 18 }, rpcUrls: { default: { http: ['https://api.infra.mainnet.somnia.network/'] }, }, blockExplorers: { default: { name: 'Somnia Explorer', url: 'https://explorer.somnia.network' }, }, }); // Chains your dApp will let users move assets between const chains = [mainnet, arbitrum, optimism, base, somnia]; // A Viem wallet client backed by the user's injected wallet (e.g. MetaMask) const walletClient = createWalletClient({ chain: mainnet, transport: custom(window.ethereum!), }); createConfig({ integrator: 'YourSomniaDApp', // required; max 23 chars (letters, numbers, . - _) rpcUrls: { [SOMNIA]: ['https://api.infra.mainnet.somnia.network/'], // let the SDK use Somnia's RPC }, providers: [ EVM({ getWalletClient: async () => walletClient, switchChain: async (chainId) => { await switchChain(walletClient, { id: chainId }); return walletClient; }, }), ], }); ``` {% endcode %} {% hint style="success" %} The SDK automatically fetches chain, bridge, and token metadata from LI.FI at runtime — you don't have to hard-code bridge addresses. The `defineChain` block is only needed so the wallet can **switch networks** during execution, and `rpcUrls` lets the SDK use your preferred Somnia endpoint. For production, pass an authenticated RPC URL rather than a public one. {% endhint %} {% hint style="warning" %} **TypeScript note:** the SDK's types use a `ChainId` enum for parameters like `rpcUrls` keys and `getTokens({ chains })`. If your installed SDK version predates Somnia's addition to that enum, the raw number `5031` will fail to type-check — cast it with `5031 as ChainId` (shown above). The runtime value is unaffected; this is purely a type-level workaround. `getQuote`'s `fromChain` / `toChain` accept a plain `number` and need no cast. {% endhint %} ## Step 3: Request a quote A **quote** is a single, ready-to-execute route with the optimal pricing LI.FI could find. The example below bridges **USDC on Arbitrum → USDC.e on Somnia** (routed via Stargate at the time of writing). Amounts are always passed as strings in the token's **smallest unit** (USDC has 6 decimals, so `10` USDC = `"10000000"`). A chain's native token is represented by the zero address. {% code title="Bridge USDC (Arbitrum) → USDC.e (Somnia)" %} ```typescript import { getQuote } from '@lifi/sdk'; const quote = await getQuote({ fromChain: 42161, // Arbitrum toChain: 5031, // Somnia fromToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC on Arbitrum toToken: '0x28BEc7E30E6faee657a03e19Bf1128AaD7632A00', // USDC.e (bridged USDC) on Somnia fromAmount: '10000000', // 10 USDC (6 decimals) fromAddress: userWalletAddress, // the connected wallet }); console.log(quote.estimate.toAmount); // estimated USDC.e received (6 decimals) ``` {% endcode %} ### Tokens routable to Somnia These are the tokens LI.FI can currently route to Somnia (Chain ID `5031`): | Symbol | Address | Decimals | Notes | | ------ | -------------------------------------------- | -------- | ----------------------- | | SOMI | `0x0000000000000000000000000000000000000000` | 18 | Native gas token | | WSOMI | `0x046EDe9564A72571df6F5e44d0405360c0f4dCab` | 18 | Wrapped SOMI | | USDC.e | `0x28BEc7E30E6faee657a03e19Bf1128AaD7632A00` | 6 | Bridged USDC (Stargate) | | USDT | `0x67B302E35Aef5EEE8c32D934F5856869EF428330` | 6 | Bridged USDT (Stargate) | | WETH | `0x936Ab8C674bcb567CD5dEB85D8A216494704E9D8` | 18 | Wrapped ETH | {% hint style="warning" %} This list reflects LI.FI's coverage at the time of writing and grows over time. Always fetch the current set with `getTokens` at runtime rather than hard-coding it (see [Step 6](#step-6-keep-your-ui-in-sync)). {% endhint %} ## Step 4: Execute the route A quote must first be converted to a **route** with `convertQuoteToRoute`, then passed to `executeRoute`. The SDK handles token approvals, network switching, and signing through the wallet provider you configured in Step 2. Use `updateRouteHook` to react to progress in your UI. ```typescript import { convertQuoteToRoute, executeRoute } from '@lifi/sdk'; // A quote cannot be executed directly — convert it to a route first const route = convertQuoteToRoute(quote); const executedRoute = await executeRoute(route, { updateRouteHook: (updatedRoute) => { // Called whenever the route changes during execution — drive your progress UI from here updatedRoute.steps.forEach((step, i) => { step.execution?.process.forEach((process) => { console.log(`Step ${i + 1}:`, process.type, process.status); if (process.txHash) console.log(' tx hash:', process.txHash); }); }); }, }); ``` {% hint style="info" %} `executeRoute` also accepts other hooks such as `acceptExchangeRateUpdateHook` (confirm a changed rate before continuing) and `switchChainHook`. See the official [Execute Routes](https://docs.li.fi/sdk/execute-routes) guide for the full list. {% endhint %} ## Step 5: Handle the outcome Status updates arrive through the `updateRouteHook` from Step 4, read each step's `execution.status` and `execution.process` to drive your UI. Cross-chain transfers don't always end in an exact 1:1 result, so handle the final states explicitly: | Final state | Meaning | What to show the user | | ----------- | -------------------------------------------------------------- | ------------------------------------------- | | Completed | Success, exact destination token received | "Funds arrived on Somnia" | | Partial | Success, but a different token was received (still full value) | "Completed, received an alternate token" | | Refunded | The transfer failed and funds were returned | "Refunded on the source chain" | | Failed | Execution failed | Prompt the user to retry or contact support | {% hint style="info" %} A **same-chain** swap is atomic: it either fully succeeds or reverts. A **cross-chain** transfer can have the bridge succeed while the destination step fails, in that case the bridged asset is refunded on the destination chain. {% endhint %} To resume tracking an interrupted transfer (for example, after a page reload), the SDK can pick up an in-progress route again. See the official [Execute Routes](https://docs.li.fi/sdk/execute-routes) guide. For server-side or out-of-band status checks, query the REST [status endpoint](https://docs.li.fi/api-reference/check-the-status-of-a-cross-chain-transfer) directly. ## Step 6: Keep your UI in sync Use the SDK's query helpers to populate dropdowns and **verify that Somnia routes and tokens are live** before showing them to users. ```typescript import { ChainId, ChainType, getChains, getTokens, getTools } from '@lifi/sdk'; // Confirm Somnia (5031) is currently supported const chains = await getChains({ chainTypes: [ChainType.EVM] }); const somniaSupported = chains.some((c) => c.id === 5031); // Tokens available on Somnia — getTokens returns a map keyed by chain ID // (cast 5031 to ChainId if your SDK version predates Somnia in the enum) const { tokens } = await getTokens({ chains: [5031 as ChainId] }); const somniaTokens = tokens[5031] ?? []; // Available bridges and exchanges const { bridges, exchanges } = await getTools(); ``` {% hint style="warning" %} Somnia support on LI.FI is live and expanding. Treat `getChains` and `getTokens` as the source of truth at runtime rather than hard-coding lists, new tokens and bridges are added regularly. {% endhint %} ## Monetization (optional) Integrators can charge a fee on transactions routed through their app. Configure a fee when requesting a route and withdraw collected fees via LI.FI's Partner Portal. See the official guide for the current setup: . ## Troubleshooting * **No route found:** Try a different token pair or a larger amount. Very small amounts may not cover bridge/gas costs. * **Slippage / minimum-received error:** Increase the `slippage` parameter (default `0.005` = 0.5%) when requesting the quote. * **Rate limited (`429`):** Without an API key you're limited to 200 requests / 2 hours. [Request a key](https://li.fi/) for production and back off with retries. * **Insufficient balance:** Ensure the user holds enough of the source token **plus** native gas on the source chain. * **Network switch fails:** Confirm Somnia (`5031`) is added to the user's wallet. See [Connect Your Wallet to Mainnet](/get-started/connect-your-wallet-to-mainnet). ## Need Help? * LI.FI SDK docs (source of truth): * Somnia Discord: * Somnia Developer Telegram: ## Disclaimers * LI.FI is a third-party provider. Always integrate from the official packages (`@lifi/sdk`) and verify chain/token data against the live API. * Bridging and swapping involve smart-contract and market risk. Test thoroughly on a small amount before enabling production flows. # Account Abstraction Account Abstraction (AA) revolutionizes how users interact with blockchain applications by making wallets **smarter, simpler, and more programmable**. In this section, you’ll explore how to implement **Smart Contract Accounts (SCAs)** on Somnia using modern tooling like **Thirdweb** and **Privy**, and learn how to enable **gasless transactions** and **session keys** for better UX. You’ll learn how to: * Create and manage smart contract wallets * Implement user operations via ERC-4337-style flows * Enable sponsored and gasless transactions * Simplify onboarding through smart wallets and relayers > Account Abstraction bridges the gap between Web2 simplicity and Web3 ownership — empowering developers to build dApps users actually love to use. # Gasless Transactions with Thirdweb This tutorial demonstrates how to build a gasless NFT minting application on Somnia using Thirdweb's Account Abstraction infrastructure. Users can mint NFTs without holding STT tokens by using **Smart Accounts** with **sponsored transactions**. ## Prerequisites * Basic knowledge of React and Next.js * A Thirdweb account and API key * A deployed ERC721 NFT Smart Contract on Somnia ### What You'll Build A web application where users can: * Connect using email or social accounts (via in-app wallets) * Mint NFTs without paying gas fees * View their NFT balance * Experience seamless Web3 interactions ## Create a Next.js Project ```bash npx create-next-app@latest somnia-gasless-nft --typescript --tailwind --app cd somnia-gasless-nft ``` ## Install Thirdweb SDK ```bash npm install thirdweb ``` ## Set Up Environment Variables Create a .env.local file in your project root: ```bash NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_client_id_here ``` Get your Client ID from the[ Thirdweb Dashboard](https://thirdweb.com/dashboard/settings). ## Deploy a Simple NFT Contract If you haven't already, deploy this simple ERC721 contract on Somnia.

SimpleNFT.sol

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; contract SimpleNFT is ERC721 { uint256 private _tokenIdCounter; constructor() ERC721("SimpleNFT", "SNFT") {} function mint(address to) public { uint256 tokenId = _tokenIdCounter; _tokenIdCounter++; _safeMint(to, tokenId); } function totalSupply() public view returns (uint256) { return _tokenIdCounter; } } ```

## Create Constants Configuration Now we need to set up our configuration file that will handle all the blockchain connections and smart account setup. This file will: * Initialize the Thirdweb client with your API key * Set up both traditional wallet and in-app wallet options * Define the smart account infrastructure Create a new folder called constants in your project root, then create `constants/index.ts.`

constants

```typescript import { createThirdwebClient, getContract } from 'thirdweb'; import { SmartWalletOptions, inAppWallet } from 'thirdweb/wallets'; import { somniaTestnet } from 'thirdweb/chains'; // Validate environment variables const clientId = process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID; if (!clientId) { throw new Error('No client ID provided'); } // Initialize Thirdweb client export const client = createThirdwebClient({ clientId: clientId, }); // Use Somnia testnet export const chain = somniaTestnet; // Your deployed NFT contract address export const nftContractAddress = '0x...'; // UPDATE with your contract address // Get contract instance export const nftContract = getContract({ address: nftContractAddress, chain, client, }); // Account Abstraction configuration for standard wallet connection export const accountAbstraction: SmartWalletOptions = { chain, sponsorGas: true, // Enable gasless transactions }; // Smart Account infrastructure addresses const FACTORY_ADDRESS = '0x4be0ddfebca9a5a4a617dee4dece99e7c862dceb'; // Thirdweb Account Factory // In-app wallet configuration with smart accounts export const wallets = [ inAppWallet({ smartAccount: { chain: somniaTestnet, sponsorGas: true, factoryAddress: FACTORY_ADDRESS, }, }), ]; ```

## Create the Main Minting Page This is the main component where users will interact with your NFT minting application. We'll break this into three parts: imports and setup, the component logic, and the UI rendering. ### Imports and Component Setup First, let's set up our imports and initialize the component. Create `app/page.tsx`.

page.tsx

These imports provide: * `ERC721 Extensions`: Functions to read NFT data (balance and total supply) * `React Components`: Pre-built UI components for wallet connection and transactions * `Hooks`: To access the connected account and read blockchain data * All our constants from the previous step ### Component Logic and Data Fetching Now let's add the component logic that handles wallet connections and reads blockchain data:

page.tsx

```typescript export default function Home() { // Get the currently connected account (either smart account or regular wallet) const account = useActiveAccount(); // State for showing transaction progress const [txStatus, setTxStatus] = useState(''); // Read the total number of NFTs minted from the contract const { data: totalMinted } = useReadContract(totalSupply, { contract: nftContract, }); // Read how many NFTs the connected user owns const { data: userBalance } = useReadContract(balanceOf, { contract: nftContract, owner: account?.address!, queryOptions: { enabled: !!account }, // Only fetch when account is connected }); ```

* `useActiveAccount()`: Gets the connected wallet/smart account * `useState`: Manages transaction status messages * `useReadContract`: Automatically fetches and updates blockchain data The queries will re-fetch automatically when accounts change or transactions complete ## User Interface Now let's build the complete UI that users will interact with

page.tsx

```typescript 'use client'; import { useState } from 'react'; import { balanceOf, totalSupply } from 'thirdweb/extensions/erc721'; import { ConnectButton, TransactionButton, useActiveAccount, useReadContract, } from 'thirdweb/react'; import { prepareContractCall } from 'thirdweb'; import { accountAbstraction, client, nftContract, wallets, } from '../../constants'; import Link from 'next/link'; const GaslessHome: React.FC = () => { const account = useActiveAccount(); const [txStatus, setTxStatus] = useState(''); // Get total supply const { data: totalMinted } = useReadContract(totalSupply, { contract: nftContract, }); // Get user's balance const { data: userBalance } = useReadContract(balanceOf, { contract: nftContract, owner: account?.address!, queryOptions: { enabled: !!account }, }); return (

{/* Main Title */}

Gasless NFT Minting on Somnia

{/* Wallet Connection Button */} {/* NFT Display and Minting Section */}

{/* Stats Card */}

{totalMinted?.toString() || '0'}

Total NFTs Minted

{/* NFT Visual Representation */}

NFT

SimpleNFT on Somnia

{/* Conditional Rendering: Connected vs Not Connected */} {account ? (

{/* User Stats */}

You own{' '} {userBalance?.toString() || '0'} {' '} NFTs

Wallet: {account.address.slice(0, 6)}...{account.address.slice(-4)}

{/* Transaction Status */} {txStatus && (

{txStatus}

)} {/* Mint Button */} prepareContractCall({ contract: nftContract, method: 'function mint(address to)', params: [account.address], }) } onError={(error) => { console.error('Transaction error:', error); setTxStatus(''); // User-friendly error messages let errorMessage = 'Transaction failed'; if (error.message?.includes('insufficient funds')) { errorMessage = 'Insufficient funds for gas'; } else if (error.message?.includes('rejected')) { errorMessage = 'Transaction rejected by user'; } else if (error.message?.includes('500')) { errorMessage = 'Service temporarily unavailable'; } alert(`Error: ${errorMessage}`); }} onTransactionSent={(result) => { console.log('Transaction sent:', result.transactionHash); setTxStatus('Transaction submitted! Waiting for confirmation...'); }} onTransactionConfirmed={async (receipt) => { console.log('Transaction confirmed:', receipt); setTxStatus(''); alert('NFT minted successfully!'); }} className='px-8 py-4 bg-gradient-to-r from-purple-600 to-blue-600 hover:from-purple-700 hover:to-blue-700 rounded-lg font-semibold transition-all transform hover:scale-105 shadow-lg' > Mint NFT (Gasless)

) : ( {/* Not Connected State */}

Connect your wallet to mint NFTs without gas fees!

)}

{/* Navigation - Removed since this is now the home page */}

); }; ```

### Understanding the UI Components `ConnectButton`: This component handles both connection methods: * `In-App Wallets`: Users can sign in with email, Google, Apple, etc. * `Traditional Wallets`: Users can connect MetaMask, WalletConnect, etc. Both methods automatically create smart accounts for gasless transactions `TransactionButton`: This component prepares and sends the transaction automatically. Handling all wallet interactions and confirmations, and provides callbacks for different transaction states. It also shows loading states automatically Error Handling: The component provides user-friendly error messages instead of technical blockchain errors, improving the user experience. ## Update the Layout The layout file wraps your entire application and is where we set up the Thirdweb provider. This provider is essential as it: * Manages wallet connections across your app * Handles blockchain interactions * Provides React hooks for reading blockchain data * Manages transaction states Update `app/layout.tsx`:

layout.tsx

```typescript import type { Metadata } from "next"; import { Inter } from "next/font/google"; import "./globals.css"; import { ThirdwebProvider } from "thirdweb/react"; const inter = Inter({ subsets: ["latin"] }); export const metadata: Metadata = { title: "Gasless NFT Minting on Somnia", description: "Mint NFTs without gas fees using Account Abstraction", }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return (

{children}

); } ```

## Conclusion You've successfully built a gasless NFT minting application on Somnia! This implementation leverages Thirdweb's Account Abstraction to provide a seamless Web3 experience where users can interact with blockchain without holding native tokens. For more advanced features and updates on Somnia support, check: * [Thirdweb Account Abstraction Guide](https://portal.thirdweb.com/connect/account-abstraction) ### Resources * [Live Demo](https://nextjs-thirdweb-somnia.vercel.app/) # Smart Wallet App with Thirdweb The Somnia mission is to enable the development of mass-consumer real-time applications. The Somnia Network allows developers to build a unique experience by implementing Smart Contract Wallets with gasless transactions via Account Abstraction (ERC-4337). In this tutorial, we'll use the [Thirdweb React SDK](https://portal.thirdweb.com/react/v5) to: * Connect Smart Wallets (Account Abstraction) * Read Wallet Balance * Send STT Tokens ## Pre-requisites Before we start, ensure you have: * Basic knowledge of React * A [Thirdweb](https://thirdweb.com/) account & Client ID * Node.js & npm installed ## Install Dependencies Run the following command to set up your project: ```bash npx create-next-app@latest somnia-thirdweb cd somnia-thirdweb npm install thirdweb ethers viem dotenv ``` This installs: `thirdweb` → The Thirdweb React SDK. `ethers` → To interact with blockchain transactions. `dotenv` → To securely store API keys. ## Create the Thirdweb Client The Thirdweb client allows the app to communicate with the blockchain. Create a **`client.ts`** file and add: ``` import { createThirdwebClient } from "thirdweb"; export const client = createThirdwebClient({ clientId: process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID as string, // Replace with your actual Client ID }); ``` {% hint style="info" %} Get your Client ID: Register at thirdweb.com/dashboard. 💡 {% endhint %} ## Add Environment Variables Store API keys in a .env.local file: ``` NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your-client-id-here NEXT_PUBLIC_SOMNIA_RPC_URL=https://dream-rpc.somnia.network/ ``` Restart Next.js after modifying .env.local ## Build the Account Abstraction App To ensure Thirdweb Components are available throughout the app, wrap the children's components inside ThirdwebProvider. Modify **`layout.ts`**: ```typescript import { ThirdwebProvider } from 'thirdweb/react'; {children} ``` ## Create & Connect Smart Contract Wallet The **`useActiveAccount`** hook allows us to detect the connected Smart Wallet Account. We use **`ConnectButton`** to handle authentication and connection to the blockchain. ```typescript import { useActiveAccount } from "thirdweb/react"; const smartAccount = useActiveAccount(); ``` This button will connect the user's Smart Contract Wallet and authenticate the user with Thirdweb. After connection, it will also display the wallet address.

To show the connected address, we add the following UI component: ```typescript {smartAccount ? (

Connected as: {smartAccount.address}

{message &&

{message}

}

) : (

Please connect your wallet.

)} ``` ## Token Transfer The **`useSendTransaction`** hook is used to send STT tokens to another address. The function **`sendTokens`** will check that the Smart Account is connected and then send 0.01 STT tokens to a recipient address. First, copy your Smart Wallet Address and request for Tokens on Discord in the **dev-chat,** you can also Transfer some from your EOA. Log transaction success or failure messages to the console. ``` import { useSendTransaction } from "thirdweb/react"; import { ethers } from "ethers"; const { mutate: sendTransaction, isPending } = useSendTransaction(); const sendTokens = async () => { if (!smartAccount) { setMessage("No smart account connected."); return; } console.log("Sending 0.01 STT from:", smartAccount.address); sendTransaction( { to: "0xb6e4fa6ff2873480590c68D9Aa991e5BB14Dbf03", value: ethers.parseUnits("0.01", 18), chain: somniaTestnet, client, }, { onSuccess: (receipt) => { console.log("Transaction Success:", receipt); setMessage(`Sent 0.01 STT! TX: ${receipt.transactionHash}`); }, onError: (error) => { console.error("Transaction Failed:", error); setMessage("Transaction failed! Check console."); }, } ); }; ``` ## Button Integration The button UI provides a clear interaction for sending STT tokens. The button shows a loading state (Sending...) when the transaction is pending and displays a success or failure message once the transaction is complete. ```typescript const [message, setMessage] = useState(''); {message &&

{message}

} ```

Complete Code

```typescript 'use client'; import { useState } from 'react'; import { ConnectButton, useActiveAccount, useSendTransaction, } from 'thirdweb/react'; import { ethers } from 'ethers'; import { client } from './client'; import { somniaTestnet } from 'viem/chain'; export default function Home() { const [message, setMessage] = useState(''); const smartAccount = useActiveAccount(); // Get connected account const { mutate: sendTransaction, isPending } = useSendTransaction(); const sendTokens = async () => { if (!smartAccount) { setMessage('No smart account connected.'); return; } console.log('🚀 Sending 0.01 STT from:', smartAccount.address); sendTransaction( { to: '0xb6e4fa6ff2873480590c68D9Aa991e5BB14Dbf03', // Replace value: ethers.parseUnits('0.01', 18), chain: somniaTestnet, client, }, { onSuccess: (receipt) => { console.log('Transaction Success:', receipt); setMessage(`Sent 0.01 STT! TX: ${receipt.transactionHash}`); }, onError: (error) => { console.error('Transaction Failed:', error); setMessage('Transaction failed! Check console.'); }, } ); }; return (

{smartAccount ? (

Connected as: {smartAccount.address}

{message &&

{message}

}

) : (

Please connect your wallet.

)}

); } ```

The full implementation includes wallet connection, balance retrieval, and token transfer.

## Conclusion Congratulations! 🎉 You have successfully connected a smart contract wallet using Thirdweb. Read wallet balances and Transferred STT tokens on Somnia Testnet. You can explore additional features such as gasless transactions, NFT integration, and DeFi applications.
# Data Indexing and Querying Subgraphs allow your dApp to efficiently index and query onchain data from the Somnia Network. Whether you're building dashboards, tracking events, or querying user actions, Subgraphs provide a scalable way to make your smart contract data accessible and searchable. In this section, you’ll learn: * [How to create and deploy subgraphs on Somnia using **ORMI**](/developer/building-dapps/data-indexing-and-querying/ormi-subgraph) * [How to build with **Protofire’s subgraph infrastructure**](/developer/building-dapps/data-indexing-and-querying/protofire-subgraph) * [Frontend integrations for building responsive UIs from your subgraph data](/developer/building-dapps/data-indexing-and-querying/building-subgraph-uis-nextjs-fetch) > Subgraphs are essential for any developer building real-time dApps, analytics dashboards, or event-driven logic on Somnia. # Ormi Subgraph The Graph is a decentralized indexing protocol that allows developers to query blockchain data using GraphQL. Instead of parsing complex raw logs and events directly from smart contracts, developers can build subgraphs that transform onchain activity into structured, queryable datasets. This tutorial demonstrates how to deploy a subgraph on the Somnia Testnet using [Ormi](https://ormilabs.com), a powerful gateway that simplifies subgraph deployment through a hosted Graph Node and IPFS infrastructure. {% embed url="" %} ## Prerequisites * GraphQL is installed and set up on your local machine. * A verified smart contract address deployed on Somnia. * An Ormi account and Private Key. ## Install Graph CLI globally ```bash npm install -g @graphprotocol/graph-cli ``` ## Initialize Your Subgraph The Graph services rely on the existence of a deployed Smart Contract with onchain activity. The subgraph will be created based on indexing the events emitted from the Smart Contract. To set up a subgraph service for an example contract called **`MyToken`** run the following command to scaffold a new subgraph project: ```bash graph init --contract-name MyToken --from-contract 0xYourTokenAddress --network somnia-testnet mytoken ``` **`mytoken`** is the folder that contains the subgraph files. Replace `0xYourTokenAddress` with your actual deployed Smart Contract address on Somnia. This command will generate the following files: * `subgraph.yaml`Defines the data sources and events to index * `schema.graphql` Structure of your data * `src/mytoken.ts`TypeScript logic to handle events ## Define the Subgraph Schema For the example`MyToken` Contract, which is an ERC20 Token, Edit `schema.graphql` to index all the Transfer events emitted from the Smart Contract. ```typescript type Transfer @entity(immutable: true) { id: Bytes! from: Bytes! to: Bytes! value: BigInt! blockNumber: BigInt! blockTimestamp: BigInt! transactionHash: Bytes! } ``` ## Build the Subgraph After customizing your schema and mapping logic, build the subgraph by running the command: ``` graph codegen && graph build ``` This will generate the necessary `artifacts` for deployment. ## Deploy Using Ormi Open the Somnia Ormi website and create an account.

On the left navigation menu, click the "key" icon to access your `privateKey.`

Deploy your subgraph to Ormi’s hosted infrastructure with the following command: ```bash graph deploy mytoken --node https://api.subgraph.somnia.network/deploy --ipfs https://api.subgraph.somnia.network/ipfs --deploy-key yourORMIPrivateKey ``` Replace yourPrivateKey with your Somnia Ormi account private key. Once deployed, Ormi will return a GraphQL endpoint where you can begin querying your subgraph. Return to the dashboard to find your list of deployed subgraphs.

Open the deployed subgraph in the explorer to interact with it:

## Conclusion You have successfully deployed a subgraph to index events emitted from your Smart Contract. To challenge yourself even further, you can extend your build: * Expand your schema and mapping logic to cover more events. * Connect your subgraph to a frontend UI or analytics dashboard.
For more information, visit the Ormi [docs](https://docs.ormilabs.com/dedicated-env/somnia/subgraphs/overview). # Protofire Subgraph The blockchain is an ever-growing database of transactions and Smart Contract events. Developers use subgraphs, an indexing solution provided by the Graph protocol, to retrieve and analyze this data efficiently. A graph in this context represents the structure of blockchain data, including token transfers, contract events, and user interactions. A subgraph is a customized indexing service that listens to blockchain transactions and structures them in a way that can be easily queried using GraphQL. {% embed url="" %} ## Prerequisites * This guide is not an introduction to Solidity Programming; you are expected to understand Basic Solidity Programming. * GraphQL is installed and set up on your local machine. ```bash npm install -g @graphprotocol/graph-cli ``` ## Deploy a Simple ERC20 Token on Somnia We will deploy a basic ERC20 token on the Somnia network using Hardhat. Ensure you have Hardhat, OpenZeppelin, and dotenv installed: ```bash npm install --save-dev hardhat @nomicfoundation/hardhat-ignition-ethers @openzeppelin/contracts dotenv ethers ``` ## Create an ERC20 Token Contract Create a new Solidity file: `contracts/MyToken.sol` and update it ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.25; import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; contract MyToken is ERC20 { constructor(uint256 initialSupply) ERC20("MyToken", "MTK") { _mint(msg.sender, initialSupply * 10**decimals()); } function mint(address to, uint256 amount) external { _mint(to, amount); } function burn(uint256 amount) external { _burn(msg.sender, amount); } } ``` ## Create a Deployment Script Create a new file in `ignition/modules/MyTokenModule.ts` ```typescript import { buildModule } from "@nomicfoundation/hardhat-ignition/modules"; export default buildModule("MyTokenModule", (m) => { const initialSupply = m.getParameter("initialSupply", 1000000n * 10n ** 18n); const myToken = m.contract("MyToken", [initialSupply]); return { myToken }; }); ``` ## Deploy the Smart Contract Open the hardhat.config.js file and update the network information by adding Somnia Network to the list of networks. Copy your Wallet Address Private Key from MetaMask, and add it to the accounts section. Ensure there are enough STT Token in the Wallet Address to pay for Gas. You can get some from the Somnia Faucet.
```javascript module.exports = { // ... networks: { somniaTestnet: { url: "https://dream-rpc.somnia.network", accounts: ["0xPRIVATE_KEY"], // put dev menomonic or PK here, }, }, // ... }; ``` Open a new terminal and deploy the smart contract to the Somnia Network. Run the command: ```bash npx hardhat ignition deploy ./ignition/modules/MyTokenModule.ts --network somniaTestnet ``` This will deploy the ERC20 contract to the Somnia network and return the deployed contract address. ## Simulate On-Chain Activity Once deployed, we will create a script to generate multiple transactions on the blockchain. Create a new file `scripts/interact.js`

interact.js

```javascript require("dotenv").config(); const { ethers } = require("hardhat"); async function main() { // Connect to Somnia RPC const provider = new ethers.JsonRpcProvider(process.env.SOMNIA_RPC_URL); // Load wallets from .env const deployer = new ethers.Wallet(process.env.PRIVATE_KEY_1, provider); const user1 = new ethers.Wallet(process.env.PRIVATE_KEY_2, provider); const user2 = new ethers.Wallet(process.env.PRIVATE_KEY_3, provider); const user3 = new ethers.Wallet(process.env.PRIVATE_KEY_4, provider); const user4 = new ethers.Wallet(process.env.PRIVATE_KEY_5, provider); const contractAddress = "0xBF9516ADc5263d277E2505d4e141F7159B103d33"; // Replace with your deployed contract address const abi = [ "function transfer(address to, uint256 amount) external returns (bool)", "function mint(address to, uint256 amount) external", "function burn(uint256 amount) external", ]; // Attach to the deployed ERC20 contract const token = new ethers.Contract(contractAddress, abi, provider); console.log("🏁 Starting Token Transactions Simulation on Somnia..."); // Simulate Transfers const transfers = [ { from: deployer, to: user1.address, amount: "1000" }, { from: deployer, to: user2.address, amount: "1000" }, { from: user1, to: user2.address, amount: "50" }, { from: user2, to: user3.address, amount: "30" }, { from: user3, to: user4.address, amount: "10" }, { from: user4, to: deployer.address, amount: "5" }, { from: deployer, to: user2.address, amount: "100" }, { from: user1, to: user3.address, amount: "70" }, { from: user2, to: user4.address, amount: "40" }, ]; for (const tx of transfers) { const { from, to, amount } = tx; const txResponse = await token.connect(from).transfer(to, ethers.parseUnits(amount, 18)); await txResponse.wait(); console.log(`✅ ${from.address} sent ${amount} MTK to ${to}`); } // Simulate Minting const mintAmount1 = ethers.parseUnits("500", 18); const mintTx1 = await token.connect(deployer).mint(user1.address, mintAmount1); await mintTx1.wait(); console.log(`✅ Minted ${ethers.formatUnits(mintAmount1, 18)} MTK to User1!`); const mintAmount2 = ethers.parseUnits("300", 18); const mintTx2 = await token.connect(deployer).mint(user2.address, mintAmount2); await mintTx2.wait(); console.log(`✅ Minted ${ethers.formatUnits(mintAmount2, 18)} MTK to User2!`); // Simulate Burning const burnAmount1 = ethers.parseUnits("50", 18); const burnTx1 = await token.connect(user1).burn(burnAmount1); await burnTx1.wait(); console.log(`🔥 User1 burned ${ethers.formatUnits(burnAmount1, 18)} MTK!`); const burnAmount2 = ethers.parseUnits("100", 18); const burnTx2 = await token.connect(user2).burn(burnAmount2); await burnTx2.wait(); console.log(`🔥 User2 burned ${ethers.formatUnits(burnAmount2, 18)} MTK!`); console.log("🏁 Simulation Complete on Somnia!"); } main() .then(() => process.exit(0)) .catch((error) => { console.error(error); process.exit(1); }); ```

Create an `.env` file to hold sensitive informations such as the private keys ```properties SOMNIA_RPC_URL=https://dream-rpc.somnia.network PRIVATE_KEY_1=0x... PRIVATE_KEY_2=0x... PRIVATE_KEY_3=0x... PRIVATE_KEY_4=0x... PRIVATE_KEY_5=0x... ``` #### Run the Script ```bash node scripts/interact.js ``` This will generate several on-chain transactions for our subgraph to index. ## Deploy a Subgraph on Somnia Go to and connect your Wallet.

First, you need to create a private key for deploying subgraphs. To do so, please go to [Somnia Protofire Service](https://somnia.chain.love) and create an Account. You are now able to create subgraphs. Click the create button and enter the required details.

After initialising the subgraph on the next step is to create and deploy the subgraph via the terminal. ## Initialize the Subgraph ```bash graph init --contract-name MyToken --from-contract 0xYourTokenAddress --network somnia-testnet mytoken ```

Then, update networks.json to use Somnia’s RPC ```bash { "somnia-testnet": { "network": "Somnia Testnet", "rpc": "https://dream-rpc.somnia.network", "startBlock": 12345678 } } ``` ## Define the Subgraph Schema 📁 Edit schema.graphql ```bash type Transfer @entity(immutable: true) { id: Bytes! from: Bytes! to: Bytes! value: BigInt! blockNumber: BigInt! blockTimestamp: BigInt! transactionHash: Bytes! } ``` ## Build the Subgraph ```bash graph codegen graph build ``` ## Deploy the Subgraph ```bash graph deploy --node https://proxy.somnia.chain.love/graph/somnia-testnet --version-label 0.0.1 somnia-testnet/test-mytoken --access-token=your_token_from_somnia_chain_love ```

## Query the Subgraph Once your subgraph is deployed and indexing blockchain data on Somnia, you can retrieve information using GraphQL queries. These queries allow you to efficiently access structured data such as token transfers, approvals, and contract interactions without having to scan the blockchain manually. Developers can query indexed blockchain data in real time using the Graph Explorer or a GraphQL client. This enables DApps, analytics dashboards, and automated systems to interact more efficiently with blockchain events. This section demonstrates how to write and execute GraphQL queries to fetch blockchain data indexed by the subgraph. Go to ### Fetch Latest Transfers ```json { transfers(first: 10, orderBy: blockTimestamp, orderDirection: desc) { id from to value blockTimestamp transactionHash } } ``` ### Get Transfers by Address ```json { transfers(where: { from: "0xUserWalletAddress" }) { id from to value } } ``` ### Get Transfers in a Time Range ``` { transfers(where: { blockTimestamp_gte: "1700000000", blockTimestamp_lte: "1710000000" }) { id from to value } } ``` ## Conclusion This tutorial provides a complete pipeline for indexing blockchain data on Somnia using The Graph! 🔥
# Building Subgraph UIs (NextJS/Fetch) [Subgraphs](https://somnia.chain.love) allow developers to efficiently query Somnia blockchain data using GraphQL, making it easy to index and retrieve real-time blockchain activity. In this tutorial, you’ll learn how to: * Fetch blockchain data from a Subgraph API * Fix CORS errors using a NextJS API route * Display token transfers in a real-time UI By the end of this guide, you'll have a fully functional UI that fetches and displays token transfers from Somnia’s Subgraph API. ## Prerequisites * Basic knowledge of React & Next.js. * A deployed Subgraph API on Somnia ([or use an existing one](https://somnia.chain.love/graph)). * Account on see [guide](/developer/building-dapps/data-indexing-and-querying/protofire-subgraph). ## Create a NextJS Project Start by creating a new Next.js app. ```bash npx create-next-app@latest somnia-subgraph-ui cd somnia-subgraph-ui ``` Then, install required dependencies. ```bash npm install thirdweb react-query graphql ``` ## Define the Subgraph API in Environment Variables Create a .env.local file in the root folder. ``` NEXT_PUBLIC_SUBGRAPH_URL=https://proxy.somnia.chain.love/subgraphs/name/somnia-testnet/test-mytoken NEXT_PUBLIC_SUBGRAPH_CLIENT_ID=YOUR_CLIENT_ID ``` {% hint style="info" %} 💡 Note: Restart your development server after modifying .env.local: {% endhint %} ```bash npm run dev ``` ## Create a NextJS API Route for the Subgraph Since the Somnia Subgraph API has CORS restrictions, we’ll use a NextJS API route to act as a proxy. Inside the app directory create the folder paths **`api/proxy`** and add a file **`route.ts`** Update the **`route.ts`** file with the following code: ```typescript import { NextResponse } from "next/server"; const SUBGRAPH_URL = process.env.NEXT_PUBLIC_SUBGRAPH_URL as string; const CLIENT_ID = process.env.NEXT_PUBLIC_SUBGRAPH_CLIENT_ID as string; export async function POST(req: Request) { try { const body = await req.json(); const response = await fetch(SUBGRAPH_URL, { method: "POST", headers: { "Content-Type": "application/json", "Client-ID": CLIENT_ID, // ✅ Pass the Subgraph Client ID }, body: JSON.stringify(body), }); const data = await response.json(); return NextResponse.json(data); } catch (error) { console.error("Proxy Error:", error); return NextResponse.json({ error: "Failed to fetch from Subgraph" }, { status: 500 }); } } ``` This code allows your frontend to make requests without triggering CORS errors. ## Fetch and Display Token Transfers in the UI Now that we have the API set up, let’s build a React component that: * Sends the GraphQL query using fetch() * Stores the fetched data using useState() * Displays the token transfers in a simple UI To fetch the latest 10 token transfers, we’ll use this GraphQL query: ```graphql { transfers(first: 10, orderBy: blockTimestamp, orderDirection: desc) { id from to value blockTimestamp transactionHash } } ``` This code fetches the last 10 transfers (first: 10) and orders them by timestamp (latest first). It retrieves wallet addresses (from, to) and the amount transferred (value) and includes the transaction hash (used to generate an explorer link). ## Fetch and Display Data in a React Component Now, let’s integrate the query into our NextJS frontend. Create a folder **`components`** and add a file **`TokenTransfer.ts`** We use **`useState()`** to store transfer data and **`useEffect()`** to fetch it when the component loads. ```typescript "use client"; import { useEffect, useState } from "react"; export default function TokenTransfers() { // Store transfers in state const [transfers, setTransfers] = useState([]); // Track loading state const [loading, setLoading] = useState(true); Next, we fetch the token transfer data when the component loads. useEffect(() => { async function fetchTransfers() { setLoading(true); // Show loading state const query = ` { transfers(first: 10, orderBy: blockTimestamp, orderDirection: desc) { id from to value blockTimestamp transactionHash } } `; const response = await fetch("/api/proxy", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query }), }); const { data } = await response.json(); setTransfers(data.transfers || []); // Store results in state setLoading(false); // Hide loading state } fetchTransfers(); }, []); ``` Once data is fetched, we render it inside the UI. ```typescript return (

Latest Token Transfers

{loading ? (

Loading transfers...

) : (

From: {transfer.from}

To: {transfer.to}

Value: {parseFloat(transfer.value) / 1e18} STT

TX:{" "} View Transaction

)}

); } ``` The UI shows a loading message while data is being fetched. When data is ready, it displays the latest 10 token transfers. It formats transaction values (value / 1e18) to show the correct STT amount and provides a link to view each transaction on Somnia Explorer. ## Add the Component to the NextJS Page Update the page.tsx file: ```typescript "use client"; import TokenTransfers from "../components/TokenTransfers"; export default function Home() { return (

Welcome to MyToken Dashboard

); } ``` Restart the development server: ``` npm run dev ```

Now your NextJS UI dynamically fetches and displays token transfers from Somnia’s Subgraph! 🔥
# Building Subgraph UIs (Apollo Client) This guide will teach you how to create a minimal, functional UI that queries blockchain data from a Somnia subgraph using Next.js, Apollo Client, and GraphQL. ## Prerequisites * Basic knowledge of React and Next.js * Node.js 20+ * A deployed subgraph on Somnia (we'll use [SomFlip](https://shannon-explorer.somnia.network/address/0x014F851965F281d6112FC7F6dfe8c331C413Eb9b) as an example) ## What You'll Build A clean, minimal interface that: * Displays all coin flip results with pagination * Shows a live feed that auto-refreshes every 5 seconds ## Create a Next.js Project Start by creating a new Next.js application with TypeScript and TailwindCSS: ```bash npx create-next-app@latest somnia-subgraph-ui --typescript --tailwind --app cd somnia-subgraph-ui ``` Install the required GraphQL dependencies: ```bash npm install @apollo/client graphql ``` ## Understand the Architecture Before we code, let's understand how the pieces fit together: ``` User Interface (React Components) ↓ Apollo Client (GraphQL Client) ↓ GraphQL Queries ↓ Somnia Subgraph API ↓ Blockchain Data ``` ## Set Up Apollo Client Apollo Client is a comprehensive GraphQL client that manages data fetching, caching, and state management. Create a `lib` directory and create a file `apollo-client.ts` ```typescript import { ApolloClient, InMemoryCache } from '@apollo/client'; const client = new ApolloClient({ // The URI of your subgraph endpoint uri: 'https://proxy.somnia.chain.love/subgraphs/name/somnia-testnet/SomFlip', // Apollo's caching layer - stores query results cache: new InMemoryCache(), }); export default client; ``` The `URI` is the endpoint where your subgraph is hosted, and `InMemoryCache` will store the query results in memory for fast access ## Create the Apollo Provider Wrapper React components need access to the Apollo Client. We'll create a wrapper component that provides this access to the entire app. Create a `components` directory and create a file `ApolloWrapper.tsx`. ```typescript 'use client'; // Next.js 13+ directive for client-side components import { ApolloProvider } from '@apollo/client'; import client from '@/lib/apollo-client'; // This component wraps your app with Apollo's context provider export default function ApolloWrapper({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` ApolloProvider: Makes the Apollo Client available to all child components ## Update app/layout.tsx ```typescript import ApolloWrapper from '@/components/ApolloWrapper'; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` ## Create GraphQL Queries GraphQL queries define exactly what data you want from the subgraph. Let's create queries for our two main features. In the `lib` directory create a `queries.ts` file.

queries.ts

``` import { gql } from '@apollo/client'; // Query for paginated flip results export const GET_FLIP_RESULTS = gql` query GetFlipResults( $first: Int!, # Number of results to fetch $skip: Int!, # Number of results to skip (for pagination) $orderBy: String!, # Field to sort by $orderDirection: String! # 'asc' or 'desc' ) { flipResults( first: $first skip: $skip orderBy: $orderBy orderDirection: $orderDirection ) { id # Unique identifier player # Wallet address of player betAmount # Amount bet (in wei) choice # Player's choice: HEADS or TAILS result # Actual result: HEADS or TAILS payout # Amount won (0 if lost) blockNumber # Block when flip occurred blockTimestamp # Unix timestamp transactionHash # Transaction hash on blockchain } } `; // Query for recent flips (live feed) export const GET_RECENT_FLIPS = gql` query GetRecentFlips($first: Int!) { flipResults( first: $first orderBy: blockTimestamp orderDirection: desc # Most recent first ) { id player betAmount choice result payout blockTimestamp transactionHash } } `; ```

Note the following: * `gql` is the template literal tag that parses GraphQL queries * Variables start with $ and have types (Int!, String!, etc.) * ! means the field is required (non-nullable) ## Build the All Flips Component Let's build the All Flips component step by step, understanding each part in detail. ### Set Up the Component File In the `components` directory create `AllFlips.tsx` file and add the following imports. ``` 'use client'; import { useState } from 'react'; import { useQuery } from '@apollo/client'; import { GET_FLIP_RESULTS } from '@/lib/queries'; ``` ### Create Utility Functions Add these helper functions at the top of your component: ``` / Shortens long blockchain addresses for display // Example: "0x1234567890abcdef" becomes "0x1234...cdef" const truncateHash = (hash: string) => { return `${hash.slice(0, 6)}...${hash.slice(-4)}`; }; // Converts wei (smallest unit) to ether (display unit) // 1 ether = 1,000,000,000,000,000,000 wei (10^18) const formatEther = (wei: string) => { const ether = parseFloat(wei) / 1e18; return ether.toFixed(4); // Show 4 decimal places }; // Converts Unix timestamp to readable date // Blockchain stores time as seconds since Jan 1, 1970 const formatTime = (timestamp: string) => { const milliseconds = parseInt(timestamp) * 1000; const date = new Date(milliseconds); return date.toLocaleString(); }; ``` ### Component Function and State Management ``` export default function AllFlips() { // Track which page of results we're viewing const [page, setPage] = useState(0); const itemsPerPage = 30; ``` `the number ofpage` tracks the current page number (starting at 0), which is used to calculate the number of results to skip. It updates when the user clicks the Previous/Next button. ### Execute the GraphQL Query ``` const { loading, error, data } = useQuery(GET_FLIP_RESULTS, { variables: { first: itemsPerPage, // How many results to fetch skip: page * itemsPerPage, // How many to skip orderBy: 'blockTimestamp', // Sort by time orderDirection: 'desc', // Newest first }, }); ``` The `useQuery` function is set to `loading: true` while fetching `data` and the `data` contains the query results when successful. ### Handle Query States ``` // Show loading spinner while fetching if (loading) { return

; } // Show error message if query failed if (error) { return (

Error: {error.message}

); } // Check if we have results if (!data?.flipResults?.length) { return

No flips found

; } ``` This prevents rendering errors and andles edge cases gracefully ### Render the Table View

AllFlips.tsx - Table View

``` return (

{/* Makes table scrollable on mobile */} {data.flipResults.map((flip: any) => ( {/* Player address - truncated for readability */} {/* Bet amount - converted from wei to ether */} {/* Player's choice - color coded */} {/* Actual result - same color coding */} {/* Payout - green if won, gray if lost */} {/* Timestamp - converted to readable date */} ))}

Player	Bet	Choice	Result	Payout	Time
{truncateHash(flip.player)}	{formatEther(flip.betAmount)} STT	{flip.choice}	{flip.result}	{flip.payout !== '0' ? `+${formatEther(flip.payout)}` : '0' } STT	{formatTime(flip.blockTimestamp)}

{/* Previous button */} {/* Current page indicator */} Page {page + 1} {/* Next button */}

); } ```

## Build the Live Feed Component Now let's build the Live Feed component that automatically refreshes to show new flips. ### Set Up the Component In the `components` directory create a `LiveFeed.tsx` file and update the imports. ``` 'use client'; import { useQuery } from '@apollo/client'; import { GET_RECENT_FLIPS } from '@/lib/queries'; ``` ### Create Utility Functions ``` const truncateHash = (hash: string) => { return `${hash.slice(0, 6)}...${hash.slice(-4)}`; }; const formatEther = (wei: string) => { return (parseFloat(wei) / 1e18).toFixed(4); }; ``` ### Component Function with Auto-Refresh ``` export default function LiveFeed() { // Execute query with automatic polling const { loading, error, data } = useQuery(GET_RECENT_FLIPS, { variables: { first: 10 // Get 10 most recent flips }, pollInterval: 5000, // Refresh every 5 seconds (5000ms) }); ``` The `pollInterval` automatically re-executes the query every 5 seconds. New flips appear without user interaction with Apollo Client handling the refresh logic. You can set to 0 or remove to disable auto-refresh ### Handle Query States ``` // Same loading/error handling as AllFlips if (loading) { return

; } if (error) { return

Error: {error.message}

; } if (!data?.flipResults?.length) { return

No recent flips

; } ``` ### Complete Live Feed Component

LiveFeed.tsx

``` 'use client'; import { useQuery } from '@apollo/client'; import { GET_RECENT_FLIPS } from '@/lib/queries'; const truncateHash = (hash: string) => `${hash.slice(0, 6)}...${hash.slice(-4)}`; const formatEther = (wei: string) => (parseFloat(wei) / 1e18).toFixed(4); export default function LiveFeed() { const { loading, error, data } = useQuery(GET_RECENT_FLIPS, { variables: { first: 10 }, pollInterval: 5000, }); if (loading) return

; if (error) return

Error: {error.message}

; if (!data?.flipResults?.length) return

No recent flips

; return (

{data.flipResults.map((flip: any) => { const won = flip.payout !== '0'; return (

{truncateHash(flip.player)} bet {formatEther(flip.betAmount)} STT

{flip.choice} → {flip.result}

{won ? `Won ${formatEther(flip.payout)} STT` : 'Lost'}

); })}

Auto-refreshing every 5 seconds

); } ```

The key differences from the AllFlips page are that there is no pagination (shows most recent only), and it auto-refreshes with pollInterval, with a visual emphasis on win/loss status. ## Update the Main Page.tsx

page.tsx

``` 'use client'; import { useState } from 'react'; import AllFlips from '@/components/AllFlips'; import LiveFeed from '@/components/LiveFeed'; export default function Home() { const [activeTab, setActiveTab] = useState('allFlips'); return (

SomFlip

{/* Tab Navigation */}

{/* Conditional Rendering Based on Active Tab */} {activeTab === 'allFlips' ? : }

); } ```

## Run Your Application ``` npm run dev ``` Visit `http://localhost:3000` to see your UI in action.
# Using Data APIs (Ormi) The Somnia mission is to enable the building of mass-consumer real-time applications. As a Developer, you need to understand how to interact with onchain data to build UIs. This guide will teach you how to build a Token Balance dApp that fetches and displays ERC20 token balances from the Somnia Network using Next.js and the Ormi Data APIs. ## Prerequisites To complete this guide, you will need: * Basic understanding of React and TypeScript * An Ormi API key. Get one at[ ](https://ormi.xyz/). {% embed url="" %} ## What is Ormi Data API? [Ormi](https://docs.ormilabs.com/dedicated-env/somnia/data-apis/overview) provides a unified crypto data infrastructure for live and historical blockchain data. The Data APIs allow developers to query blockchain data without running their own nodes, making it easy to build data-rich applications on the Somnia Network. #### API Base URL The Ormi Data API for Somnia Network uses the following base URL: ``` https://api.subgraph.somnia.network/public_api/data_api ``` #### API Endpoints The API follows a RESTful structure. For fetching ERC20 token balances, the endpoint structure is: ``` /somnia/v1/address/{walletAddress}/balance/erc20 ``` Where: * `somnia` - The network identifier * `v1` - API version * `{walletAddress}` - The wallet address you want to query * `balance/erc20` - Specifies that you want ERC-20 token balances #### Authentication The Ormi API requires authentication using a Bearer token. Every request must include an Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` **Important**: Never expose your API key in client-side code. Always make API calls from a server-side route to keep your key secure. #### Example API Request Here's an example of how to make a direct API call using curl: ```bash curl -X GET "https://api.subgraph.somnia.network/public_api/data_api/somnia/v1/address/0xYOUR_WALLET_ADDRESS/balance/erc20" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" ``` ## Set up the Project Create a new Next.js application with TypeScript and Tailwind CSS: ```bash npx create-next-app@latest somnia-balance-demo --typescript --tailwind --app cd somnia-balance-demo ``` ## Create the Type Definitions First, we need to define TypeScript interfaces for the API response. Update `app/page.tsx`: ```typescript 'use client' import { useState, FormEvent } from 'react' // Type definitions for the API response interface TokenBalance { balance: string contract: { address: string decimals: number erc_type: string logoUri: string | null name: string symbol: string } raw_balance: string } interface BalanceResponse { erc20TokenBalances: TokenBalance[] resultCount: number } ``` ## Build the User Interface Now, let's create the main component with an input field and button. Update your `app/page.tsx`: ```typescript export default function Home() { const [walletAddress, setWalletAddress] = useState('') const [loading, setLoading] = useState(false) const [data, setData] = useState(null) const [error, setError] = useState('') return (

Somnia Network Balance Demo

) } ``` ## Create a `.env` file The `.env` is for keeping secrets such as the Ormi API KEY. Add the API KEY: ```bash PRIVATE_KEY=YOUR_API_KEY_HERE ``` ## Create the API Route To avoid CORS issues and keep your API key secure, we'll create an API route. Create a directory and a new file `app/api/balance/route.ts`: ```typescript import { NextRequest, NextResponse } from 'next/server' export async function GET(request: NextRequest) { try { const searchParams = request.nextUrl.searchParams; const walletAddress = searchParams.get('address'); if (!walletAddress) { return NextResponse.json( { error: 'Wallet address is required' }, { status: 400 } ) } const apiKey = process.env.PRIVATE_KEY const baseUrl = 'https://api.subgraph.somnia.network/public_api/data_api' const response = await fetch( `${baseUrl}/somnia/v1/address/${walletAddress}/balance/erc20`, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json', 'Accept': 'application/json', }, } ) const data = await response.json() if (!response.ok) { return NextResponse.json( { error: 'Failed to fetch data from Ormi API', details: data }, { status: response.status } ) } return NextResponse.json(data) } catch (error) { console.error('API Error:', error) return NextResponse.json( { error: 'Internal server error' }, { status: 500 } ) } } ``` Important: Replace `YOUR_API_KEY_HERE` with your actual Ormi API key. ## Implement the Fetch Function Add the fetch function to handle form submission. Update your `app/page.tsx`: ```typescript const fetchBalance = async (e: FormEvent) => { e.preventDefault() if (!walletAddress) { setError('Please enter a wallet address') return } setLoading(true) setError('') setData(null) try { const response = await fetch(`/api/balance?address=${walletAddress}`, { headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ walletAddress }), }) const result = await response.json() if (!response.ok) { throw new Error(result.error || 'Failed to fetch balance') } setData(result) } catch (err) { setError(err instanceof Error ? err.message : 'An error occurred') } finally { setLoading(false) } } ``` Don't forget to add the onSubmit handler to your form: ```typescript

``` ## Display the Results Add error handling and a table to display the token balances. Add this code after your form in `app/page.tsx`: ```typescript {error && (

{error}

)} {data && data.erc20TokenBalances.length > 0 && (

Token Balances ({data.resultCount} tokens)

{data.erc20TokenBalances.map((token, index) => ( ))}

Name	Symbol	Balance	Contract Address
{token.contract.name \|\| 'Unknown'}	{token.contract.symbol \|\| '-'}	{parseFloat(token.balance).toLocaleString()}	{token.contract.address.slice(0, 6)}...{token.contract.address.slice(-4)}

)} {data && data.erc20TokenBalances.length === 0 && (

No ERC-20 tokens found for this address

)} ``` ### Test Your dApp Start the development server: ```bash npm run dev ``` Open[ http://localhost:3000](http://localhost:3000/) in your browser. Enter a wallet address that has tokens on Somnia Network. Example test address: `0xC4890Bc98273424a18626772F266C35bf57FA56A` Look at the browser for the response and the displayed token balances. You can click on any contract address to view it in the Shannon Explorer. ## Complete Code

page.tsx

```typescript 'use client'; import { useState, FormEvent } from 'react'; // Type definitions for the API response interface TokenBalance { balance: string; contract: { address: string; decimals: number; erc_type: string; logoUri: string | null; name: string; symbol: string; }; raw_balance: string; } interface BalanceResponse { erc20TokenBalances: TokenBalance[]; resultCount: number; } export default function Home() { const [walletAddress, setWalletAddress] = useState(''); const [loading, setLoading] = useState(false); const [data, setData] = useState(null); const [error, setError] = useState(''); const fetchBalance = async (e: FormEvent) => { e.preventDefault(); if (!walletAddress) { setError('Please enter a wallet address'); return; } setLoading(true); setError(''); setData(null); try { const response = await fetch(`/api/balance?address=${walletAddress}`, { headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ walletAddress }), }); const result = await response.json(); if (!response.ok) { throw new Error(result.error || 'Failed to fetch balance'); } setData(result); } catch (err) { setError(err instanceof Error ? err.message : 'An error occurred'); } finally { setLoading(false); } }; return (

Somnia Network Balance Demo

setWalletAddress(e.target.value)} placeholder='Enter wallet address (0x...)' className='flex-1 px-4 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 text-gray-500' />

{error && (

{error}

)} {data && data.erc20TokenBalances.length > 0 && (

Token Balances ({data.resultCount} tokens)

{data.erc20TokenBalances.map((token, index) => ( ))}

Name	Symbol	Balance	Contract Address
{token.contract.name \|\| 'Unknown'}	{token.contract.symbol \|\| '-'}	{parseFloat(token.balance).toLocaleString()}	{token.contract.address.slice(0, 6)}... {token.contract.address.slice(-4)}

)} {data && data.erc20TokenBalances.length === 0 && (

No ERC-20 tokens found for this address

)}

); } ```

route.ts

```typescript import { NextRequest, NextResponse } from 'next/server'; export async function GET(request: NextRequest) { try { const searchParams = request.nextUrl.searchParams; const walletAddress = searchParams.get('address'); if (!walletAddress) { return NextResponse.json( { error: 'Wallet address is required' }, { status: 400 } ); } const apiKey = process.env.PRIVATE_KEY; const baseUrl = 'https://api.subgraph.somnia.network/public_api/data_api'; const response = await fetch( `${baseUrl}/somnia/v1/address/${walletAddress}/balance/erc20`, { headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', Accept: 'application/json', }, } ); const data = await response.json(); if (!response.ok) { return NextResponse.json( { error: 'Failed to fetch data from Ormi API', details: data }, { status: response.status } ); } return NextResponse.json(data); } catch (error) { console.error('API Error:', error); return NextResponse.json( { error: 'Internal server error' }, { status: 500 } ); } } ```

## Congratulations You have built your first API enabled dApp on the Somnia Network! Now that you have a working Token Balance dApp, you can extend it by using other Ormi API [endpoints](https://subgraphs.somnia.network/). # Listening to Blockchain Events (WebSocket) This guide teaches developers how to create WebSocket connections to listen for smart contract events on the Somnia network in real-time. We'll use a simple Greeting contract as an example to demonstrate the core concepts. ## Resources | Somnia Mainnet WebSocket | | | ------------------------ | ------------------------------------------- | | Somnia Testnet WebSocket | | For the underlying subscription and log-filtering RPC methods, see the [JSON-RPC API Reference](/developer/json-rpc-api). ## Example Script

websocket-listener.js

```javascript // const { ethers } = require("ethers"); import { ethers } from "ethers"; // Configuration const wsUrl = "wss://dream-rpc.somnia.network/ws"; const contractAddress = "0xADA7b2953E7d670092644d37b6a39BAE3237beD7"; // Replace with your contract address // Contract ABI const abi = [ { anonymous: false, inputs: [ { indexed: true, internalType: "string", name: "oldGreeting", type: "string" }, { indexed: true, internalType: "string", name: "newGreeting", type: "string" }, ], name: "GreetingSet", type: "event", }, { inputs: [], name: "getGreeting", outputs: [{ internalType: "string", name: "", type: "string" }], stateMutability: "view", type: "function", }, ]; async function listen() { // Create WebSocket provider and contract const provider = new ethers.WebSocketProvider(wsUrl); await provider._waitUntilReady(); const contract = new ethers.Contract(contractAddress, abi, provider); console.log("Listening for events...\n"); // Event filter const filter = { address: contractAddress, topics: [ethers.id("GreetingSet(string,string)")], }; // Listen for events provider.on(filter, async (log) => { try { const greeting = await contract.getGreeting(); console.log(`New greeting: "${greeting}"`); } catch (error) { console.error("Error:", error.message); } }); // Keep connection alive setInterval(async () => { try { await provider.getBlockNumber(); } catch (error) { console.error("Connection error"); } }, 30000); // Handle shutdown process.on("SIGINT", () => { provider.destroy(); process.exit(0); }); } // Start listening listen().catch(console.error); ```

## Prerequisites * Node.js 20+ * Basic understanding of JavaScript * A deployed smart contract on Somnia network ## What are WebSockets? WebSockets are a communication protocol that provides bidirectional communication channels over a single TCP connection. Unlike traditional HTTP requests, WebSockets maintain a persistent connection between the client and server. ### **How WebSockets Work** WebSockets begin with a connection establishment phase where the client initiates a WebSocket handshake through an HTTP upgrade request. Once established, the connection stays open as a persistent channel between client and server. This enables bidirectional communication where both client and server can send messages at any time without waiting for requests. The protocol maintains low latency since there's no need to establish new connections for each message exchange. This design is highly efficient with minimal protocol overhead compared to traditional HTTP polling approaches. **WebSocket Connection Lifecycle** ```bash Client Server | | |----Connection Request-->| |<---Connection Accept----| | | |<===Open Connection====> | | | |----Send Message-------->| |<---Receive Message------| |<---Push Notification----| |----Send Message-------->| | | |<===Open Connection====> | | | |----Close Connection---->| ``` ### WebSocket vs HTTP Polling #### **HTTP Polling Approach** ```javascript // Inefficient: Constantly asking "Any updates?" setInterval(async () => { const response = await fetch('https://api.example.com/events'); const data = await response.json(); if (data.hasNewEvents) { console.log('New event:', data.events); } }, 5000); // Check every 5 seconds ``` The problem with polling is that Polling wastes bandwidth by constantly checking for updates even when none exist, leading to unnecessary network traffic. This approach introduces delays of up to the polling interval (5 seconds in our example), meaning users might wait several seconds to see new events that have already occurred. Additionally, the server must process these unnecessary requests repeatedly, increasing computational load and infrastructure costs. For blockchain applications, this translates to higher costs for RPC providers who often charge based on the number of requests made. #### **WebSocket Approach** ```javascript // Efficient: Server pushes updates immediately const ws = new WebSocket('wss://api.example.com/events'); ws.on('message', (data) => { console.log('New event:', data); // Instant notification }); ``` WebSockets provide real-time updates measured in milliseconds rather than seconds, ensuring users receive notifications instantly when events occur. This eliminates wasted requests since the server only sends data when there are actual updates, significantly reducing bandwidth usage. The reduced request frequency leads to lower server load and better resource utilization. For users, this translates to a superior experience with immediate feedback, while developers benefit from reduced infrastructure costs. ### Blockchain Events and WebSockets Smart contracts emit events when important state changes occur. These events are included in transaction receipts and stored in blockchain logs. The event flow begins when a user calls a Smart Contract function through a Transaction. During execution, the contract updates its Internal State and emits Events containing relevant data about the changes. These Transactions and their associated Events are then included in a new block by Validators. Once the Block is finalized, Nodes across the network broadcast it to their peers. WebSocket connections instantly notify connected clients about these new events, enabling real-time reactions to Blockchain state changes. ### **Example Use Cases for WebSocket Event Listening** | DeFi Applications |

Monitor price updates on DEX swaps

| | ------------------- | ---------------------------------------------------- | | NFT Marketplaces |

Live bidding updates in auctions

| | Gaming DApps |

Real-time game state updates

| | DAOs and Governance |

Live voting updates

| | Supply Chain |

Product status updates

| ### Indexed Parameters in Events When you mark an event parameter as `indexed` in Solidity, it becomes part of the event's topics rather than the data section. This enables efficient filtering but changes how you access the data. Non-Indexed String (accessible directly): ```solidity event MessageSent(string message); // Can read 'message' directly from logs ``` Indexed String (hashed for filtering): ```solidity event MessageSent(string indexed message); // 'message' is hashed, cannot read directly ``` **Why Use Indexed Parameters?** `Indexed` parameters enable efficient filtering by allowing nodes to quickly find specific events without scanning through all logs in a block. They provide gas optimization since topics are more gas-efficient for filtering operations compared to parsing event data. Additionally, nodes can index and search these parameters significantly faster, improving overall query performance when applications need to find specific events based on parameter values. **The Trade-off** For strings and bytes, indexing means: * Can filter events by this parameter efficiently * Cannot retrieve the actual value from the event log * Must query contract state to get the current value This is why, in our example, when we receive a `GreetingSet` event with indexed string parameters, we call contract.getGreeting() to retrieve the actual greeting text. > The pattern for listening to blockchain events via WebSocket follows these principles: > > The process begins by establishing a connection to the blockchain node's WebSocket endpoint, ensuring a persistent communication channel. Once connected, you create a filter that defines which events from which contracts to monitor, allowing precise event targeting. Next, you set up listener functions that register callbacks to execute when specific events occur. When events are received, your handler functions process the event data according to your application's needs. Throughout the connection lifetime, you must maintain the connection with periodic activity to prevent timeouts. Finally, when your application terminates, ensure a clean shutdown by properly closing all connections and removing event listeners. ## Code Breakdown ### Connect to Somnia WebSocket ```javascript const wsUrl = 'wss://api.infra.testnet.somnia.network/ws'; //change url for Mainnet const provider = new ethers.WebSocketProvider(wsUrl); await provider._waitUntilReady(); ``` The WebSocket URL for Somnia mainnet is . This creates a persistent connection to the network. #### Create Contract Instance ```javascript const contract = new ethers.Contract(contractAddress, abi, provider); ``` You need: * `Contract address`: The deployed address on Somnia. * `ABI`: At minimum, include the events you want to listen for. * `Provider`: The WebSocket connection. ### Define Event Filter ```javascript const filter = { address: contractAddress, topics: [ethers.id("GreetingSet(string,string)")] }; ``` The filter specifies: * Which contract to monitor * Which event signature to listen for ### Set Up Event Listener ```javascript provider.on(filter, async (log) => { // Handle the event const greeting = await contract.getGreeting(); console.log(`New greeting: "${greeting}"`); }); ``` When an event is detected: 1. The callback receives the log data 2. Query the contract for the current state 3. Process/display the data as needed ### Maintain Connection ```javascript setInterval(async () => { await provider.getBlockNumber(); }, 30000); ``` This is because WebSocket connections can timeout. Send periodic requests to keep the connection alive. ### Update the ABI Include only the events and functions you need: ```javascript const abi = [ // Your event definition { "anonymous": false, "inputs": [ // Your event parameters ], "name": "YourEventName", "type": "event" }, // Any read functions you need { "inputs": [], "name": "yourReadFunction", "outputs": [/* outputs */], "stateMutability": "view", "type": "function" } ]; ``` ### Update the Event Filter Change the event signature to match your event: ```javascript const filter = { address: contractAddress, topics: [ethers.id("YourEventName(type1,type2)")] }; ``` ### Handle Event Data Process the event based on your needs: ```javascript provider.on(filter, async (log) => { // For non-indexed parameters, you can parse the log const parsedLog = contract.interface.parseLog(log); // For indexed strings, query the contract state const currentState = await contract.yourReadFunction(); // Process your data console.log('Event detected:', currentState); }); ``` ## Common Patterns ### Multiple Events Listen for multiple events from the same contract: ```javascript // Listen for Event1 provider.on({ address: contractAddress, topics: [ethers.id("Event1(...)")] }, handleEvent1); // Listen for Event2 provider.on({ address: contractAddress, topics: [ethers.id("Event2(...)")] }, handleEvent2); ``` ### Error Recovery Add reconnection logic for production applications: ```javascript async function connectWithRetry() { let retries = 0; while (retries < 5) { try { await listen(); break; } catch (error) { console.log(`Retry ${++retries}/5...`); await new Promise(r => setTimeout(r, 5000)); } } } ``` ### Event History Get recent events on startup: ```javascript // Get last 100 blocks of events const currentBlock = await provider.getBlockNumber(); const events = await contract.queryFilter('YourEventName', currentBlock - 100, currentBlock); events.forEach(event => { console.log('Historical event:', event); }); ``` ## Test Your WebSocket Connection 1. Deploy your Smart Contract to Somnia network. 2. Run the listener in one terminal: ```bash node websocket-listener.js ``` 3. Trigger events from another script or dApp 4. Observe real-time updates in your listener ### Conclusion WebSocket connections provide real-time event monitoring for smart contracts on Somnia. This guide demonstrated: 1. Connecting to Somnia's WebSocket endpoint 2. Listening for specific contract events 3. Handling indexed parameters correctly 4. Maintaining stable connections 5. Adapting the pattern for any smart contract With this foundation, you can build responsive dApps that react instantly to blockchain events without polling.
# Oracles Oracles bridge the gap between onchain and offchain worlds. They bring external data like prices, randomness, and real-world events directly into your smart contracts. In this section, you’ll explore: * [How to integrate **DIA price feeds** on Somnia](/developer/building-dapps/oracles/dia-price-feeds) * [How to implement **Protofire Price Feeds**](/developer/building-dapps/oracles/protofire-price-feeds) * [How to implement **Verifiable Randomness (VRF)** via **Protofire + Chainlink**](/developer/building-dapps/oracles/using-verifiable-randomness-vrf) * Use cases for oracles in DeFi, gaming, prediction markets, and more > If your dApp depends on real-world data, randomness, or secure external inputs — this is where to start. # DIA Price Feeds ## **Overview** [DIA](https://docs.diadata.org/) Oracles provide **secure, customizable, and decentralized price feeds** that can be integrated into **smart contracts on the Somnia Testnet**. This guide will walk you through how to access **on-chain price data**, understand the oracle’s functionality, and integrate it into your **Solidity Smart Contracts**. {% embed url="" %} ## **Oracle Details** ### **Contracts on Somnia**

Network	Contract Address
Mainnet	0xbA0E0750A56e995506CA458b2BdD752754CF39C4
Testnet	0x9206296Ea3aEE3E6bdC07F7AaeF14DfCf33d865D

### Gas Wallets The gas wallet is used for pushing data to your contracts. To ensure uninterrupted Oracle operation, please maintain sufficient funds in the gas wallet. You can monitor the wallets below to ensure they remain adequately funded at all times.

Network	Contract Address
Mainnet	0x3073d2E61ecb6E4BF4273Af83d53eDAE099ea04a
Testnet	0x24384e1c60547b0d5403b21ed9b6fb9457fb573f

### **Oracle Configuration** * **Pricing Methodology:** MAIR * **Deviation Threshold:** 0.5% (Triggers price update if exceeded) * **Refresh Frequency:** Every 120 seconds * **Heartbeat:** Forced price update every 24 hours ## **Supported Asset Feeds** ### **Mainnet**


Asset Ticker	Adapter Address	Asset Markets Overview
USDT	0x936C4F07fD4d01485849ee0EE2Cdcea2373ba267	USDT markets
USDC	0x5D4266f4DD721c1cD8367FEb23E4940d17C83C93	USDC markets
BTC	0xb12e1d47b0022fA577c455E7df2Ca9943D0152bE	BTC markets
ARB	0x6a96a0232402c2BC027a12C73f763b604c9F77a6	ARB markets
SOL	0xa4a3a8B729939E2a79dCd9079cee7d84b0d96234	SOL markets
WETH	0x4E5A9Ebc4D48d7dB65bCde4Ab9CBBE89Da2Add52	WETH markets
SOMI	0x1f5f46B0DABEf8806a1f33772522ED683Ba64E27	SOMI markets

### **Testnet**

Asset Ticker	Adapter Address	Asset Markets Overview
USDT	0x67d2C2a87A17b7267a6DBb1A59575C0E9A1D1c3e	USDT markets
USDC	0x235266D5ca6f19F134421C49834C108b32C2124e	USDC markets
BTC	0x4803db1ca3A1DA49c3DB991e1c390321c20e1f21	BTC markets
ARB	0x74952812B6a9e4f826b2969C6D189c4425CBc19B	ARB markets
SOL	0xD5Ea6C434582F827303423dA21729bEa4F87D519	SOL markets
WETH	0x786c7893F8c26b80d42088749562eDb50Ba9601E	WETH markets
SOMI	0xaEAa92c38939775d3be39fFA832A92611f7D6aDe	SOMI markets

## **How the Oracle Works** DIA oracles continuously fetch and push asset prices **on-chain** using an **oracleUpdater**, which operates within the `DIAOracleV2` contract. The oracle uses **predefined update intervals** and **deviation thresholds** to determine when price updates are necessary.

Each asset price feed has an adapter contract, allowing access through the AggregatorV3Interface. You can use the methods `getRoundData` and `latestRoundData` to fetch pricing information. Learn more [here](https://nexus.diadata.org/how-to-guides/migrate-to-dia). ## **Using the Solidity Library** DIA has a dedicated Solidity library to facilitate the integration of DIA oracles in your own contracts. The library consists of two functions, `getPrice` and `getPriceIfNotOlderThan`. ### Access the library ``` import { DIAOracleLib } from "./libraries/DIAOracleLib.sol"; ``` ### `getPrice` ``` function getPrice( address oracle, string memory key ) public view returns (uint128 latestPrice, uint128 timestampOflatestPrice); ``` **Returns the price of a specified asset along with the update timestamp**. ### **`getPriceIfNotOlderThan`** ``` function getPriceIfNotOlderThan( address oracle, string memory key, uint128 maxTimePassed ) public view returns (uint128 price, bool inTime) { ``` **Checks if the Oracle price is older than `maxTimePassed`** ## Using DIAOracleV2 Interface The following contract provides an integration example of retrieving prices and verifying price age. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.13; interface IDIAOracleV2 { function getValue(string memory) external view returns (uint128, uint128); } contract DIAOracleSample { address diaOracle; constructor(address _oracle) { diaOracle = _oracle; } function getPrice(string memory key) external view returns ( uint128 latestPrice, uint128 timestampOflatestPrice ) { (latestPrice, timestampOflatestPrice) = IDIAOracleV2(diaOracle).getValue(key); } } ``` [**Full Example on DIA Docs**](https://www.diadata.org/docs/nexus/how-to-guides/fetch-price-data/solidity) ## Adapter contracts To consume price data from DIA Oracle, you can use the adapter Smart Contract located at the [adapter address](https://docs.google.com/document/d/1tqK1Va0dOrgZcOjqwLg2fh7hDOK6pQWDfF3ZrljDN-w/edit?tab=t.0#heading=h.iyqc22917lsc) for each asset. This will allow you to access the same methods on the `AggregatorV3Interface` such as `getRoundData` & `latestRoundData`. You can learn more [here](https://www.diadata.org/docs/nexus/how-to-guides/migrate-to-dia). ## **Glossary** | Term | Definition | | --------------------- | --------------------------------------------------------------------- | | **Deviation** | Percentage threshold that triggers a price update when exceeded. | | **Refresh Frequency** | Time interval for checking and updating prices if conditions are met. | | **Trade Window** | Time interval used to aggregate trades for price calculation. | | **Heartbeat** | Forced price update at a fixed interval. | ## **Support** If you need further assistance integrating DIA Oracles, reach out through DIA’s[ official documentation](https://docs.diadata.org/) and ask your questions in the #dev-support channel on [Discord](https://discord.com/invite/somnia). Developers can build secure, real-time, and on-chain financial applications with reliable pricing data by integrating DIA Oracles on Somnia. # Protofire Price Feeds ## Somnia Mainnet Price Feeds | **Asset Pair** | **OCR Aggregator** | **Proxy (read‑only)** | | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | USDC / USD | [0x4b74EcA574Ce996448b485100e4FFf84866911dF](https://explorer.somnia.network/address/0x4b74EcA574Ce996448b485100e4FFf84866911dF) | [0x843B6812E9Aa67b3773675d2836646BCbd216642](https://explorer.somnia.network/address/0x843B6812E9Aa67b3773675d2836646BCbd216642) | | ETH / USD | [0xa3060dd6Bb56EdfB2E0d78c88ef63A974a392D36](https://explorer.somnia.network/address/0xa3060dd6Bb56EdfB2E0d78c88ef63A974a392D36) | [0xeC25a820A6F194118ef8274216a7F225Da019526](https://explorer.somnia.network/address/0xeC25a820A6F194118ef8274216a7F225Da019526) | | BTC / USD | [0x3cBdF7F02956c8e946192Bff64bb2Dd470dd589C](https://explorer.somnia.network/address/0x3cBdF7F02956c8e946192Bff64bb2Dd470dd589C) | [0xa57d637618252669fD859B1F4C7bE6F52Bef67ed](https://explorer.somnia.network/address/0xa57d637618252669fD859B1F4C7bE6F52Bef67ed) | ## Somnia Testnet Price Feeds


Token Pair	Contract Address
USDC/USD	0xa2515C9480e62B510065917136B08F3f7ad743B4
ETH/USD	0xd9132c1d762D432672493F640a63B758891B449e
BTC/USD	0x8CeE6c58b8CbD8afdEaF14e6fCA0876765e161fE

Use any of these when deploying the PriceConsumer Smart Contract for your dApp. {% embed url="" %} ## What Are Oracles and Why Do They Matter This service is powered by Protofire, an infrastructure provider that integrates decentralized oracle networks for Somnia. Learn more at[ protofire.io](https://protofire.io/services/solution/oracle-integration). Oracles are critical infrastructure in the blockchain ecosystem that enable Smart Contracts to interact with real-world data. Blockchains are deterministic by design and cannot fetch off-chain information directly. This creates a need for oracles, which are trusted data feeds that can push external data, like market prices, sports scores, or weather conditions, into Smart Contracts. Chainlink is the most widely adopted decentralized oracle network. It allows developers to access reliable data feeds that are resistant to manipulation and downtime. In this tutorial, we focus on Protofire Chainlink Price Feeds, which provide real-time market prices for assets like ETH, BTC, and USDC on Somnia Smart Contracts that rely on accurate pricing (e.g., lending, trading, insurance) benefit immensely from using decentralized oracles like Protofire. Oracles unlock use cases that were previously impossible due to blockchain isolation. In this guide, we will build a live crypto price tracker that displays BTC/USD, ETH/USD, and USDC/USD using Protofire Chainlink Price Feeds deployed on the Somnia Testnet. ## Prerequisites 1. This guide is not an introduction to JavaScript Programming; you are expected to understand JavaScript. 2. Basic knowledge of React & Next.js. ### Solidity Contract (Chainlink Oracle Consumer) ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol"; contract PriceConsumer { AggregatorV3Interface internal priceFeed; constructor(address _priceFeed) { priceFeed = AggregatorV3Interface(_priceFeed); } /** * Returns the latest price */ function getLatestPrice() public view returns (int256) { ( /* uint80 roundID */, int256 price, /* uint startedAt */, /* uint timeStamp */, /* uint80 answeredInRound */ ) = priceFeed.latestRoundData(); return price; } /** * Returns price decimals */ function getDecimals() public view returns (uint8) { return priceFeed.decimals(); } } ``` ### Code Breakdown ```solidity import `@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol ``` Pulls in the AggregatorV3Interface from the Chainlink library. This interface allows interaction with Chainlink oracle contracts for Price Feeds. ```solidity constructor(address _priceFeed) { } ``` The contract's constructor runs once when the contract is deployed. It takes the address of the Protofire Chainlink Price Feed contract and stores it. ```solidity priceFeed = AggregatorV3Interface(_priceFeed); ``` Instantiates the interface with the provided address, enabling function calls to the external oracle. ```solidity function getLatestPrice() public view returns (int256) { ( /* uint80 roundID */, int256 price, /* uint startedAt */, /* uint timeStamp */, /* uint80 answeredInRound */ ) = priceFeed.latestRoundData(); return price; } ``` `getLatestPrice()` is a public function which is callable from outside the contract. It does not modify blockchain state and returns the latest price from the Chainlink feed. It calls the Chainlink function **`latestRoundData()`** which returns a 5-value tuple: ```solidity (uint80 roundId, int256 price, uint startedAt, uint timeStamp, uint80 answeredInRound) ``` This function extracts only the price and ignores the rest using commas. It returns the latest price as an int256. ```solidity function getDecimals() public view returns (uint8) { return priceFeed.decimals(); } ``` `getDecimals()` is a helper function to return the number of decimals used by the price feed. Ensures consumers of the contract know how to scale the price properly. ## How Price Oracle latestRoundData() works It's helpful to understand how the Price Feed data is structured. The function `latestRoundData()` from the Chainlink Aggregator interface returns the following tuple: ```solidity (uint80 roundId, int256 answer, uint startedAt, uint timeStamp, uint80 answeredInRound) ``` * `roundId`: The current round number for the feed * `price`: The actual price value (e.g. ETH/USD = 1900.42 × 10^8) * `startedAt`: Timestamp when this round started * `timeStamp`: When the answer was last updated * `answeredInRound`: The round in which the answer was submitted
Most price consumer contracts use only `price`, but for more robust designs, `timeStamp` can be checked to ensure the price is recent. Additionally, Protofire Chainlink Price Feeds often return prices with 8 decimals. This means the raw price value needs to be normalized by dividing it by 10 \*\* decimals. This is essential because Solidity doesn't support floating-point math. Prices are represented using fixed-point math. For example, if ETH/USD is $1,940.82 and the feed uses 8 decimals, the returned price would be 194082000000. You must divide by 10 \*\* 8 to display $1940.82 in your UI. Always use the `getDecimals()` method provided by the Aggregator interface to dynamically adjust for different feeds that may use 6, 8, or 18 decimals depending on the asset. ## Deploy with Hardhat Update ignition/modules/deploy.js: ```typescript import { buildModule } from "@nomicfoundation/hardhat-ignition/modules"; const PriceConsumerModule = buildModule("PriceConsumerModule", (m) => { // Replace this with the correct feed address for your chosen pair const feedAddress = m.getParameter( "feedAddress", "0xd9132c1d762D432672493F640a63B758891B449e" // Example: ETH/USD on Somnia ); const priceConsumer = m.contract("PriceConsumer", [feedAddress]); return { priceConsumer }; }); export default PriceConsumerModule; ``` Deploy using: ```bash npx hardhat ignition deploy ./ignition/modules/Lock.js --network somnia ``` ## Building the UI Now that we’ve deployed the contract and confirmed it fetches live price data from Somnia’s Protofire Oracles, let’s bring it to life with a clean and responsive UI. We’ll use React and Viem.js to build a real-time dashboard that displays crypto prices with auto-refresh and token selection. Start by creating a new Next.js app. ```bash npx create-next-app@latest somnia-protofire-example cd somnia-protofire-example ``` Then, install required dependencies. ```bash npm install viem ``` Add imports to the `index.js` file ```typescript import { useEffect, useState } from 'react'; import { createPublicClient, http, parseAbi, formatUnits } from 'viem'; import { somniaTestnet } from 'viem/chains'; ``` * useEffect, useState: React hooks for lifecycle and state management. * createPublicClient: Creates a read-only client to interact with the blockchain. * http: Defines the transport layer for the client (uses Somnia RPC). * parseAbi: Parses the contract's ABI. * formatUnits: Converts big numbers (like token prices) to a human readable format.s. #### Create a Viem Client for Somnia ```typescript const client = createPublicClient({ chain: somniaTestnet, transport: http(), }); ``` Creates a blockchain client configured for Somnia Testnet using its RPC URL and allows reading smart contract data without needing a wallet or signer. #### Declare a variable for the deployed Smart Contracts for your Price Feed Addresses ```typescript const FEEDS = { //Testnet Price Feeds ETH: '0x604CF5063eC760A78d1C089AA55dFf29B90937f9', BTC: '0x3dF17dbaa3BA861D03772b501ADB343B4326C676', USDC: '0xA4a08Eb26f85A53d40E3f908B406b2a69B1A2441', }; ``` This will map token pairs to their corresponding Chainlink oracle contract addresses deployed on Somnia.
Parse the ABI ```typescript const abi = parseAbi([ 'function getLatestPrice() view returns (int256)', 'function getDecimals() view returns (uint8)', ]); ``` #### Set up the State ```typescript export default function PriceWidget() { const [price, setPrice] = useState(''); const [selectedToken, setSelectedToken] = useState<'ETH' | 'BTC' | 'USDC'>('ETH'); ``` The `price` state will store the formatted token price and `selectedToken` will track which token is selected from the dropdown (default: ETH). #### Fetch the Latest Price ```typescript const fetchPrice = async () => { const contractAddress = FEEDS[selectedToken]; const [rawPrice, decimals] = await Promise.all([ client.readContract({ address: contractAddress, abi, functionName: 'getLatestPrice' }), client.readContract({ address: contractAddress, abi, functionName: 'getDecimals' }), ]); const normalized = formatUnits(rawPrice, decimals); setPrice(parseFloat(normalized).toFixed(2)); }; ``` Reads the price and its decimal precision from the Chainlink oracle contract. The function declaration uses `Promise.all()` to optimize performance by fetching both at once and formats the price to 2 decimal places for display. #### Fetch Price on Load & Every 10 Seconds ```typescript useEffect(() => { fetchPrice(); const interval = setInterval(fetchPrice, 10000); return () => clearInterval(interval); }, [selectedToken]); ``` The `useEffect` hook runs `fetchPrice()`, once on component mount and every time `selectedToken` changes. The hook also refreshes price data every 10 seconds Live Price Display in the `return` statement. ```typescript return ( ...

${price}

... ) ``` ## Complete Code

index.js

```typescript import { useEffect, useState } from 'react'; import { createPublicClient, http, parseAbi, formatUnits } from 'viem'; import { somniaTestnet } from 'viem/chains'; const client = createPublicClient({ chain: somniaTestnet, transport: http(), }); const FEEDS = { ETH: '0x604CF5063eC760A78d1C089AA55dFf29B90937f9', BTC: '0x3dF17dbaa3BA861D03772b501ADB343B4326C676', USDC: '0xA4a08Eb26f85A53d40E3f908B406b2a69B1A2441', }; const abi = parseAbi([ 'function getLatestPrice() view returns (int256)', 'function getDecimals() view returns (uint8)', ]); export default function PriceWidget() { const [price, setPrice] = useState(''); const [selectedToken, setSelectedToken] = useState<'ETH' | 'BTC' | 'USDC'>( 'ETH' ); const fetchPrice = async () => { const contractAddress = FEEDS[selectedToken]; const [rawPrice, decimals] = await Promise.all([ client.readContract({ address: contractAddress, abi, functionName: 'getLatestPrice', }), client.readContract({ address: contractAddress, abi, functionName: 'getDecimals', }), ]); const normalized = formatUnits(rawPrice, decimals); setPrice(parseFloat(normalized).toFixed(2)); }; useEffect(() => { fetchPrice(); const interval = setInterval(fetchPrice, 10000); return () => clearInterval(interval); }, [selectedToken]); return (

{selectedToken}/USD on Somnia

${price}

); } ```

## Conclusion The Protofire Oracle integration on Somnia provides developers with reliable, on-chain price feeds for key assets like ETH, BTC, and USDC. Using verified oracles and standardized data formats enables accurate, real-time pricing essential for building GaemFi, DeFi, trading, and financial applications.
# Using Verifiable Randomness (VRF) Protofire Chainlink’s Verifiable Random Function (VRF) allows developers to securely request random numbers in a tamper-proof and auditable way. It is ideal for gaming, NFT mints, and lotteries. This tutorial walks you through integrating Protofire's Chainlink VRF v2.5 on Somnia Network, using native STT (Somnia Token) as the payment currency. ## Mainnet VRF Smart Contracts

Contract	Address
VRFV2PlusWrapper	0x606b2B36516AB7479D1445Ec14B6B39B44901bf8
LINK Token	0x0a4Db7035284566F6f676991ED418140dC01A2aa
LINK/NATIVE oracle	0xEBD41881413dD76F42DF2902ee865099af9099B4

## Testnet VRF Smart Contracts

Contract	Address
VRFV2PlusWrapper	0x763cC914d5CA79B04dC4787aC14CcAd780a16BD2
LINK Token	0x30C75a2badF9b12733e831fcb5315C8f54e96f6d
LINK/NATIVE oracle	0xEc00df0e834AB878135b6554bb7438A2Ff66563b

{% embed url="" %} ## Understanding VRF and Why It Matters Randomness is essential for many blockchain applications, such as Games, Lotteries, Raffles, and NFT drops, but blockchains are deterministic by nature. This means every node must produce the same output given the same inputs. If you try to use on-chain data like `block.timestamp` or `blockhash` as a random source, miners/validators can manipulate these values to influence the outcome. This is where VRF comes in. ### What is VRF? A Verifiable Random Function (VRF) is a cryptographic method of generating random numbers along with a proof that the result was not tampered with. When using Protofire Chainlink VRF: 1. You request a random number from the VRF service. 2. Protofire Chainlink’s decentralized oracle network generates a random value off-chain along with a cryptographic proof. 3. The proof is verified on-chain before the value is returned to your contract. This ensures tamper-proof randomness and publicly verifiable results. Where the outcomes are fair. ### Why is VRF important on blockchain? Without VRF, randomness in blockchain apps can be gamed. With VRF: * No single party can manipulate the results * Users can independently verify the randomness * Applications gain trust from players, participants, and investors Requesting VRF Data using Protofire Chainlink services relies on two methods: Subscription and Direct Funding In the Subscription method, Chainlink VRF requests receive funding from subscription accounts. The [Subscription Manager](https://vrf.chain.link/) lets you create an account and pre-pay for your use of Chainlink VRF requests. You can learn more about the subscription method by referencing the Chainlink [documentation](https://docs.chain.link/vrf/v2-5/overview/subscription).\ \ The Direct Funding method doesn't require a subscription and is optimal for one-off requests for randomness. This method also works best for applications where your end-users must pay the fees for VRF because the cost of the request is determined at request time. [Learn more](https://docs.chain.link/vrf/v2-5/overview/direct-funding).
In this guide, we will build a Smart Contract called `RandomNumberConsumer` that: * Inherits the Protofire Chainlink VRF Wrapper. * Requests 3 secure random numbers * Pays for randomness using native STT (no LINK subscription required) * Emits events and exposes functions to retrieve the randomness * Handles overpayments and pending request checks ## Prerequisites Before getting started: * You are familiar with Solidity (v0.8+) * You have the VRF Wrapper address for [Protofire ChainLink VRF Wrapper](https://shannon-explorer.somnia.network/address/0x763cC914d5CA79B04dC4787aC14CcAd780a16BD2) ## TL;DR 1. Owner calls `requestRandomNumber()` and sends enough STT `(msg.value)` to cover the fee. 2. Contract uses **VRF Wrapper** to request 3 random words (in native STT). 3. When VRF is ready, the wrapper calls `fulfillRandomWords`, the contract: 1. verifies the request, 2. stores the 3 words, 3. toggles `fulfilled = true`, 4. emits RandomNumberFulfilled. 4. User Interfaces and Scripts can read `getLatestRandomWord()` or poll `getRequestStatus()`.

EXAMPLE - RandomNumberConsumer.sol

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.19; import {VRFConsumerBaseV2Plus} from "@chainlink/contracts@1.4.0/src/v0.8/vrf/dev/VRFConsumerBaseV2Plus.sol"; import {VRFV2PlusClient} from "@chainlink/contracts@1.4.0/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol"; import {VRFV2PlusWrapperConsumerBase} from "@chainlink/contracts@1.4.0/src/v0.8/vrf/dev/VRFV2PlusWrapperConsumerBase.sol"; import {ConfirmedOwner} from "@chainlink/contracts@1.4.0/src/v0.8/shared/access/ConfirmedOwner.sol"; contract RandomNumberConsumer is VRFV2PlusWrapperConsumerBase, ConfirmedOwner { uint256 public latestRequestId; uint256[] public latestRandomWord; bool public fulfilled; uint32 public constant CALLBACK_GAS_LIMIT = 2_100_000; uint16 public constant REQUEST_CONFIRMATIONS = 3; uint32 public constant NUM_WORDS = 3; event RandomNumberRequested(uint256 indexed requestId, address indexed requester, uint256 paid); event RandomNumberFulfilled(uint256 indexed requestId, uint256[] randomWord); error InsufficientPayment(uint256 required, uint256 sent); error RequestAlreadyPending(); constructor(address wrapper) ConfirmedOwner(msg.sender) VRFV2PlusWrapperConsumerBase(wrapper) {} function requestRandomNumber() external payable onlyOwner { // Check if there's already a pending request if (latestRequestId != 0 && !fulfilled) { revert RequestAlreadyPending(); } // Calculate the required payment uint256 requestPrice = getRequestPrice(); if (msg.value < requestPrice) { revert InsufficientPayment(requestPrice, msg.value); } // Prepare the extra arguments for native payment VRFV2PlusClient.ExtraArgsV1 memory extraArgs = VRFV2PlusClient.ExtraArgsV1({ nativePayment: true }); bytes memory args = VRFV2PlusClient._argsToBytes(extraArgs); // Request randomness (uint256 requestId, uint256 paid) = requestRandomnessPayInNative( CALLBACK_GAS_LIMIT, REQUEST_CONFIRMATIONS, NUM_WORDS, args ); latestRequestId = requestId; fulfilled = false; emit RandomNumberRequested(requestId, msg.sender, paid); // Refund excess payment if (msg.value > paid) { (bool success, ) = msg.sender.call{value: msg.value - paid}(""); require(success, "Refund failed"); } } // This will be called by the VRF Wrapper function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal override { require(randomWords.length > 0, "No random word returned"); require(requestId == latestRequestId, "Unexpected request ID"); latestRandomWord = randomWords; fulfilled = true; emit RandomNumberFulfilled(requestId, randomWords); } function getRequestStatus() external view returns ( uint256 requestId, bool isPending, bool isFulfilled ) { return ( latestRequestId, latestRequestId != 0 && !fulfilled, fulfilled ); } function getLatestRandomWord() external view returns (uint256[] memory) { require(fulfilled, "No fulfilled request yet"); return latestRandomWord; } /** * @notice Get the current price for a VRF request in native tokens * @return The price in wei for requesting random numbers */ function getRequestPrice() public view returns (uint256) { return i_vrfV2PlusWrapper.calculateRequestPriceNative(CALLBACK_GAS_LIMIT, NUM_WORDS); } /** * @notice Withdraw any excess native tokens from the contract * @dev Only callable by owner, useful for recovering overpayments */ function withdraw() external onlyOwner { uint256 balance = address(this).balance; require(balance > 0, "No balance to withdraw"); (bool success, ) = owner().call{value: balance}(""); require(success, "Withdrawal failed"); } // Allow contract to receive STT for native payment receive() external payable {} } ```

## Code Breakdown ```solidity contract RandomNumberConsumer is VRFV2PlusWrapperConsumerBase, ConfirmedOwner ``` `VRFV2PlusWrapperConsumerBase` gives you the glue code for requesting randomness from the VRF Wrapper and receiving the callback `(fulfillRandomWords)`. It also exposes the wrapper instance `i_vrfV2PlusWrapper`. `ConfirmedOwner` is a lightweight ownership module; it lets you restrict actions to the contract owner via onlyOwner. ## State Variables ```solidity uint256 public latestRequestId; uint256[] public latestRandomWord; bool public fulfilled; ``` `latestRequestId` tracks the most recent VRF request ID. Used to make sure the fulfillment we receive matches the last request.\ \ `latestRandomWord` stores the three random words returned by VRF for the latest request.\ \ `fulfilled` marks whether the latest request has finished (prevents overlapping requests and makes UI/state checks easy). ## VRF Request Parameters (constants) ```solidity uint32 public constant CALLBACK_GAS_LIMIT = 2_100_000; uint16 public constant REQUEST_CONFIRMATIONS = 3; uint32 public constant NUM_WORDS = 3; ``` `CALLBACK_GAS_LIMIT` is the max gas VRF can use when calling your `fulfillRandomWords`. Must be large enough for your logic. This example uses headroom for 3 words.\ \ `REQUEST_CONFIRMATIONS` is how many blocks to wait before fulfillment (trade-off between speed and reorg safety).\ \ `NUM_WORDS` This is how many random numbers you want per request. Here, it’s 3. ## Events ```solidity event RandomNumberRequested(uint256 indexed requestId, address indexed requester, uint256 paid); event RandomNumberFulfilled(uint256 indexed requestId, uint256[] randomWord); ``` `RandomNumberRequested` is emitted right after submitting a VRF request. Includes the paid cost in native STT.\ \ `RandomNumberFulfilled` is emitted when VRF returns the result, with the three random words. Events make it easy to monitor behavior from explorers, indexers, or frontends. ## Custom errors ```solidity error InsufficientPayment(uint256 required, uint256 sent); error RequestAlreadyPending(); ``` `InsufficientPayment` is thrown if msg.value doesn’t cover the VRF native fee at request time. `RequestAlreadyPending` is thrown if you try to request again while the previous request hasn’t been fulfilled. Errors are cheaper than require("string") and clearer to reason about. ## Constructor ```solidity constructor(address wrapper) ConfirmedOwner(msg.sender) VRFV2PlusWrapperConsumerBase(wrapper) {} ``` Takes the VRF V2+ Wrapper address (the on-chain contract that mediates VRF requests) and initializes ownership to the deployer. ## Function Requesting Randomness ```solidity function requestRandomNumber() external payable onlyOwner { // 1) block overlapping requests if (latestRequestId != 0 && !fulfilled) revert RequestAlreadyPending(); // 2) compute required fee and validate payment uint256 requestPrice = getRequestPrice(); if (msg.value < requestPrice) revert InsufficientPayment(requestPrice, msg.value); // 3) signal native payment to the wrapper bytes memory args = VRFV2PlusClient._argsToBytes( VRFV2PlusClient.ExtraArgsV1({ nativePayment: true }) ); // 4) submit request (uses native STT) (uint256 requestId, uint256 paid) = requestRandomnessPayInNative( CALLBACK_GAS_LIMIT, REQUEST_CONFIRMATIONS, NUM_WORDS, args ); latestRequestId = requestId; fulfilled = false; emit RandomNumberRequested(requestId, msg.sender, paid); // 5) refund any excess back to caller if (msg.value > paid) { (bool ok, ) = msg.sender.call{ value: msg.value - paid }(""); require(ok, "Refund failed"); } } ``` The `requestRandomNumber()` function implements safeguards and processes to ensure reliable VRF operation. First, it enforces safety by preventing spam or overlapping requests, which ensures a predictable user experience and maintains simpler state management. The function then calculates the exact payment required by calling `getRequestPrice()` to determine how much STT the wrapper currently needs, rejecting any transaction with insufficient payment. To specify the payment method, it encodes `nativePayment: true` in the request parameters, instructing the wrapper to charge in native STT tokens rather than LINK. Once validated, the function submits the request through `requestRandomnessPayInNative()`, which initiates the VRF request to Chainlink while storing the returned requestId and marking the fulfilled status as false to track the pending request. Finally, the function implements automatic refund logic that returns any excess funds to the user if they overpaid, ensuring users never lose funds due to price variations. ## READ OPERATIONS ### VRF callback (fulfillment) ```solidity function fulfillRandomWords( uint256 requestId, uint256[] memory randomWords ) internal override { require(randomWords.length > 0, "No random word returned"); require(requestId == latestRequestId, "Unexpected request ID"); latestRandomWord = randomWords; // stores 3 words fulfilled = true; emit RandomNumberFulfilled(requestId, randomWords); } ``` Called by the VRF Wrapper (not by you) and validates that we actually received words, and the `requestId` matches the latest request (guards against stale/foreign callbacks). It then stores the 3 words and flips `fulfilled = true` and emits a completion event. If you need game logic, derive from these random words inside this function or store and consume later. ### getRequestStatus() ```solidity function getRequestStatus() external view returns (uint256 requestId, bool isPending, bool isFulfilled) { return (latestRequestId, latestRequestId != 0 && !fulfilled, fulfilled); } ``` For frontends/monitoring: see the last `request ID`, whether it’s still `pending`, and whether it was `fulfilled`. ### getLatestRandomWord() ```solidity function getLatestRandomWord() external view returns (uint256[] memory) { require(fulfilled, "No fulfilled request yet"); return latestRandomWord; } ``` Returns the three words from the most recent fulfilled request, which is actually a string on numbers for example: `93869141573160465677701763703933181905260360385351294458479680637737009096153` ### Pricing Helper ```solidity function getRequestPrice() public view returns (uint256) { return i_vrfV2PlusWrapper.calculateRequestPriceNative(CALLBACK_GAS_LIMIT, NUM_WORDS); } ``` Asks the wrapper how much STT (in wei) you need right now for a request with your chosen `CALLBACK_GAS_LIMIT` and `NUM_WORDS`. Use this in your UI or scripts to fill `msg.value`. ## Conclusion You've successfully built a secure random number generator on Somnia using Chainlink VRF v2.5. Your `RandomNumberConsumer` Smart Contract provides tamper proof randomness with native STT payment, automatic refunds, and proper request management, everything needed for production use. ### Real-World VRF Use Cases VRF powers a wide range of blockchain applications where fairness is critical. In gaming, it enables trustworthy dice rolls, loot drops, critical hit calculations, and procedurally generated maps. For NFT collections, VRF ensures unbiased trait assignment during minting, metadata reveals, and rarity distribution. This is crucial when traits can be worth thousands. Lotteries and raffles benefit from transparent winner selection, whether for small community giveaways or million dollar prize pools. DeFi protocols use VRF for random liquidator selection, fair distribution, and variable reward mechanisms, while DAO governance applications include jury selection for disputes, randomized proposal ordering, and representative sampling for surveys. With VRF integrated, you're ready to build applications where fairness is cryptographically guaranteed, not just promised. Whether for games, NFTs, or DeFi protocols, your users can verify that randomness is truly random and build trust through mathematics, not faith.
# Example Applications This section showcases **hands-on examples** of real applications built on Somnia, from small experimental dApps to full scale and production ready projects. Each example walks you through architecture, deployment, and integration patterns, helping you understand **how all the pieces fit together:** contracts, subgraphs, oracles, APIs, and SDKs. You’ll find examples like: * Token swap dApps (DEX) * DAO Smart Contract * DAO User Interface > These examples are meant to inspire and guide you. Use them as blueprints, remix them, or extend them — and build the next great dApp on Somnia. # DAO Smart Contract Decentralized Autonomous Organizations (DAOs) are an innovative way to organize communities where decisions are made collectively without centralized authority. In this tutorial, we’ll explore a simple DAO implemented in Solidity. By the end, you’ll understand how to deploy and interact with this contract. {% hint style="success" %} Somnia Mainnet is LIVE. To deploy on Somnia Mainnet, you will need SOMI Tokens. Please refer to the [guide](/get-started/getting-started-for-mainnet) on Moving from Testnet to Mainnet. {% endhint %} ## Example Use Case: DAO Implementation in Gaming DAOs can be particularly impactful in gaming environments. Imagine a massive multiplayer online game (MMO) with a shared in-game economy. A DAO can be used to manage a treasury funded by player contributions, allowing players to propose and vote on game updates, community events, or rewards. For example: 1. In-Game Treasury Management: Players deposit some of their in-game earnings into a DAO treasury. Proposals for using these funds—such as hosting tournaments or funding new content—are created and voted on. 2. Player-Driven Governance: Gamers vote on new features like maps, characters, or weapons, giving them a direct say in the game's evolution. 3. Community Rewards: DAOs could allocate funds to reward top-performing players or teams, enhancing engagement and competition. This decentralized approach ensures that game updates align with player interests, creating a more engaging and community-driven gaming experience. ## Prerequisites Before starting, ensure you have: 1. This guide is not an introduction to Solidity Programming; you are expected to understand Basic Solidity Programming. 2. To complete this guide, you will need MetaMask installed and the Somnia Network added to the list of Networks. If you have yet to install MetaMask, please follow this guide to Connect Your Wallet. 3. You can deploy the Smart Contracts using our Hardhat or Foundry guides. ## Overview of the DAO Contract

The provided DAO contract allows users to: 1. Deposit funds to gain voting power. 2. Create proposals. 3. Vote on proposals. 4. Execute proposals if they pass. The key features of the contract include: * Proposal Struct: Stores details of proposals. * Voting Mechanism: Allows weighted voting based on deposited funds. * Execution Logic: Ensures proposals are executed only if approved. ## Setting Up the Development Environment Follow the [Hardhat](/developer/development-frameworks/deploy-with-hardhat) or [Foundry](/developer/development-frameworks/deploy-with-foundry) guides. ## Create the Smart Contract Create a new file named DAO.sol in the contracts folder and copy the provided contract code.

DAO.sol

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.28; contract DAO { struct Proposal { string description; // Proposal details uint256 deadline; // Voting deadline uint256 yesVotes; // Votes in favor uint256 noVotes; // Votes against bool executed; // Whether the proposal has been executed address proposer; // Address of the proposer } mapping(uint256 => Proposal) public proposals; mapping(address => uint256) public votingPower; mapping(uint256 => mapping(address => bool)) public hasVoted; uint256 public totalProposals; uint256 public votingDuration = 10 minutes; address public owner; modifier onlyOwner() { require(msg.sender == owner, "Not the owner"); _; } constructor() { owner = msg.sender; } function deposit() external payable { require(msg.value == 0.001 ether, "Must deposit STT"); votingPower[msg.sender] += msg.value; } function createProposal(string calldata description) external { require(votingPower[msg.sender] > 0, "No voting power"); proposals[totalProposals] = Proposal({ description: description, deadline: block.timestamp + votingDuration, yesVotes: 0, noVotes: 0, executed: false, proposer: msg.sender }); totalProposals++; } function vote(uint256 proposalId, bool support) external { Proposal storage proposal = proposals[proposalId]; require(block.timestamp < proposal.deadline, "Voting has ended"); require(!hasVoted[proposalId][msg.sender], "Already voted"); require(votingPower[msg.sender] > 0, "No voting power"); hasVoted[proposalId][msg.sender] = true; if (support) { proposal.yesVotes += votingPower[msg.sender]; } else { proposal.noVotes += votingPower[msg.sender]; } } function executeProposal(uint256 proposalId) external { Proposal storage proposal = proposals[proposalId]; require(block.timestamp >= proposal.deadline, "Voting still active"); require(!proposal.executed, "Proposal already executed"); require(proposal.yesVotes > proposal.noVotes, "Proposal did not pass"); proposal.executed = true; // Logic for proposal execution // Example: transfer STT to proposer as a reward for successful vote pass payable(proposal.proposer).transfer(0.001 ether); } } ```

Let’s break down the contract into its main components: #### Mappings Mappings are used to store structured data efficiently: 1. **`proposals`** ```solidity mapping(uint256 => Proposal) public proposals; ``` * Stores all proposals created in the DAO. * It represents the Proposal `struct` containing details like description, deadline, votes, and proposer. ```solidity struct Proposal { string description; // Proposal details uint256 deadline; // Voting deadline uint256 yesVotes; // Votes in favor uint256 noVotes; // Votes against bool executed; // Whether the proposal has been executed address proposer; // Address of the proposer } ``` 2. **`votingPower`** ```solidity mapping(address => uint256) public votingPower; ``` * Tracks the voting power of each address. * Voting power increases when users deposit funds into the DAO. 3. **`hasVoted`** ```solidity mapping(uint256 => mapping(address => bool)) public hasVoted; ``` * Tracks whether a specific address has voted on a specific proposal. * Prevents double voting. #### Functions The contract includes several key functions: 1. **`Constructor`** ```solidity constructor() { owner = msg.sender; } ``` * Sets the deployer as the owner of the contract.\
2. **`deposit`** ```solidity function deposit() external payable { require(msg.value >= 0.001 ether, "Minimum deposit is 0.001 STT"); votingPower[msg.sender] += msg.value; } ``` * Allows users to deposit STT Tokens to gain voting power. * Increases their votingPower by the amount deposited. 3. **`createProposal`** ```solidity function createProposal(string calldata description) external { require(votingPower[msg.sender] > 0, "No voting power"); proposals[totalProposals] = Proposal({ description: description, deadline: block.timestamp + votingDuration, yesVotes: 0, noVotes: 0, executed: false, proposer: msg.sender }); totalProposals++; } ``` * Allows users with voting power to create new proposals. * Adds the proposal to the proposals mapping. 4. **`vote`** ```solidity function vote(uint256 proposalId, bool support) external { Proposal storage proposal = proposals[proposalId]; require(block.timestamp < proposal.deadline, "Voting has ended"); require(!hasVoted[proposalId][msg.sender], "Already voted"); require(votingPower[msg.sender] > 0, "No voting power"); hasVoted[proposalId][msg.sender] = true; if (support) { proposal.yesVotes += votingPower[msg.sender]; } else { proposal.noVotes += votingPower[msg.sender]; } } ``` * Allows users to cast a vote on a proposal. * Updates the **`yesVotes`** or **`noVotes`** in the Proposal struct based on the user's choice. * Prevents double voting by using the **`hasVoted`** mapping. 5. **`executeProposal`** ```solidity function executeProposal(uint256 proposalId) external { Proposal storage proposal = proposals[proposalId]; require(block.timestamp >= proposal.deadline, "Voting still active"); require(!proposal.executed, "Proposal already executed"); require(proposal.yesVotes > proposal.noVotes, "Proposal did not pass"); proposal.executed = true; payable(proposal.proposer).transfer(0.001 ether); } ``` * Executes a proposal if it passes (more yes votes than no votes). * Transfers a fixed amount of ETH to the proposer as an example of execution logic. * Ensures proposals cannot be executed multiple times. #### Key Variables 1. **`totalProposals`** ```solidity uint256 public totalProposals; ``` * Tracks the total number of proposals created. 2. **`votingDuration`** ```solidity uint256 public votingDuration = 10 minutes; ``` * Sets the default duration for voting on proposals. 3. **`owner`** ```solidity address public owner; ``` * Stores the address of the contract owner. * Used for functions that require administrative control. Understanding these components shows how the DAO enables decentralized governance while maintaining transparency and fairness. ## Deploy the Smart Contract to Somnia Follow the [Hardhat](/developer/development-frameworks/deploy-with-hardhat) or [Foundry](/developer/development-frameworks/deploy-with-foundry) guides. First, compile the Smart Contract to Bytecode by running the Hardhat or Foundry compile instructions. This is an example deployment script using Hardhat. Create a file in the **`/ignition/module`** folder and name it **`deploy.js`** ```javascript import { buildModule } from "@nomicfoundation/hardhat-ignition/modules"; const dao = buildModule("DAO", (m) => { const contract = m.contract("DAO"); return { contract }; }); module.exports = dao; ``` Before running the deploy command, add Somnia Network to the **`hardhat.config.js`** file: ```javascript const config = { solidity: "0.8.28", networks: { somnia: { url: "https://dream-rpc.somnia.network", accounts: ["YOUR_PRIVATE_KEY"], }, }, }; ``` Ensure that the deploying address has enough STT Tokens. You can get STT Tokens from the [Faucet](https://devnet.somnia.network/). Run the deployment script: ```bash npx hardhat ignition deploy ./ignition/modules/deploy.ts --network somnia ``` Congratulations. :tada: You have successfully deployed the DAO Smart Contract. :tada: ## Interacting with the Contract Use the Hardhat console or scripts to interact with the contract. #### 1. Deposit Funds Call the deposit function to gain voting power: ```javascript await dao.deposit({ value: ethers.utils.parseEther("0.001") }); ``` #### 2. Create a Proposal Create a new proposal by calling createProposal: ```javascript await dao.createProposal("Fund development of new feature"); ``` #### 3. Vote on a Proposal Vote on a proposal by specifying its ID and your support (true for yes, false for no): ```javascript await dao.vote(0, true); // Vote ‘yes’ on proposal 0 ``` #### 4. Execute a Proposal After the voting deadline, execute the proposal if it has majority votes: ```javascript await dao.executeProposal(0); ``` ## Testing the Contract #### Writing Tests Create a test file DAO.test.js in the test folder. ```javascript const { expect } = require("chai"); const { ethers } = require("hardhat"); describe("DAO", function () { let dao; let owner, addr1; beforeEach(async function () { const DAO = await ethers.getContractFactory("DAO"); dao = await DAO.deploy(); [owner, addr1] = await ethers.getSigners(); }); it("Should allow deposits and update voting power", async function () { await dao.connect(addr1).deposit({ value: ethers.utils.parseEther("0.001") }); expect(await dao.votingPower(addr1.address)).to.equal(ethers.utils.parseEther("0.001")); }); it("Should allow proposal creation", async function () { await dao.connect(addr1).deposit({ value: ethers.utils.parseEther("0.001") }); await dao.connect(addr1).createProposal("Test Proposal"); const proposal = await dao.proposals(0); expect(proposal.description).to.equal("Test Proposal"); }); }); ``` Run the tests: ```bash npx hardhat test ``` ## Enhance the DAO You can expand this DAO contract by: 1. Adding Governance Tokens: Reward participants with tokens for voting or executing proposals. Follow the ERC20 Token Guide here. 2. Implementing Quorums: Require a minimum number of votes for proposals to pass. 3. Flexible Voting Power: Allow dynamic voting power allocation. ## Conclusion This tutorial provided a foundational understanding of building and deploying a simple DAO on Somnia. Experiment with enhancements to create more complex governance structures. DAOs are a powerful tool for decentralized decision-making, and the possibilities for innovation are limitless!
# DAO UI Tutorial p1 Somnia empowers developers to build applications for mass adoption. Smart Contracts deployed on the Somnia Blockchain will sometimes require building a User Interface. This guide will teach you how to build a user interface for a [DAO Smart Contract](/developer/building-dapps/example-applications/dao-smart-contract) using Next.js and React Context. It is divided into three parts. At the end of this guide, you’ll learn how to: 1. Initialize a Next.js project. 2. Set up a global state using the Context API ([**`useContext`**](https://react.dev/reference/react/useContext) hook). 3. Add a global NavBar in **`_app.js`** so it appears on every page. You will have a basic skeleton of a DApp, ready for **READ/WRITE** operations and UI components —topics we’ll cover in the subsequent articles. *** ## Pre-requisites: 1. This guide is not an introduction to JavaScript Programming; you are expected to understand JavaScript. 2. To complete this guide, you will need MetaMask installed and the Somnia Network added to the list of Networks. If you have yet to install MetaMask, please follow this guide to [Connect Your Wallet](https://codex.somnia.network/get-started/connect-your-wallet). ## Create Your Next.js Project To create a NextJS project, run the command: ```bash npx create-next-app my-dapp-ui ``` Accept the prompts and change directory into the folder after the build is completed. This gives you a minimal Next.js setup with a pages folder (holding your routes), a public folder (for static assets), and config files. #### (Optional) Add Tailwind CSS If you plan to style your app with Tailwind, install and configure it now: ```bash npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -p ``` Then edit your tailwind.config.js: ```javascript module.exports = { content: [ "./pages/**/*.{js,ts,jsx,tsx}", "./components/**/*.{js,ts,jsx,tsx}", ], theme: { extend: {}, }, plugins: [], } ``` Finally, include Tailwind in styles/globals.css: ```css @tailwind base; @tailwind components; @tailwind utilities; ``` *** ## Setting Up a React Context for Global State In many DApps, including this one, developers will manage **Wallet connection** and **State** globally so each page and component in the project can access it without repetitive code. This can be achieved by a [Context](https://react.dev/learn/passing-data-deeply-with-context) following React patterns. * Create a folder and name it **`contexts`** at the project root or inside **`pages`** directory. * Inside it, create a file called **`walletcontext.js`** add the following code to the file:

walletcontext.js

```javascript import { createContext, useContext, useState } from "react"; const WalletContext = createContext(); export function WalletProvider({ children }) { const [connected, setConnected] = useState(false); const [address, setAddress] = useState(""); async function connectToMetaMask() { if (typeof window !== "undefined" && window.ethereum) { try { await window.ethereum.request({ method: "eth_requestAccounts" }); // For simplicity, get the first address const [userAddress] = window.ethereum.selectedAddress ? [window.ethereum.selectedAddress] : []; setAddress(userAddress); setConnected(true); } catch (err) { console.error("User denied account access:", err); } } else { console.log("MetaMask is not installed!"); } } function disconnectWallet() { setConnected(false); setAddress(""); } // Return the context provider return ( {children} ); } export function useWallet() { return useContext(WalletContext); } ```

We parse three class methods from React: **`createContext`**, **`useContext`**, and**`useState`** `createContext` is used to create a [context](https://react.dev/learn/passing-data-deeply-with-context) that components can provide or read. In this example, we assign `createContext` to the **`WalletContext`** variable and call the **`Provider`** method on each State and Function to make them available throughout the application. **`useWallet()`** is a custom hook, so any page or component can do: ```javascript const { connected, ... } = useWallet() ``` to access the global wallet state i.e. any of the **`Wallet.Provider`** methods **`connectToMetaMask()`** triggers the MetaMask connection flow. **`WalletProvider`** manages **State** and **Methods** in the application. *** ## Creating a Global NavBar in \_app.js Next.js automatically uses **`pages/_app.js`** to initialize every page. We will wrap the entire app in the **`WalletProvider`** inside `_app.js` and inject a **`NavBar`** menu that appears site-wide in the application #### Create the `_app.js` and add the code: ```javascript import "../styles/globals.css"; import { WalletProvider } from "../contexts/walletcontext"; import NavBar from "../components/navbar"; function MyApp({ Component, pageProps }) { return (

); } export default MyApp; ``` **``** wraps the entire **``** tree so that every page can share the same wallet state. **``** is placed above **`

`**, so it’s visible on all pages. We give **`

`** a pt-16 to avoid content hiding behind a fixed navbar. ## NavBar Create a sub directory **components** and add a file called **`navbar.js`** Add the code: ```javascript import { useWallet } from "../contexts/walletcontext"; import Link from "next/link"; export default function NavBar() { const { connected, address, disconnectWallet } = useWallet(); return ( ); } ``` It uses **`useWallet()`** to read the global `connected` and `address`states, and the **`disconnectWallet`** function. The truncated `address` is displayed if a user is logged into the App or “Not connected” otherwise. A **Logout** button calls **`disconnectWallet()`** to reset the global state. *** ## Test Your Setup Start the dev server: ```bash npm run dev ``` Open **** in a Web Browser.\ \ You should see your NavBar at the top.

Because we haven’t built any advanced pages yet, you will see a blank home page. The important part is that your **WalletContext** and global **NavBar** are in place and ready for the next steps.\
*** ### 5. Next Steps * Article 2 shows you how to implement READ/WRITE operations (e.g., deposit, create proposals, vote, etc.) across different Next.js pages—using the same WalletContext to handle contract calls. * Article 3 will focus on UI components, like forms, buttons, and event handling, tying it all together into a polished user interface. Congratulations! You have a clean foundation, a Next.js project configured with Tailwind, a global context to manage wallet states, and a NavBar appearing across all routes. This sets the stage for adding contract interactions and advanced UI flows in the subsequent articles. Happy building!
# DAO UI Tutorial p2 This guide will focus exclusively on implementing Read Operations, which fetches data from your deployed [DAO Smart Contract](/developer/building-dapps/example-applications/dao-smart-contract). By the end of this article, you’ll be able to: 1. Understand how to read data from your smart contract using [viem](/developer/development-frameworks/using-the-viem-library). 2. Implement functions to fetch the total number of proposals and specific proposal details. 3. Integrate these READ operations into your Next.js pages to display dynamic data. Prerequisite:\ Ensure you’ve completed [Part 1](/developer/building-dapps/example-applications/dao-ui-tutorial-p1) of this series, where you initialized a Next.js project, set up a **`WalletContext`** for global state management, and added a global **`NavBar`**. *** ## Understand READ Operations In decentralized applications (dApps), Read Operations involve fetching data from the blockchain without altering its state. In the example DAO Smart Contract, this is crucial for displaying dynamic information such as: * **Total Number of Proposals**: How many proposals have been created. * **Proposal Details**: Information about a specific proposal, including its description, votes, and execution status. These operations are read-only and do not require the user to sign any transactions, making them free of gas costs. We’ll use the viem library to interact with our smart contract and perform these READ operations. *** ## Expand walletcontext.js for Read Operations **`walletcontext.js`** is the central hub for managing wallet connections and interacting with your Smart Contract. We’ll add two primary READ functions: 1. **`fetchTotalProposals()`**: Retrieves the total number of proposals created. 2. **`fetchProposal(proposalId)`**: Fetches details of a specific proposal by its ID. ### Fetch Total Proposals Functionality: This function calls the **`totalProposals`** method in your smart contract to determine how many proposals have been created so far.

contexts/walletcontext.js

```javascript import { createContext, useContext, useState } from "react"; import { defineChain, createPublicClient, createWalletClient, http, custom, parseEther, } from "viem"; import { ABI } from "../../abi"; // Adjust the path as necessary // Define Somnia Chain const SOMNIA = defineChain({ id: 50312, name: "Somnia Testnet", nativeCurrency: { decimals: 18, name: "Ether", symbol: "STT", }, rpcUrls: { default: { http: ["https://dream-rpc.somnia.network"], }, }, blockExplorers: { default: { name: "Explorer", url: "https://somnia-devnet.socialscan.io" }, }, }); // Create a public client for read operations const publicClient = createPublicClient({ chain: SOMNIA, transport: http(), }); const WalletContext = createContext(); export function WalletProvider({ children }) { // ---------- STATE ------------ const [connected, setConnected] = useState(false); const [address, setAddress] = useState(""); const [client, setClient] = useState(null); // Fetch Total Proposals async function fetchTotalProposals() { try { const result = await publicClient.readContract({ address: "0x7be249A360DB86E2Cf538A6893f37aFd89C70Ab4", abi: ABI, functionName: "totalProposals", }); return result; // Returns a BigInt } catch (error) { console.error("Error fetching totalProposals:", error); throw error; } } // Fetch Proposal Details async function fetchProposal(proposalId) { try { const result = await publicClient.readContract({ address: "0x7be249A360DB86E2Cf538A6893f37aFd89C70Ab4", abi: ABI, functionName: "proposals", args: [parseInt(proposalId)], }); console.log(result); return result; // Returns the Proposal struct } catch (error) { console.error("Error fetching proposal:", error); throw error; } } // Provider's value return ( {children} ); } // Custom hook to consume context export function useWallet() { return useContext(WalletContext); } ```

**`fetchTotalProposals()`** uses **`publicClient.readContract`** to call the **`totalProposals`** function in the Smart Contract. This function returns a `BigInt` representing the total number of proposals.\ \ \&#xNAN;**`fetchProposal(proposalId)`** calls the proposals mapping in your contract to retrieve details of a specific proposal by its `ID`. It returns a struct containing the proposal's **description**, **deadline**, **votes**, **execution status**, and **proposer**. *** ## Integrate Read Operations into Pages With the read functions in place, let’s integrate them into Next.js pages to display dynamic data. ### Home Page Update the `index.js` page to show the total number of proposals created in your DAO on the home page.

pages/index.js

```javascript import { useState, useEffect } from "react"; import ConnectButton from "../components/connectbutton"; import { useWallet } from "../contexts/walletcontext"; export default function Home() { const { fetchTotalProposals } = useWallet(); const [totalProposals, setTotalProposals] = useState(null); useEffect(() => { async function loadData() { try { const count = await fetchTotalProposals(); setTotalProposals(count); } catch (error) { console.error("Failed to fetch total proposals:", error); } } loadData(); }, [fetchTotalProposals]); return (

{/* The NavBar is already rendered in _app.js */}

Welcome to MyDAO

{totalProposals !== null ? (

Total proposals created: {totalProposals.toString()}

) : (

Loading total proposals...

)}

); } ```

Here we set the `totalProposals` state variable to store the fetched total number of proposals.\ The **`ConnectButton`** implements the MetaMask authentication. The useWallet hook parse the function from **`WalletContext.`** The **`useEffect`** Hook is applied on component mount, **`fetchTotalProposals()`** is then called to retrieve the total number of proposals from the Smart Contract. The page displays a loading message until totalProposals is fetched. Once fetched, it displays the total number of proposals. Users will have to click the **ConnectButton** to connect their wallets for WRITE operations. See part 3. *** ### Fetch-Proposal Page This page allow users to input a proposal ID, fetch its details, and display them. Additionally, on the page users are provided options for voting on or executing the proposal. Implementation:

pages/fetch-proposal.js

```javascript import { useState, useEffect } from "react"; import { useRouter } from "next/router"; import { useWallet } from "../contexts/walletcontext"; import { Button, Card, Label, TextInput } from "flowbite-react"; // Optional Flowbite imports export default function FetchProposalPage() { const [proposalId, setProposalId] = useState(""); const [proposalData, setProposalData] = useState(null); const [error, setError] = useState(""); const { connected, fetchProposal, voteOnProposal, executeProposal } = useWallet(); const handleSubmit = async (e) => { e.preventDefault(); setError(""); // Clear previous errors if (!connected) { alert("You must connect your wallet first!"); return; } if (!proposalId.trim()) { setError("Please enter a proposal ID."); return; } try { // Fetch the proposal from the contract const result = await fetchProposal(proposalId); console.log("Fetched Proposal:", result); setProposalData(result); } catch (err) { console.error("Error fetching proposal:", err); setError("Failed to fetch proposal. Check console for details."); } }; useEffect(() => { if (proposalData !== null) { console.log("Updated Proposal Data:", proposalData); } }, [proposalData]); return (

Fetch a Proposal

{/* Form to input Proposal ID */} {/* Display Errors */} {error &&

{error}

} {/* Display Proposal Details */} {proposalData && (

Proposal #{proposalId}

Description: {proposalData[0]}
Deadline: {new Date(proposalData[1] * 1000).toLocaleString()}
Yes Votes: {proposalData[2].toString()}
No Votes: {proposalData[3].toString()}
Executed: {proposalData[4] ? "Yes" : "No"}
Proposer: {proposalData[5]}

)} ); } ```

The following React states are implemented * `proposalId`: Stores the user-inputted proposal ID. * `proposalData`: Stores the fetched proposal details. * `error`: Captures any errors during fetch, vote, or execute operations. The **`handleSubmit`** function is used to validate the input and connection status. It then calls the **`fetchProposal(proposalId)`** to retrieve proposal details. We use a **Form** element for users to input a proposal ID and fetch its details. The **Error** Display is implemented to show any errors that occur during operations. The **Proposal Details** displays the fetched proposal information in a styled card. The card contains **Vote** and **Execute b**uttons for users to vote **YES/NO** or execute the proposal if eligible. *** ## Edge Cases and Errors For better UX, consider adding loading indicators while fetching data or awaiting transaction confirmations. Example:

pages/fetch-proposal.js

```javascript const [loading, setLoading] = useState(false); // In handleSubmit const handleSubmit = async (e) => { e.preventDefault(); setError(""); setLoading(true); // ... rest of the code setLoading(false); }; // In the button ```

*** ## Test Read Operations ### Populate Some Data Before testing read operations, make sure there are some proposals created: 1. Load your Smart Contract on the [Remix IDE](/developer/building-dapps/tokens-and-nfts/create-erc20-tokens). 2. Deposit 0.001 ETH to gain voting power. 3. Create one or more proposals via the Create Proposal page. ### Verify Read Operations Run your application using the command: ``` npm run dev ``` Your application will be running on **`localhost:3000`** in your web browser. Check for the following in the User Interface: 1. Total Proposals: On the Home page, verify that the total number of proposals matches the number you’ve created via Remix IDE. 2. Fetch Proposal Details:\ \- Navigate to the Fetch-Proposal page.\ \- Input a valid proposalId (e.g., 0 for the first proposal).\ \- Verify that all proposal details are accurately displayed. Monitor the browser console for any errors or logs that can help in debugging. *** ## Conclusion and Next Steps In Part 2, you successfully implemented Read Operations in your DAO front end: * **`fetchTotalProposals()`**: Displayed the total number of proposals on the Home page. * **fetchProposal(proposalId)**: Retrieved and displayed specific proposal details on the Fetch-Proposal page. #### What's Next? Stay tuned for Part 3 of this series, where we’ll dive into building UI Components—crafting forms, buttons, and enhancing event handling to create a more polished and user-friendly interface for your DAO dApp. *** Congratulations! You’ve now built a robust foundation for reading data from your DAO smart contract within your Next.js front end. Keep experimenting and enhancing your dApp’s capabilities in the upcoming sections!
# DAO UI Tutorial p3 This guide focuses exclusively on implementing Write Operations—interacting with your smart contract to perform actions such as depositing funds, creating proposals, voting, and executing proposals for the [DAO Smart Contract](/developer/building-dapps/example-applications/dao-smart-contract). By the end of this article, you’ll be able to: 1. Understand the Write Operations necessary for the DAO. 2. Implement these operations within the existing [WalletContext](/developer/building-dapps/example-applications/dao-ui-tutorial-p1). 3. Integrate these operations into your Next.js pages with intuitive UI components. 4. Handle transaction states and provide user feedback. Prerequisite:\ Ensure you’ve completed [Part 2](/developer/building-dapps/example-applications/dao-ui-tutorial-p2) of this series, where you set up the WalletContext for global state management and added a global NavBar. {% embed url="" %} *** ## Overview of Write Operations Write Operations in a DAO involve actions that modify the blockchain state. These include: * Depositing Funds: Adding 0.001 STT to the DAO to gain voting power. * Creating Proposals: Submitting new proposals for the DAO to consider. * Voting on Proposals: Casting votes (Yes/No) on existing proposals. * Executing Proposals: Finalizing and implementing approved proposals. These operations require users to sign transactions, incurring gas fees. Proper handling of these interactions is crucial for a smooth user experience. *** ## Expand WalletContext with Write Functions We’ll enhance the existing WalletContext by adding functions to handle the aforementioned write operations. This centralized approach ensures that all blockchain interactions are managed consistently. ### Implement deposit Allows users to deposit a fixed amount of ETH (e.g., 0.001 ETH) into the DAO contract to gain voting power.

contexts/walletContext.js

```javascript import { parseEther } from "viem"; export function WalletProvider({ children }) { // ...existing state and actions // Deposit Function const deposit = async () => { if (!client || !address) { alert("Please connect your wallet first!"); return; } try { const tx = await client.writeContract({ address: "0x7be249A360DB86E2Cf538A6893f37aFd89C70Ab4", // Your DAO contract address abi: ABI, functionName: "deposit", value: parseEther("0.001"), // 0.001 STT }); console.log("Deposit Transaction:", tx); alert("Deposit successful! Transaction hash: " + tx.hash); } catch (error) { console.error("Deposit failed:", error); alert("Deposit failed. Check console for details."); } }; // ...other functions return ( {children} ); } ```

**`parseEther("0.001")`**: Converts 0.001 STT to Wei, the smallest denomination of Ether. **`writeContract`**: Sends a transaction to call the deposit function on the DAO contract, transferring 0.001 STT. ### Implement createProposal Allows users to create a new proposal by submitting a description.

contexts/walletContext.js

```javascript export function WalletProvider({ children }) { // ...existing state and actions // Create Proposal Function const createProposal = async (description) => { if (!client || !address) { alert("Please connect your wallet first!"); return; } try { const tx = await client.writeContract({ address: "0x7be249A360DB86E2Cf538A6893f37aFd89C70Ab4", // Your DAO contract address abi: ABI, functionName: "createProposal", args: [description], }); console.log("Create Proposal Transaction:", tx); alert("Proposal created! Transaction hash: " + tx.hash); } catch (error) { console.error("Create Proposal failed:", error); alert("Failed to create proposal. Check console for details."); } }; // ...other functions return ( {children} ); } ```

**`createProposal(description)`**: Takes a proposal description as an argument and sends a transaction to the DAO contract to create the proposal. ### Implement voteOnProposal Allows users to vote on a specific proposal by its ID, supporting either a Yes or No vote.

contexts/walletContext.js

```javascript export function WalletProvider({ children }) { // ...existing state and actions // Vote on Proposal Function const voteOnProposal = async (proposalId, support) => { if (!client || !address) { alert("Please connect your wallet first!"); return; } try { const tx = await client.writeContract({ address: "0x7be249A360DB86E2Cf538A6893f37aFd89C70Ab4", // Your DAO contract address abi: ABI, functionName: "vote", args: [parseInt(proposalId), support], }); console.log("Vote Transaction:", tx); alert(`Voted ${support ? "YES" : "NO"} on proposal #${proposalId}! Transaction hash: ${tx.hash}`); } catch (error) { console.error("Vote failed:", error); alert("Voting failed. Check console for details."); } }; // ...other functions return ( {children} ); } ```

**`voteOnProposal(proposalId, support)`**: Takes a proposal ID and a boolean indicating support (**`true for Yes, false for No`**). Sends a transaction to cast the vote. ### Implement executeProposal Allows users to execute a proposal if it meets the necessary conditions (e.g., quorum reached).

contexts/walletContext.js

```javascript export function WalletProvider({ children }) { // ...existing state and actions // Execute Proposal Function const executeProposal = async (proposalId) => { if (!client || !address) { alert("Please connect your wallet first!"); return; } try { const tx = await client.writeContract({ address: "0x7be249A360DB86E2Cf538A6893f37aFd89C70Ab4", // Your DAO contract address abi: ABI, functionName: "executeProposal", args: [parseInt(proposalId)], }); console.log("Execute Proposal Transaction:", tx); alert(`Proposal #${proposalId} executed! Transaction hash: ${tx.hash}`); } catch (error) { console.error("Execute Proposal failed:", error); alert("Execution failed. Check console for details."); } }; // ...other functions return ( {children} ); } ```

**`executeProposal(proposalId)`**: Takes a proposal ID and sends a transaction to execute the proposal. *** ## Integrate Write Operations With the write functions added to WalletContext, the next step is to integrate these operations into your Next.js pages, providing users with interactive UI components to perform actions. ### Create-Proposal Page Allow users to submit new proposals by entering a description.

pages/create-proposal.js

```javascript import { useState } from "react"; import { useRouter } from "next/router"; import { useWallet } from "../contexts/walletContext"; import { Label, TextInput, Button, Alert } from "flowbite-react"; export default function CreateProposalPage() { const [description, setDescription] = useState(""); const [loading, setLoading] = useState(false); const [success, setSuccess] = useState(""); const [error, setError] = useState(""); const { connected, createProposal } = useWallet(); const router = useRouter(); const handleSubmit = async (e) => { e.preventDefault(); setError(""); setSuccess(""); if (!connected) { setError("You must connect your wallet first!"); return; } if (!description.trim()) { setError("Proposal description cannot be empty!"); return; } setLoading(true); try { await createProposal(description.trim()); setSuccess("Proposal created successfully!"); setDescription(""); // Optionally redirect to home or another page // router.push("/"); } catch (err) { console.error("Error creating proposal:", err); setError("Failed to create proposal. Check console for details."); } finally { setLoading(false); } }; return (

Create Proposal

{error && ( Error! {error} )} {success && ( Success! {success} )}

); } ```

State Variables: * **description**: Stores the user's input for the proposal description. * **loading**: Indicates whether the submission is in progress. * **success** **& error**: Handle user feedback messages. The **`handleSubmit`** function undergoes validation, ensuring that the user is connected and has entered a description. It then calls the **`createProposal`** from **`WalletContext`**. It displays success or error messages based on the outcome. The return statement contains the UI Components: * Label & TextInput: For user input. * Button: Triggers the submission. Disabled and shows a loading state when processing. * Alert: Provides visual feedback for success and error messages. ### Fetch-Proposal Page: Vote and Execution Allow users to fetch proposal details, vote on them, and execute if eligible.

pages/fetch-proposal.js

```javascript import { useState } from "react"; import { useWallet } from "../contexts/walletContext"; import { Button, Card, Label, TextInput, Spinner, Alert } from "flowbite-react"; export default function FetchProposalPage() { const [proposalId, setProposalId] = useState(""); const [proposalData, setProposalData] = useState(null); const [loading, setLoading] = useState(false); const [voting, setVoting] = useState(false); const [executing, setExecuting] = useState(false); const [error, setError] = useState(""); const [success, setSuccess] = useState(""); const { connected, fetchProposal, voteOnProposal, executeProposal } = useWallet(); const handleFetch = async (e) => { e.preventDefault(); setError(""); setSuccess(""); setProposalData(null); if (!connected) { setError("You must connect your wallet first!"); return; } if (!proposalId.trim()) { setError("Please enter a proposal ID."); return; } setLoading(true); try { const data = await fetchProposal(proposalId); setProposalData(data); } catch (err) { console.error("Error fetching proposal:", err); setError("Failed to fetch proposal. Check console for details."); } finally { setLoading(false); } }; const handleVote = async (support) => { setError(""); setSuccess(""); setVoting(true); try { await voteOnProposal(proposalId, support); setSuccess(`Successfully voted ${support ? "YES" : "NO"} on proposal #${proposalId}.`); // Optionally, refresh the proposal data const updatedData = await fetchProposal(proposalId); setProposalData(updatedData); } catch (err) { console.error("Error voting:", err); setError("Voting failed. Check console for details."); } finally { setVoting(false); } }; const handleExecute = async () => { setError(""); setSuccess(""); setExecuting(true); try { await executeProposal(proposalId); setSuccess(`Proposal #${proposalId} executed successfully.`); // Optionally, refresh the proposal data const updatedData = await fetchProposal(proposalId); setProposalData(updatedData); } catch (err) { console.error("Error executing proposal:", err); setError("Execution failed. Check console for details."); } finally { setExecuting(false); } }; return (

Fetch a Proposal

{/* Form to input Proposal ID */} {/* Display Errors */} {error && ( Error! {error} )} {/* Display Success Messages */} {success && ( Success! {success} )} {/* Display Proposal Details */} {proposalData && (

Proposal #{proposalId}

Description: {proposalData[0]}
Deadline: {new Date(proposalData[1] * 1000).toLocaleString()}
Yes Votes: {proposalData[2].toString()}
No Votes: {proposalData[3].toString()}
Executed: {proposalData[4] ? "Yes" : "No"}
Proposer: {proposalData[5]}

{/* Voting Buttons */}

{/* Execute Button */} {!proposalData[4] && (

)} )}

); } ```

State Variables: * **proposalId**: User input for the proposal ID. * **proposalData**: Stores fetched proposal details. * **loading, voting, executing**: Manage the loading states for different operations. * **error & success**: Handle feedback messages. The **`handleFetch`** function ensures the user is connected and has entered a valid proposal ID. It calls **`fetchProposal`** to retrieve proposal details, and displays error messages if fetching fails. The **`handleVote`** function has the parameters for indicating the Voter support (**true** for **Yes**, **false** for **No**). The function processes Vote, by calling **`voteOnProposal`** with the provided **`proposalId`** and **`support`**parameter`.` It returns success or error messages based on the outcome. It re-fetches the proposal to reflect updated vote counts. The **`handleExecute`** function processes execution by calling **`executeProposal`** with the provided ~~**proposalId**~~. It returns success or error messages based on the outcome, and re-fetches the proposal to reflect execution status. The return statement contains the UI Components: * Label & TextInput: For inputting the proposal ID. * Button: Triggers fetching, voting, and executing actions. Disabled and shows a spinner during processing. * Alert: Provides visual feedback for success and error messages. * Card: Displays the fetched proposal details in a structured format. * Voting & Execution Buttons: Allow users to interact with the proposal directly from the details view. *** ## Transaction States and User Feedback Clear feedback during and after transactions enhances user experience and trust in your dApp. Consider using libraries like[ react-toastify](https://github.com/fkhadra/react-toastify) for non-intrusive notifications. Example with Toast Notifications: Install react-toastify ```bash npm install react-toastify ``` Inside the `_app.js` ```javascript import 'react-toastify/dist/ReactToastify.css'; import { ToastContainer } from 'react-toastify'; function MyApp({ Component, pageProps }) { return (

); } export default MyApp; ``` In your WalletContext or Pages ```javascript import { toast } from 'react-toastify'; // Replace alert with toast toast.success("Deposit successful! Transaction hash: " + tx.hash); toast.error("Deposit failed. Check console for details."); ``` The benefits of React Toastify are that it is **non-intrusive** and modal alerts don't block users. It is also customizable, which allows developers to style and position as needed. *** ## Test Write Operations Thorough testing ensures the reliability and trustworthiness of your dApp. Here's how to effectively test your write operations: #### Connect to a Test Network Run your application using the command: ``` npm run dev ``` Your application will be running on **`localhost:3000`** in your web browser. #### Obtain STT from the [Faucet.](https://devnet.somnia.network/) #### Perform Write Operations Deposit Funds: * Navigate to the Home page. * Click the Deposit button. * Confirm the transaction in MetaMask. * Verify that the deposit is reflected in the contract's state. Create a Proposal: * Go to the Create Proposal page. * Enter a proposal description and submit. * Confirm the transaction in MetaMask. * Check that the proposal count increments and the new proposal is retrievable. Vote on a Proposal: * Access the Fetch-Proposal page. * Enter a valid proposal ID and fetch details. * Click Vote YES or Vote NO. * Confirm the transaction in MetaMask. * Verify that vote counts update accordingly. Execute a Proposal: * After a proposal meets the execution deadline, execute it. * Confirm the transaction in MetaMask. * Ensure that the proposal's execution status is updated. * Monitor the browser console for any errors or logs that aid in debugging. *** ## Conclusion and Next Steps In Part 3, you successfully implemented Write Operations in your DAO front end: * **`deposit`**: Allowed users to deposit ETH into the DAO. * **`createProposal`**: Enabled users to submit new proposals. * **`voteOnProposal`**: Provided functionality to cast votes on proposals. * **`executeProposal`**: Facilitated the execution of approved proposals. *** Congratulations! Using Next.js and React Context, you’ve built a fully functional set of Write Operations for your DAO’s front end. This foundation empowers users to interact with your DAO seamlessly, fostering a decentralized, community-driven governance model. Continue refining and expanding your dApp to cater to your community’s evolving needs.
# Building a Simple DEX on Somnia This tutorial will guide you through building a simple Decentralized Exchange (DEX) on Somnia, inspired by Uniswap V2's core mechanics. We'll implement the essential components: Liquidity Pools, Automated Market Maker (AMM) logic, and Token Swapping functionality. {% hint style="success" %} Somnia Mainnet is LIVE. To deploy on Somnia Mainnet, you will need SOMI Tokens. Please refer to the [guide](/get-started/getting-started-for-mainnet) on Moving from Testnet to Mainnet. {% endhint %} ## Prerequisites 1. This guide is not an introduction to Solidity Programming; you are expected to understand Basic Solidity Programming. 2. You can deploy the Smart Contracts using our [Hardhat](/developer/development-frameworks/deploy-with-hardhat) or [Foundry](/developer/development-frameworks/deploy-with-foundry) guides. ## Core Concepts ### Automated Market Maker (AMM) At the core of an AMM is a Liquidity Pool, a Smart Contract that holds reserves of two (or more) tokens (e.g., STT and USDC). Users trade directly against this pool instead of with other users. Most AMMs (like Uniswap v2) use the constant product formula: x⋅y=kx \cdot y = kx⋅y=k * `x` = amount of Token A in the pool * `y` = amount of Token B in the pool * `k` = constant (must remain unchanged) This ensures price adjustment based on supply and demand. If a user wants to buy Token A with Token B: * They send Token B into the Pool * The Smart Contract calculates how much Token A to send out to maintain `x * y = k` * As more Token A is withdrawn, its price increases (slippage) Anyone can deposit an equal value of both tokens into the pool to become a Liquidity Provider (LP) and earn a share of the trading fees (e.g., 0.3%). > **AMMs are fully decentralized with no need for counterparties and are Open and permissionless to use and contribute liquidity.** ### Liquidity Pools Pairs of tokens locked in Smart Contracts that facilitate trading without traditional order books. ## Smart Contract Architecture We'll build three main contracts: 1. `SomniaFactory`: Creates and manages pair contracts 2. `SomniaPair`: Individual liquidity pool for token pairs 3. `SomniaRouter`: User-facing contract for swaps and liquidity management ## Implementation ### ERC-20 Interface First, let's define the ERC-20 interface we'll use.

SomniaPair.sol

```solidity // IERC20.sol pragma solidity ^0.8.0; interface IERC20 { function totalSupply() external view returns (uint256); function balanceOf(address account) external view returns (uint256); function transfer(address recipient, uint256 amount) external returns (bool); function allowance(address owner, address spender) external view returns (uint256); function approve(address spender, uint256 amount) external returns (bool); function transferFrom(address sender, address recipient, uint256 amount) external returns (bool); event Transfer(address indexed from, address indexed to, uint256 value); event Approval(address indexed owner, address indexed spender, uint256 value); } ```

### SomniaPair Contract The pair contract manages individual Liquidity Pools.

SomniaPair.sol

```solidity // SomniaPair.sol pragma solidity ^0.8.0; import "./IERC20.sol"; contract SomniaPair is IERC20 { uint256 public constant MINIMUM_LIQUIDITY = 10**3; address public factory; address public token0; address public token1; uint112 private reserve0; uint112 private reserve1; uint32 private blockTimestampLast; uint256 public kLast; uint256 private unlocked = 1; modifier lock() { require(unlocked == 1, 'LOCKED'); unlocked = 0; _; unlocked = 1; } // ERC-20 Implementation string public constant name = "Somnia LP Token"; string public constant symbol = "SLP"; uint8 public constant decimals = 18; uint256 public totalSupply; mapping(address => uint256) public balanceOf; mapping(address => mapping(address => uint256)) public allowance; event Mint(address indexed sender, uint256 amount0, uint256 amount1); event Burn(address indexed sender, uint256 amount0, uint256 amount1, address indexed to); event Swap( address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to ); event Sync(uint112 reserve0, uint112 reserve1); constructor() { factory = msg.sender; } function initialize(address _token0, address _token1) external { require(msg.sender == factory, 'FORBIDDEN'); token0 = _token0; token1 = _token1; } function getReserves() public view returns (uint112 _reserve0, uint112 _reserve1, uint32 _blockTimestampLast) { _reserve0 = reserve0; _reserve1 = reserve1; _blockTimestampLast = blockTimestampLast; } function _safeTransfer(address token, address to, uint256 value) private { (bool success, bytes memory data) = token.call(abi.encodeWithSelector(IERC20.transfer.selector, to, value)); require(success && (data.length == 0 || abi.decode(data, (bool))), 'TRANSFER_FAILED'); } function _update(uint256 balance0, uint256 balance1, uint112 _reserve0, uint112 _reserve1) private { require(balance0 <= type(uint112).max && balance1 <= type(uint112).max, 'OVERFLOW'); uint32 blockTimestamp = uint32(block.timestamp % 2**32); reserve0 = uint112(balance0); reserve1 = uint112(balance1); blockTimestampLast = blockTimestamp; emit Sync(reserve0, reserve1); } function mint(address to) external lock returns (uint256 liquidity) { (uint112 _reserve0, uint112 _reserve1,) = getReserves(); uint256 balance0 = IERC20(token0).balanceOf(address(this)); uint256 balance1 = IERC20(token1).balanceOf(address(this)); uint256 amount0 = balance0 - _reserve0; uint256 amount1 = balance1 - _reserve1; uint256 _totalSupply = totalSupply; if (_totalSupply == 0) { liquidity = sqrt(amount0 * amount1) - MINIMUM_LIQUIDITY; _mint(address(0), MINIMUM_LIQUIDITY); // permanently lock the first MINIMUM_LIQUIDITY tokens } else { liquidity = min(amount0 * _totalSupply / _reserve0, amount1 * _totalSupply / _reserve1); } require(liquidity > 0, 'INSUFFICIENT_LIQUIDITY_MINTED'); _mint(to, liquidity); _update(balance0, balance1, _reserve0, _reserve1); kLast = uint256(reserve0) * reserve1; emit Mint(msg.sender, amount0, amount1); } function burn(address to) external lock returns (uint256 amount0, uint256 amount1) { (uint112 _reserve0, uint112 _reserve1,) = getReserves(); address _token0 = token0; address _token1 = token1; uint256 balance0 = IERC20(_token0).balanceOf(address(this)); uint256 balance1 = IERC20(_token1).balanceOf(address(this)); uint256 liquidity = balanceOf[address(this)]; uint256 _totalSupply = totalSupply; amount0 = liquidity * balance0 / _totalSupply; amount1 = liquidity * balance1 / _totalSupply; require(amount0 > 0 && amount1 > 0, 'INSUFFICIENT_LIQUIDITY_BURNED'); _burn(address(this), liquidity); _safeTransfer(_token0, to, amount0); _safeTransfer(_token1, to, amount1); balance0 = IERC20(_token0).balanceOf(address(this)); balance1 = IERC20(_token1).balanceOf(address(this)); _update(balance0, balance1, _reserve0, _reserve1); kLast = uint256(reserve0) * reserve1; emit Burn(msg.sender, amount0, amount1, to); } function swap(uint256 amount0Out, uint256 amount1Out, address to, bytes calldata data) external lock { require(amount0Out > 0 || amount1Out > 0, 'INSUFFICIENT_OUTPUT_AMOUNT'); (uint112 _reserve0, uint112 _reserve1,) = getReserves(); require(amount0Out < _reserve0 && amount1Out < _reserve1, 'INSUFFICIENT_LIQUIDITY'); uint256 balance0; uint256 balance1; { address _token0 = token0; address _token1 = token1; require(to != _token0 && to != _token1, 'INVALID_TO'); if (amount0Out > 0) _safeTransfer(_token0, to, amount0Out); if (amount1Out > 0) _safeTransfer(_token1, to, amount1Out); balance0 = IERC20(_token0).balanceOf(address(this)); balance1 = IERC20(_token1).balanceOf(address(this)); } uint256 amount0In = balance0 > _reserve0 - amount0Out ? balance0 - (_reserve0 - amount0Out) : 0; uint256 amount1In = balance1 > _reserve1 - amount1Out ? balance1 - (_reserve1 - amount1Out) : 0; require(amount0In > 0 || amount1In > 0, 'INSUFFICIENT_INPUT_AMOUNT'); { uint256 balance0Adjusted = balance0 * 1000 - amount0In * 3; uint256 balance1Adjusted = balance1 * 1000 - amount1In * 3; require(balance0Adjusted * balance1Adjusted >= uint256(_reserve0) * _reserve1 * 1000**2, 'K'); } _update(balance0, balance1, _reserve0, _reserve1); emit Swap(msg.sender, amount0In, amount1In, amount0Out, amount1Out, to); } // Helper functions function sqrt(uint256 y) internal pure returns (uint256 z) { if (y > 3) { z = y; uint256 x = y / 2 + 1; while (x < z) { z = x; x = (y / x + x) / 2; } } else if (y != 0) { z = 1; } } function min(uint256 x, uint256 y) internal pure returns (uint256 z) { z = x < y ? x : y; } // ERC-20 functions function _mint(address to, uint256 value) internal { totalSupply += value; balanceOf[to] += value; emit Transfer(address(0), to, value); } function _burn(address from, uint256 value) internal { balanceOf[from] -= value; totalSupply -= value; emit Transfer(from, address(0), value); } function approve(address spender, uint256 value) external returns (bool) { allowance[msg.sender][spender] = value; emit Approval(msg.sender, spender, value); return true; } function transfer(address to, uint256 value) external returns (bool) { balanceOf[msg.sender] -= value; balanceOf[to] += value; emit Transfer(msg.sender, to, value); return true; } function transferFrom(address from, address to, uint256 value) external returns (bool) { if (allowance[from][msg.sender] != type(uint256).max) { allowance[from][msg.sender] -= value; } balanceOf[from] -= value; balanceOf[to] += value; emit Transfer(from, to, value); return true; } } ```

### SomniaFactory Contract The factory creates and tracks all pair contracts.

SomniaFactory.sol

```solidity // SomniaFactory.sol pragma solidity ^0.8.0; import "./SomniaPair.sol"; contract SomniaFactory { mapping(address => mapping(address => address)) public getPair; address[] public allPairs; event PairCreated(address indexed token0, address indexed token1, address pair, uint256); function allPairsLength() external view returns (uint256) { return allPairs.length; } function createPair(address tokenA, address tokenB) external returns (address pair) { require(tokenA != tokenB, 'IDENTICAL_ADDRESSES'); (address token0, address token1) = tokenA < tokenB ? (tokenA, tokenB) : (tokenB, tokenA); require(token0 != address(0), 'ZERO_ADDRESS'); require(getPair[token0][token1] == address(0), 'PAIR_EXISTS'); bytes memory bytecode = type(SomniaPair).creationCode; bytes32 salt = keccak256(abi.encodePacked(token0, token1)); assembly { pair := create2(0, add(bytecode, 32), mload(bytecode), salt) } SomniaPair(pair).initialize(token0, token1); getPair[token0][token1] = pair; getPair[token1][token0] = pair; allPairs.push(pair); emit PairCreated(token0, token1, pair, allPairs.length); } } ```

### SomniaRouter Contract The router provides user-friendly functions for swapping and liquidity management.

SomniaRouter.sol

```solidity // SomniaRouter.sol pragma solidity ^0.8.0; import "./IERC20.sol"; import "./SomniaPair.sol"; import "./SomniaFactory.sol"; contract SomniaRouter { address public immutable factory; modifier ensure(uint256 deadline) { require(deadline >= block.timestamp, 'EXPIRED'); _; } constructor(address _factory) { factory = _factory; } // Add liquidity function addLiquidity( address tokenA, address tokenB, uint256 amountADesired, uint256 amountBDesired, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline ) external ensure(deadline) returns (uint256 amountA, uint256 amountB, uint256 liquidity) { (amountA, amountB) = _addLiquidity(tokenA, tokenB, amountADesired, amountBDesired, amountAMin, amountBMin); address pair = pairFor(tokenA, tokenB); _safeTransferFrom(tokenA, msg.sender, pair, amountA); _safeTransferFrom(tokenB, msg.sender, pair, amountB); liquidity = SomniaPair(pair).mint(to); } function _addLiquidity( address tokenA, address tokenB, uint256 amountADesired, uint256 amountBDesired, uint256 amountAMin, uint256 amountBMin ) internal returns (uint256 amountA, uint256 amountB) { if (SomniaFactory(factory).getPair(tokenA, tokenB) == address(0)) { SomniaFactory(factory).createPair(tokenA, tokenB); } (uint256 reserveA, uint256 reserveB) = getReserves(tokenA, tokenB); if (reserveA == 0 && reserveB == 0) { (amountA, amountB) = (amountADesired, amountBDesired); } else { uint256 amountBOptimal = quote(amountADesired, reserveA, reserveB); if (amountBOptimal <= amountBDesired) { require(amountBOptimal >= amountBMin, 'INSUFFICIENT_B_AMOUNT'); (amountA, amountB) = (amountADesired, amountBOptimal); } else { uint256 amountAOptimal = quote(amountBDesired, reserveB, reserveA); assert(amountAOptimal <= amountADesired); require(amountAOptimal >= amountAMin, 'INSUFFICIENT_A_AMOUNT'); (amountA, amountB) = (amountAOptimal, amountBDesired); } } } // Remove liquidity function removeLiquidity( address tokenA, address tokenB, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline ) public ensure(deadline) returns (uint256 amountA, uint256 amountB) { address pair = pairFor(tokenA, tokenB); SomniaPair(pair).transferFrom(msg.sender, pair, liquidity); (uint256 amount0, uint256 amount1) = SomniaPair(pair).burn(to); (address token0,) = sortTokens(tokenA, tokenB); (amountA, amountB) = tokenA == token0 ? (amount0, amount1) : (amount1, amount0); require(amountA >= amountAMin, 'INSUFFICIENT_A_AMOUNT'); require(amountB >= amountBMin, 'INSUFFICIENT_B_AMOUNT'); } // Swap functions function swapExactTokensForTokens( uint256 amountIn, uint256 amountOutMin, address[] calldata path, address to, uint256 deadline ) external ensure(deadline) returns (uint256[] memory amounts) { amounts = getAmountsOut(amountIn, path); require(amounts[amounts.length - 1] >= amountOutMin, 'INSUFFICIENT_OUTPUT_AMOUNT'); _safeTransferFrom( path[0], msg.sender, pairFor(path[0], path[1]), amounts[0] ); _swap(amounts, path, to); } function swapTokensForExactTokens( uint256 amountOut, uint256 amountInMax, address[] calldata path, address to, uint256 deadline ) external ensure(deadline) returns (uint256[] memory amounts) { amounts = getAmountsIn(amountOut, path); require(amounts[0] <= amountInMax, 'EXCESSIVE_INPUT_AMOUNT'); _safeTransferFrom( path[0], msg.sender, pairFor(path[0], path[1]), amounts[0] ); _swap(amounts, path, to); } // Internal functions function _swap(uint256[] memory amounts, address[] memory path, address _to) internal { for (uint256 i; i < path.length - 1; i++) { (address input, address output) = (path[i], path[i + 1]); (address token0,) = sortTokens(input, output); uint256 amountOut = amounts[i + 1]; (uint256 amount0Out, uint256 amount1Out) = input == token0 ? (uint256(0), amountOut) : (amountOut, uint256(0)); address to = i < path.length - 2 ? pairFor(output, path[i + 2]) : _to; SomniaPair(pairFor(input, output)).swap( amount0Out, amount1Out, to, new bytes(0) ); } } // Library functions function sortTokens(address tokenA, address tokenB) internal pure returns (address token0, address token1) { require(tokenA != tokenB, 'IDENTICAL_ADDRESSES'); (token0, token1) = tokenA < tokenB ? (tokenA, tokenB) : (tokenB, tokenA); require(token0 != address(0), 'ZERO_ADDRESS'); } function pairFor(address tokenA, address tokenB) internal view returns (address pair) { (address token0, address token1) = sortTokens(tokenA, tokenB); pair = SomniaFactory(factory).getPair(token0, token1); require(pair != address(0), 'PAIR_DOES_NOT_EXIST'); } function getReserves(address tokenA, address tokenB) internal view returns (uint256 reserveA, uint256 reserveB) { (address token0,) = sortTokens(tokenA, tokenB); (uint256 reserve0, uint256 reserve1,) = SomniaPair(pairFor(tokenA, tokenB)).getReserves(); (reserveA, reserveB) = tokenA == token0 ? (reserve0, reserve1) : (reserve1, reserve0); } function quote(uint256 amountA, uint256 reserveA, uint256 reserveB) internal pure returns (uint256 amountB) { require(amountA > 0, 'INSUFFICIENT_AMOUNT'); require(reserveA > 0 && reserveB > 0, 'INSUFFICIENT_LIQUIDITY'); amountB = amountA * reserveB / reserveA; } function getAmountOut(uint256 amountIn, uint256 reserveIn, uint256 reserveOut) internal pure returns (uint256 amountOut) { require(amountIn > 0, 'INSUFFICIENT_INPUT_AMOUNT'); require(reserveIn > 0 && reserveOut > 0, 'INSUFFICIENT_LIQUIDITY'); uint256 amountInWithFee = amountIn * 997; uint256 numerator = amountInWithFee * reserveOut; uint256 denominator = reserveIn * 1000 + amountInWithFee; amountOut = numerator / denominator; } function getAmountIn(uint256 amountOut, uint256 reserveIn, uint256 reserveOut) internal pure returns (uint256 amountIn) { require(amountOut > 0, 'INSUFFICIENT_OUTPUT_AMOUNT'); require(reserveIn > 0 && reserveOut > 0, 'INSUFFICIENT_LIQUIDITY'); uint256 numerator = reserveIn * amountOut * 1000; uint256 denominator = (reserveOut - amountOut) * 997; amountIn = (numerator / denominator) + 1; } function getAmountsOut(uint256 amountIn, address[] memory path) public view returns (uint256[] memory amounts) { require(path.length >= 2, 'INVALID_PATH'); amounts = new uint256[](path.length); amounts[0] = amountIn; for (uint256 i; i < path.length - 1; i++) { (uint256 reserveIn, uint256 reserveOut) = getReserves(path[i], path[i + 1]); amounts[i + 1] = getAmountOut(amounts[i], reserveIn, reserveOut); } } function getAmountsIn(uint256 amountOut, address[] memory path) public view returns (uint256[] memory amounts) { require(path.length >= 2, 'INVALID_PATH'); amounts = new uint256[](path.length); amounts[amounts.length - 1] = amountOut; for (uint256 i = path.length - 1; i > 0; i--) { (uint256 reserveIn, uint256 reserveOut) = getReserves(path[i - 1], path[i]); amounts[i - 1] = getAmountIn(amounts[i], reserveIn, reserveOut); } } function _safeTransferFrom(address token, address from, address to, uint256 value) private { (bool success, bytes memory data) = token.call(abi.encodeWithSelector(IERC20.transferFrom.selector, from, to, value)); require(success && (data.length == 0 || abi.decode(data, (bool))), 'TRANSFER_FROM_FAILED'); } } ```

You can deploy the Smart Contracts in the order they have been created above. Create `Token A` and `Token B` or, for example, use `wSTT` and `USDC` Token Pairs.\ \ The next step will be to create a Pool Pair for `Token A` and `Token B`. Deploy the Pair and Add Liquidity. Then users will be able to create `SWAP` using the `Router` Smart Contract. ### Usage Example

Add Liquidity

```solidity // Approve router to spend tokens tokenA.approve(router.address, amountA); tokenB.approve(router.address, amountB); // Add liquidity router.addLiquidity( tokenA.address, tokenB.address, amountA, amountB, minAmountA, minAmountB, userAddress, deadline ); ```

Swap Tokens

```solidity // Approve router to spend input token tokenA.approve(router.address, amountIn); // Swap exact tokens for tokens address[] memory path = new address[](2); path[0] = tokenA.address; path[1] = tokenB.address; router.swapExactTokensForTokens( amountIn, minAmountOut, path, userAddress, deadline ); ```

Remove Liquidity

```solidity // Approve router to spend LP tokens pair.approve(router.address, lpTokenAmount); // Remove liquidity router.removeLiquidity( tokenA.address, tokenB.address, lpTokenAmount, minAmountA, minAmountB, userAddress, deadline ); ```

### Test Your DEX Create a test script to verify functionality:

TestDEX.sol

```solidity pragma solidity ^0.8.0; import "./SomniaFactory.sol"; import "./SomniaRouter.sol"; import "./IERC20.sol"; contract TestDEX { SomniaFactory public factory; SomniaRouter public router; constructor() { factory = new SomniaFactory(); router = new SomniaRouter(address(factory)); } function testCreatePair(address tokenA, address tokenB) external returns (address) { return factory.createPair(tokenA, tokenB); } function testAddLiquidity( address tokenA, address tokenB, uint256 amountA, uint256 amountB ) external { IERC20(tokenA).transferFrom(msg.sender, address(this), amountA); IERC20(tokenB).transferFrom(msg.sender, address(this), amountB); IERC20(tokenA).approve(address(router), amountA); IERC20(tokenB).approve(address(router), amountB); router.addLiquidity( tokenA, tokenB, amountA, amountB, 0, 0, msg.sender, block.timestamp + 3600 ); } } ```

## Conclusion This tutorial has walked you through implementing a fully functional decentralized exchange (DEX)on Somnia, demonstrating the core Smart Contract architecture that powers Automated Market Makers - AMM. By building these contracts from scratch, you've gained hands-on experience with the fundamental mechanics of DEXs:\ 1\. How Liquidity Pools maintain token reserves.\ 2\. How the Constant Product Formula enables permissionless trading.\ 3\. How router contracts abstract complex operations into user-friendly interfaces.\ \ The implementation covers essential features including liquidity provision with LP token minting, atomic swaps with built-in slippage protection, and multi-hop routing for indirect trading pairs. While this represents a complete Smart Contract foundation, production deployments would benefit from additional features such as concentrated liquidity (as seen in Uniswap V3), dynamic fee tiers, flash loan functionality, and comprehensive governance mechanisms. The modular architecture we've implemented makes these enhancements straightforward to integrate.\ \ As you continue developing on Somnia, remember that the Smart Contracts presented here are just one layer of a complete DEX ecosystem; You'll need to consider frontend interfaces, liquidity incentives, and integration with other DeFi protocols to create a thriving exchange. Most importantly, ensure thorough testing on Somnia's testnet and seek professional security audits before deploying any contracts handling real value. This foundation provides you with the knowledge and code necessary to contribute to Somnia's DeFi ecosystem, whether by deploying your own DEX or building innovative features on top of existing protocols. # Security # Smart Contract Security 101 Smart contract vulnerabilities can lead to devastating financial losses and compromise user trust. This guide examines three critical vulnerability categories with hands-on examples that demonstrate both vulnerable patterns and secure implementations. Learn to identify and prevent the most critical security vulnerabilities in smart contracts through practical examples. This section covers real attack vectors with vulnerable and secure code implementations, along with comprehensive prevention strategies. What you'll achieve: Recognize vulnerable code patterns, understand attack mechanisms, and learn to implement secure alternatives. ## Prerequisites ✅ Required: * Understanding of Solidity function execution * Basic knowledge of EVM call mechanics ✅ Recommended: * Access to Remix IDE for testing examples * Somnia Testnet setup for deployment testing ## Vulnerability Overview The following table categorizes vulnerabilities by severity and implementation difficulty: | Vulnerability Type | Severity | Frequency | Detection Difficulty | Financial Impact | | ------------------ | -------- | --------- | -------------------- | ---------------- | | Reentrancy | Critical | High | Medium | Very High | | Access Control | Critical | Medium | Low | High | | Integer Overflow | High | Low | Low | Medium | *** ## 1. Reentrancy Vulnerabilities #### Understanding the Attack Reentrancy occurs when a contract calls an external contract before updating its internal state, allowing the external contract to call back and exploit the inconsistent state. #### Vulnerable Implementation Analysis

ReentrancyVulnerable Contract

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.18; /** * @title ReentrancyVulnerable * @notice Classic vulnerable withdraw pattern for tutorial exploitation in Remix. * @dev Demonstrates why updating state after external calls is dangerous. * * WARNING: Use only in local/Remix test environments. Do NOT deploy vulnerable contracts with real funds on mainnet. */ contract ReentrancyVulnerable { mapping(address => uint256) public deposits; event Deposited(address indexed who, uint256 amount); event Withdrawn(address indexed who, uint256 amount); function deposit() external payable { require(msg.value > 0, "zero deposit"); deposits[msg.sender] += msg.value; emit Deposited(msg.sender, msg.value); } function withdraw(uint256 amount) external { require(deposits[msg.sender] >= amount, "insufficient balance"); // INTERACTION before EFFECTS -> vulnerable to reentrancy (bool sent, ) = msg.sender.call{value: amount}(""); require(sent, "transfer failed"); // EFFECTS: update balance after external call -> attacker can re-enter here deposits[msg.sender] -= amount; emit Withdrawn(msg.sender, amount); } function contractBalance() external view returns (uint256) { return address(this).balance; } } ```

Why This Contract Is Vulnerable: * Interaction (external call) occurs before updating internal state. * No reentrancy guard or checks-effects-interactions. * Attackers can re-enter withdraw() during the external call and drain funds. #### Attack Mechanism {% stepper %} {% step %} **Attack contract & setup** Attacker contract: ```solidity contract Attacker { ReentrancyVulnerable target; uint256 public constant ATTACK_AMOUNT = 1 ether; constructor(address _target) { target = ReentrancyVulnerable(_target); } function attack() external payable { require(msg.value >= ATTACK_AMOUNT, "need at least 1 ETH"); target.deposit{value: ATTACK_AMOUNT}(); target.withdraw(ATTACK_AMOUNT); } receive() external payable { if (address(target).balance >= ATTACK_AMOUNT) { target.withdraw(ATTACK_AMOUNT); } } } ``` Initial state example: * Vulnerable contract has 10 ETH from other users * Attacker deposits 1 ETH {% endstep %} {% step %} **First withdraw and reentry** * Attacker calls `target.withdraw(1 ether)`. * Contract sends 1 ETH via `call` to attacker -> triggers attacker's `receive()`. * Because deposits were not updated yet, `deposits[attacker]` still equals 1 ETH. * In `receive()`, attacker calls `target.withdraw(1 ether)` again. {% endstep %} {% step %} **Recursive drain and final impact** * Reentrancy repeats until contract balance < attack amount. * Attacker drains nearly all ETH while only depositing 1 ETH. * Final state: contract drained, attacker profit huge, other users lose funds. {% endstep %} {% endstepper %} #### Secure Implementation

Secure Reentrancy Contract

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.18; contract ReentrancySecure { mapping(address => uint256) private _deposits; uint256 private constant _NOT_ENTERED = 1; uint256 private constant _ENTERED = 2; uint256 private _status = _NOT_ENTERED; event Deposited(address indexed who, uint256 amount); event Withdrawn(address indexed who, uint256 amount); modifier nonReentrant() { require(_status == _NOT_ENTERED, "reentrant"); _status = _ENTERED; _; _status = _NOT_ENTERED; } function deposit() external payable { require(msg.value > 0, "zero deposit"); _deposits[msg.sender] += msg.value; emit Deposited(msg.sender, msg.value); } function withdraw(uint256 amount) external nonReentrant { uint256 bal = _deposits[msg.sender]; require(bal >= amount, "insufficient balance"); // EFFECTS _deposits[msg.sender] = bal - amount; // INTERACTIONS (bool sent, ) = msg.sender.call{value: amount}(""); require(sent, "transfer failed"); emit Withdrawn(msg.sender, amount); } function depositOf(address who) external view returns (uint256) { return _deposits[who]; } function contractBalance() external view returns (uint256) { return address(this).balance; } } ```

This secure contract uses a reentrancy guard to prevent recursive calls: **Key Components:** 1. **Reentrancy Guard Variables:** * `_NOT_ENTERED = 1` and `_ENTERED = 2`: Lock states * `_status`: Tracks if function is currently executing 2. **nonReentrant Modifier:** * Checks if function is already running (`_status == _NOT_ENTERED`) * Sets lock before execution (`_status = _ENTERED`) * Releases lock after completion (`_status = _NOT_ENTERED`) 3. **Secure withdraw() Function:** * Uses `nonReentrant` modifier to block recursive calls * Updates balance BEFORE making external call (checks-effects-interactions pattern) * External call cannot trigger another withdrawal due to the guard **How It Prevents Attacks:** * First call sets `_status = _ENTERED` * Any reentrant call fails the `require(_status == _NOT_ENTERED)` check * Transaction reverts with "reentrant" error * Only one withdrawal per transaction is possible **Security Features:** * Reentrancy protection through state locking * State updates before external calls * Automatic revert on attack attempts Security fixes: * Checks-Effects-Interactions: state updated before external calls. * Reentrancy guard (mutex) via nonReentrant modifier. * Double protection: both CEI and guard prevent recursive drains. #### Prevention Strategies (summary) | Strategy | Implementation | Effectiveness | Gas Cost | | ---------------------------- | ---------------------------------- | ------------- | -------- | | CEI Pattern | Update state before external calls | High | Low | | Reentrancy Guard | Mutex-style protection | Very High | Medium | | Pull Payment | Users withdraw instead of push | High | Low | | OpenZeppelin ReentrancyGuard | Battle-tested implementation | Very High | Medium | *** ## 2. Access Control Vulnerabilities #### Understanding the Flaw Poor access control allows unauthorized users to execute privileged functions, leading to complete contract compromise. #### Vulnerable Implementation Analysis

Access Control Vulnerable Contract

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.18; contract AccessControlVulnerable { mapping(bytes32 => mapping(address => bool)) public roles; bytes32 public constant ADMIN = keccak256("ADMIN"); bytes32 public constant WRITER = keccak256("WRITER"); string public data; constructor() { roles[ADMIN][msg.sender] = true; roles[WRITER][msg.sender] = true; } function grantRole(bytes32 role, address account) external { require(account != address(0), "zero account"); require(roles[role][msg.sender], "only role-holder"); roles[role][account] = true; } function revokeRole(bytes32 role, address account) external { require(roles[role][msg.sender], "only role-holder"); roles[role][account] = false; } function write(string calldata newData) external { require(roles[WRITER][msg.sender], "not writer"); data = newData; } function emergencyReset() external { require(roles[ADMIN][msg.sender], "not admin"); data = ""; } function hasRole(bytes32 role, address account) external view returns (bool) { return roles[role][account]; } }solid ```

Critical issues: * Any role-holder can grant the same role to others → role escalation. * No owner/admin separation. * No events emitted for role changes (no audit trail). #### Attack Mechanism {% stepper %} {% step %} **Setup & initial compromise** Initial state: * Deployer has ADMIN and WRITER. * Legitimate user Alice has WRITER. * Attacker Bob has no roles. Attacker compromises Alice or Alice becomes malicious. {% endstep %} {% step %} **Role escalation sequence** * Alice calls `grantRole(WRITER, bob)` → Bob becomes WRITER. * Bob (now a role-holder) calls `grantRole(ADMIN, bob)` if the model allows it. * Because the contract lets role-holders grant roles, escalation to ADMIN can occur. {% endstep %} {% step %} **Final state & impact** * Bob gains ADMIN powers: can grant/revoke roles and perform privileged actions. * No events: attack may be undetected. * Complete contract compromise possible. {% endstep %} {% endstepper %} #### Secure Implementation

Secure Access Control Contract

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.18; contract AccessControlSecure { mapping(bytes32 => mapping(address => bool)) private _roles; bytes32 public constant ADMIN = keccak256("ADMIN"); bytes32 public constant WRITER = keccak256("WRITER"); address public immutable owner; string public data; event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender); event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender); event DataWritten(address indexed sender, string newData); constructor() { owner = msg.sender; _roles[ADMIN][msg.sender] = true; emit RoleGranted(ADMIN, msg.sender, msg.sender); } modifier onlyOwner() { require(msg.sender == owner, "only owner"); _; } modifier onlyAdmin() { require(_roles[ADMIN][msg.sender], "only admin"); _; } function grantRole(bytes32 role, address account) external { require(account != address(0), "zero address"); if (role == ADMIN) { require(msg.sender == owner, "only owner can grant admin"); } else { require(_roles[ADMIN][msg.sender], "only admin can grant"); } if (!_roles[role][account]) { _roles[role][account] = true; emit RoleGranted(role, account, msg.sender); } } function revokeRole(bytes32 role, address account) external { require(account != address(0), "zero address"); if (role == ADMIN) { require(msg.sender == owner, "only owner can revoke admin"); } else { require(_roles[ADMIN][msg.sender], "only admin can revoke"); } if (_roles[role][account]) { _roles[role][account] = false; emit RoleRevoked(role, account, msg.sender); } } function write(string calldata newData) external { require(_roles[WRITER][msg.sender], "not writer"); data = newData; emit DataWritten(msg.sender, newData); } function hasRole(bytes32 role, address account) external view returns (bool) { return _roles[role][account]; } } ```

This secure contract implements proper role hierarchy: **Key Security Features:** 1. **Immutable Owner:** * Owner address cannot be changed after deployment * Only owner can grant/revoke ADMIN roles 2. **Role Hierarchy:** * Owner > Admin > Writer * Only ADMIN can grant WRITER roles * WRITER cannot grant any roles 3. **Secure Role Management:** * Different permissions for granting ADMIN vs other roles * Input validation prevents zero address assignments * Events log all role changes for audit trail **How it prevents attacks:** * WRITER cannot escalate to ADMIN (only owner can grant ADMIN) * Clear separation of permissions * Complete audit trail of all role changes **How Security Works:** **Attack Prevention:** * Alice (WRITER) tries to grant ADMIN to Bob → Fails (only owner can grant ADMIN) * Bob tries to grant himself ADMIN → Fails (only owner can grant ADMIN) * Role escalation is impossible **Legitimate Operations:** * Owner can grant ADMIN roles * ADMIN can grant WRITER roles * All changes are logged with events **Result:** * Clear hierarchy prevents unauthorized escalation * Complete audit trail of all role changes * Attack is blocked by proper permission checks #### Best Practices (summary) | Practice | Purpose | Implementation | | ------------------ | ---------------------------- | ------------------------ | | Role Hierarchy | Prevent privilege escalation | Owner > Admin > User | | Immutable Owner | Prevent ownership takeover | Set in constructor | | Event Logging | Enable audit trails | Emit on all role changes | | Zero Address Check | Prevent accidental locks | Validate addresses | *** ## 3. Integer Overflow/Underflow #### Understanding the Issue Integer overflow/underflow occurs when arithmetic operations exceed the maximum or minimum values for the data type, potentially causing unexpected behavior or security vulnerabilities in financial calculations. #### Vulnerable Implementation Analysis

Integer Overflow Vulnerable Contract

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.18; contract IntegerOverflowVulnerable { mapping(address => uint256) public balance; uint256 public totalSupply; function mint(address to, uint256 amount) external { require(to != address(0), "zero address"); balance[to] += amount; totalSupply += amount; } function transfer(address from, address to, uint256 amount) external { require(to != address(0), "zero address"); // Missing check: require(balance[from] >= amount) balance[from] -= amount; // may revert in 0.8+; would underflow silently pre-0.8 balance[to] += amount; } function batchAdd(address[] calldata recipients, uint256[] calldata amounts) external { require(recipients.length == amounts.length, "length mismatch"); for (uint256 i = 0; i < recipients.length; i++) { require(recipients[i] != address(0), "zero addr in batch"); balance[recipients[i]] += amounts[i]; totalSupply += amounts[i]; } } function balanceOf(address who) external view returns (uint256) { return balance[who]; } } ```

Critical vulnerabilities: * Unchecked addition (overflow) on balances and totalSupply. * Unchecked subtraction (underflow) in transfer. * Batch operations amplify overflow risks. * No access control on minting. #### Attack Mechanisms {% stepper %} {% step %} **Overflow via mint()** Initial state: * totalSupply = expected supply * Attacker computes amount = max\_uint256 - totalSupply + 1 * Calling mint(attacker, amount) causes totalSupply and balance to wrap to 0 (pre-0.8 behavior). * State becomes corrupted. {% endstep %} {% step %} **Underflow via transfer() (pre-0.8 behavior)** * Attacker with 0 balance attempts to transfer a huge amount. * balance\[attacker] -= amount underflows to near max uint256. * Attacker ends up with immense balance. {% endstep %} {% step %} **Batch amplification** * Attacker uses many entries with large but individually safe amounts. * Cumulative additions overflow totalSupply or balances. * Economic model breaks. {% endstep %} {% endstepper %} #### Secure Implementation

Secure Integer Overflow Contract

```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract IntegerOverflowSecure { mapping(address => uint256) public balances; address public owner; uint256 public totalSupply; uint256 public constant MAX_SUPPLY = type(uint256).max; // example constructor() { owner = msg.sender; } modifier onlyOwner() { require(msg.sender == owner, "Not owner"); _; } function mint(address to, uint256 amount) external onlyOwner { require(to != address(0), "Zero address"); require(amount > 0, "Zero amount"); require(balances[to] + amount >= balances[to], "Balance overflow"); require(totalSupply + amount >= totalSupply, "Total supply overflow"); require(totalSupply + amount <= MAX_SUPPLY, "exceeds max supply"); balances[to] += amount; totalSupply += amount; } function transfer(address to, uint256 amount) external { require(to != address(0), "Zero address"); require(amount > 0, "Zero amount"); require(balances[msg.sender] >= amount, "Insufficient balance"); require(balances[to] + amount >= balances[to], "Balance overflow"); balances[msg.sender] -= amount; balances[to] += amount; } function batchAdd(uint256[] calldata amounts) external { uint256 currentBalance = balances[msg.sender]; for (uint256 i = 0; i < amounts.length; i++) { require(currentBalance + amounts[i] >= currentBalance, "Overflow in batch"); currentBalance += amounts[i]; } balances[msg.sender] = currentBalance; } function balanceOf(address account) external view returns (uint256) { return balances[account]; } } ```

This secure contract prevents overflow/underflow attacks: **Key Security Features:** 1. **Overflow/Underflow Checks:** * `require(a + b >= a, "overflow")` - detects addition overflow * `require(a >= b, "underflow")` - prevents subtraction underflow * Checks happen BEFORE arithmetic operations 2. **Supply Cap Enforcement:** * Actually enforces `MAX_SUPPLY` limit * Prevents unlimited token creation 3. **Access Control:** * Only owner can mint tokens * Prevents unauthorized token creation 4. **Input Validation:** * Checks for zero addresses and amounts * Batch size limits prevent gas attacks **How it prevents attacks:** * All arithmetic operations are validated before execution * Supply limits prevent economic manipulation * Access controls prevent unauthorized minting * Batch limits prevent gas-based attacks **How Security Works:** **Attack Prevention:** * Overflow/underflow checks prevent arithmetic attacks * Supply cap enforcement prevents unlimited token creation * Access control restricts minting to owner only * Input validation prevents edge cases **Result:** * All arithmetic operations are safe * Economic model is protected * Attacks are blocked before execution #### Protection Methods (summary) | Method | Solidity Version | Effectiveness | Gas Cost | | ------------------- | ---------------- | ------------- | -------- | | Built-in Protection | 0.8+ | Very High | Low | | SafeMath Library | <0.8 | High | Medium | | Manual Checks | Any | High | Low | | Unchecked Blocks | 0.8+ (when safe) | N/A | Very Low | *** ## Prevention Strategies (Consolidated) 1. Reentrancy Prevention * Primary: Checks-Effects-Interactions pattern * Secondary: Reentrancy guards (e.g., OpenZeppelin ReentrancyGuard) * Additional: Pull payments, limit gas forwarded, prefer transfer() for simple ETH sends 2. Access Control Best Practices * Use battle-tested libraries: OpenZeppelin AccessControl, Ownable * Implement clear role hierarchy and immutable owner * Emit events for role changes and use multisig for critical roles 3. Integer Overflow Protection * Use Solidity 0.8+ (automatic checks) * Add explicit pre-operation checks where appropriate * Enforce supply caps and input limits * For legacy code, use SafeMath 4. General Principles * Defense in depth: stack protections * Fail securely: default to safe state on errors * Principle of least privilege: minimal necessary permissions * Thorough testing and professional audits before mainnet deployment *** ## Testing Vulnerabilities Use these commands and steps to test examples in Remix (manual steps): ```bash # Deploy vulnerable contract in Remix # Deploy attacker contract and execute attack # Observe behavior and balances # Deploy secure version and verify attack fails ``` Verification steps: 1. Deploy vulnerable contract on testnet (Somnia Testnet recommended). 2. Attempt exploit using attacker contract. 3. Observe vulnerability in action. 4. Deploy secure version with protections. 5. Verify exploit fails against secure implementation. You can successfully identify and exploit vulnerabilities in a controlled test environment and verify mitigations on secure contracts. *** ## Common Vulnerability Patterns Red flags in code review: * External calls before state updates * Missing access control modifiers * Unchecked arithmetic operations * Missing input validation * No event emissions for critical actions * Hardcoded addresses or values * Complex inheritance hierarchies * Missing reentrancy protection Security scanning tools: | Tool | Type | Effectiveness | Cost | | --------- | ------------------ | ------------- | ---- | | Slither | Static Analysis | High | Free | | MythX | Comprehensive | Very High | Paid | | Securify | Academic | Medium | Free | | Manticore | Symbolic Execution | High | Free | *** ## Additional Resources * [SWC Registry](https://swcregistry.io/) - Smart Contract Weakness Classification * [Consensys Security Best Practices](https://consensys.github.io/smart-contract-best-practices/) *** ✅ Verification: You can identify vulnerable patterns and understand how attacks work. 🎉 Congratulations! You've mastered the most critical smart contract vulnerabilities, prevention strategies and secure coding patterns. # Audit Checklist This Self-Review Audit Checklist is the mandatory, internal quality assurance process that every smart contract must undergo before deployment to any public or private blockchain environment. Its purpose is to catch common, critical, and complex security vulnerabilities early, significantly reducing the risk of exploits, financial loss, and costly post-deployment fixes. This process consists of two primary phases: a Manual Pre-Deployment Checklist and Automated Static Analysis Tooling. ## Phase 1: Manual Pre-Deployment Checklist The development team must manually review and verify that the contract adheres to the following security, logic, and best-practice requirements. **1.1. Security Vulnerability Checks** | Item | Requirement | Verification Steps | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Reentrancy Protection** | All functions that send Ether or tokens to external addresses must follow the Checks-Effects-Interactions pattern. | Verify that state variables are updated before any external calls are made. Use `transfer`/`send` methods or reentrancy guards where necessary. | | **Access Control** | Critical state-changing functions (e.g., `setOwner`, `pause`, `upgrade`, `mint`) must be guarded by proper access modifiers (e.g., `onlyOwner`, `onlyRole`). | Check that function visibility is correctly set (e.g., `internal`, `external`, `private`). | | **Integer Overflow/Underflow** | All arithmetic operations, especially those based on user input, must be safe. | For Solidity >= 0.8.0, verify the compiler's default overflow checks are not disabled. For older versions, ensure the use of SafeMath libraries. | | **Denial-of-Service (DoS)** | Operations must not iterate over unbounded arrays or map sizes that could be arbitrarily inflated by a malicious user, leading to excessive gas costs. | Check all loops to ensure iteration counts are fixed or restricted. | | **External Call Security** | All interactions with unknown or untrusted external contracts are handled safely. | Ensure that results of external calls are checked and fail gracefully if necessary. Use call wrappers to limit reentrancy risk. | | **Visibility** | State variables and functions intended for internal use must be declared `private` or `internal`. | Review all function and variable declarations for accidental public exposure. | **1.2. Logic and Functional Checks** | Item | Requirement | Verification Steps | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Functional Specification** | The contract logic precisely matches the intended business logic and all requirements documented in the functional specification. | Verify contract against all use cases and edge cases defined in the project scope. | | **State Transitions** | The contract's state (e.g., token balances, operational phase) transitions correctly and predictably. | Trace critical functions (`transfer`, `claim`, `lock`) to ensure state variables update correctly. | | **Error Handling** | All potential failure points are handled gracefully with clear, descriptive error messages. | Ensure that `require()` or `revert()` statements are used everywhere necessary and that custom error codes are defined and leveraged. | | **Event Emission** | All critical state changes and value transfers must emit an appropriate `Event` to allow for off-chain monitoring, indexing, and UI responsiveness. | Verify that an `Event` is emitted for every action that changes a user-facing state. | ## Phase 2: Automated Static Analysis Tools Static analysis is a mandatory, automated review step that must be completed using approved tools before deployment. **2.1. Mandatory Tooling** The following static analysis tools must be executed against the final version of the smart contract code: | Tool | Purpose | Output Review Requirement | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [**Slither**](https://github.com/crytic/slither) | Detects various security vulnerabilities (e.g., reentrancy, unprotected calls, misuses of `msg.sender`) and code optimization issues. | Must be executed with all security and efficiency detectors enabled. | | [**Mythril**](https://github.com/ConsenSysDiligence/mythril) | Performs symbolic execution to find potential execution paths that could lead to vulnerabilities (e.g., integer overflows, assertion failures). | Must be run using its security analysis modes (e.g., full scan, execution path analysis). | | [**Solhint**](https://github.com/protofire/solhint) | Enforces code style and security best practices, ensuring clean and maintainable code. | Must pass all configured security and style rulesets without warnings. | **2.2. Warning Triage and Sign-off**

High/Critical Severity Warnings

Any issue categorized as High or Critical by the static analysis tools must be fixed immediately. The deployment process cannot proceed until these are resolved and the tools run clean.

Medium/Low Severity Warnings

These must be reviewed by a lead developer. They must either be: * Fixed: If the issue is a genuine vulnerability or best practice deviation. * Justified: If the tool's warning is a false positive or the logic is intentionally implemented in that manner, a clear, documented justification must be added to a dedicated "Audit Waivers" log.

Report Retention

The final, clean static analysis reports must be saved and archived as part of the pre-deployment documentation.

{% hint style="success" %} **Congratulations!** You've mastered the audit checklist for both manual and automatic process. Continue to learn prevention strategies and secure coding patterns. {% endhint %} # Node/Infra Security ## Secure RPC Key Management and Environment Configuration for Somnia Developers This comprehensive guide teaches developers how to securely manage RPC keys, private keys, and environment variables when building applications on the Somnia blockchain. If you're deploying smart contracts, building dApps, or integrating with Somnia. Proper security practices are essential to protect your assets and maintain service reliability. By following this tutorial, you'll implement industry-standard security measures with practical code examples that seamlessly integrate into your development workflow. ## Prerequisites Before starting this guide, ensure you have: * Basic knowledge of blockchain development and EVM concepts * Node.js (20+) installed * A code editor (VS Code recommended) * A Somnia wallet with Somnia Token (STT) for testing * Familiarity with environment variables and package managers * Basic understanding of Git and version control ## RPC Key Security Fundamentals RPC (Remote Procedure Call) keys and endpoints allow your application to interact with the blockchain. Using them securely is paramount. A publicly accessible key, especially one with write permissions, can be exploited by an attacker to drain wallets or cause network congestion. #### Using Ankr Provider ❌ **Bad Practice:** ```javascript // Do not call your api Provider directly in your script with the api-keys! // Setup provider AnkrProvider const provider = new AnkrProvider('https://rpc.ankr.com/somnia_testnet/your-private-key'); ``` ✅ **Good Practice:** ```javascript // Create a .env file SOMNIA_ANKR_RPC_URL=https://rpc.ankr.com/somnia_testnet/your-private-key // Use environment variables // Setup provider AnkrProvider const provider = new AnkrProvider(process.env.SOMNIA_ANKR_RPC_URL); ``` ## Environment Variable Management #### Private RPC Endpoints While public endpoints are convenient for basic queries, they are prone to unreliability and congestion during high-traffic events. **Private RPCs are premium services and perform significantly better than the public RPC**, offering more speed and reliability through dedicated connections. ```javascript // Example configuration for private endpoint const config = { testnet: { url: process.env.SOMNIA_TESTNET_RPC_URL, accounts: [process.env.TESTNET_PRIVATE_KEY] } }; ``` #### Environment Variable Best Practices A .env file is a standard way to manage environment-specific configuration: ```bash # .env file SOMNIA_TESTNET_RPC_URL=https://rpc.ankr.com/somnia_testnet/your-private-key TESTNET_PRIVATE_KEY=your_private_key_here NODE_ENV=development ``` #### Never Commit .env Files The .env file should be added to your .gitignore file. ```bash # .gitignore .env .env.local .env.*.local node_modules/ dist/ ``` #### Create Separate Environment Files Use separate configuration files for different environments. ```bash # Project structure ├── .env.example # Template file (safe to commit) ├── .env.development # Development secrets ├── .env.test # Test environment ├── .env.staging # Staging environment └── .env.production # Production secrets (never commit) ``` ```javascript // config/environment.js const dotenv = require('dotenv'); const path = require('path'); const environment = process.env.NODE_ENV || 'development'; const envFile = `.env.${environment}`; dotenv.config({ path: path.resolve(process.cwd(), envFile) }); module.exports = { rpcUrl: process.env.SOMNIA_RPC_URL, privateKey: process.env.PRIVATE_KEY, environment }; ``` #### Reference Keys in Code Always reference environment variables rather than hardcoding sensitive keys. ```javascript // utils/blockchain.js const { ethers } = require('ethers'); const config = require('../config/environment'); class BlockchainService { constructor() { this.provider = new ethers.JsonRpcProvider(config.rpcUrl); this.wallet = new ethers.Wallet(config.privateKey, this.provider); } async getBalance(address) { return await this.provider.getBalance(address); } async sendTransaction(to, value) { const tx = { to, value: ethers.parseEther(value.toString()) }; return await this.wallet.sendTransaction(tx); } } module.exports = BlockchainService; ``` #### Environment Variable Testing for Applications **Note:** This testing approach is designed for application projects only, not system-wide configurations. ```javascript // test-env.js - For application projects only require('dotenv').config(); const testEnvironmentVariables = () => { const requiredVars = [ 'SOMNIA_TESTNET_RPC_URL', 'TESTNET_PRIVATE_KEY' ]; const missing = requiredVars.filter(varName => !process.env[varName]); if (missing.length > 0) { console.error('Missing required environment variables:', missing); process.exit(1); } console.log('All required environment variables are loaded'); }; testEnvironmentVariables(); ``` ## Implementation Examples #### Complete Project Setup ```bash # 1. Initialize project npm init -y npm install ethers dotenv npm install -D nodemon # 2. Create environment template echo "SOMNIA_RPC_URL=https://rpc.ankr.com/somnia_testnet/your-key-here" > .env.example echo "PRIVATE_KEY=your-private-key-here" >> .env.example echo "CONTRACT_ADDRESS=0x..." >> .env.example # 3. Add to .gitignore echo ".env*" >> .gitignore echo "!.env.example" >> .gitignore ``` #### Secure Contract Interaction ```javascript // contracts/SomniaContract.js const { ethers } = require('ethers'); const config = require('../config/environment'); class SomniaContract { constructor(contractAddress, abi) { this.provider = new ethers.JsonRpcProvider(config.rpcUrl); this.wallet = new ethers.Wallet(config.privateKey, this.provider); this.contract = new ethers.Contract(contractAddress, abi, this.wallet); } async safeCall(methodName, ...args) { try { // Estimate gas first const gasEstimate = await this.contract[methodName].estimateGas(...args); // Add 20% buffer const gasLimit = gasEstimate * 120n / 100n; const tx = await this.contract[methodName](...args, { gasLimit }); console.log(`Transaction sent: ${tx.hash}`); const receipt = await tx.wait(); console.log(`Transaction confirmed: ${receipt.transactionHash}`); return receipt; } catch (error) { console.error('Transaction failed:', error.message); throw error; } } } module.exports = SomniaContract; ``` ## RPC Key Management #### IP Whitelisting If your RPC provider supports it, restrict access to your API key by creating an allowlist of trusted IP addresses. ```bash # Example: Configure IP allowlist in your provider dashboard # Allowed IPs: 203.0.113.1, 203.0.113.2 # This ensures only requests from your servers can use the key ``` #### Key Rotation and Expiration Regularly rotate your RPC keys and immediately revoke any that are no longer in use.

Manual key rotation implementation

```javascript // Manual key rotation implementation // Note: RPC providers typically require manual key generation through their dashboard // This implementation helps manage the rotation process once you have new keys const updateEnvironmentVariable = async (key, value) => { // Update .env file or environment configuration const fs = require('fs').promises; const envPath = '.env'; try { let envContent = await fs.readFile(envPath, 'utf8'); const regex = new RegExp(`^${key}=.*$`, 'm'); if (regex.test(envContent)) { envContent = envContent.replace(regex, `${key}=${value}`); } else { envContent += `\n${key}=${value}`; } await fs.writeFile(envPath, envContent); console.log(`Updated ${key} in environment file`); } catch (error) { console.error('Failed to update environment variable:', error); throw error; } }; // Manual key rotation helper const rotateApiKey = async (newKey) => { try { // Validate the new key format if (!newKey || typeof newKey !== 'string') { throw new Error('Invalid API key provided'); } // Store old key for reference const oldKey = process.env.SOMNIA_TESTNET_RPC_URL; console.log('Rotating API key...'); // Update environment variable await updateEnvironmentVariable('SOMNIA_TESTNET_RPC_URL', newKey); console.log('API key rotated successfully'); console.log('Please manually revoke the old key in your RPC provider dashboard'); console.log('Old key (first 10 chars):', oldKey?.substring(0, 10) + '...'); } catch (error) { console.error('Key rotation failed:', error); } }; // Key rotation reminder system const setupRotationReminder = () => { const NINETY_DAYS = 90 * 24 * 60 * 60 * 1000; setInterval(() => { console.log('\n🔑 SECURITY REMINDER: Consider rotating your RPC API keys'); console.log('1. Generate new key in your RPC provider dashboard'); console.log('2. Call rotateApiKey(newKey) with the new key'); console.log('3. Manually revoke old key in provider dashboard\n'); }, NINETY_DAYS); }; // Usage example: // rotateApiKey('https://rpc.ankr.com/somnia_testnet/your-new-private-key'); // setupRotationReminder(); ```

#### Secrets Management for Production For production environments, use a dedicated secrets management platform. ```javascript // AWS Secrets Manager example const AWS = require('aws-sdk'); const secretsManager = new AWS.SecretsManager(); const getRpcKey = async () => { const secret = await secretsManager.getSecretValue({ SecretId: 'somnia-rpc-key' }).promise(); return JSON.parse(secret.SecretString).rpcUrl; }; ``` ## Private Key Security Private keys authorize all transactions on a blockchain and should be protected with the utmost vigilance. #### Secure Key Generation Use reputable tools that follow industry standards for cryptographically random key generation. ```javascript // Example: Secure key generation with ethers.js const { Wallet } = require('ethers'); const { randomBytes } = require('crypto'); // Generate cryptographically secure random wallet const generateSecureWallet = () => { const randomWallet = Wallet.createRandom(); return { address: randomWallet.address, privateKey: randomWallet.privateKey, mnemonic: randomWallet.mnemonic.phrase }; }; ``` #### Access Control Private keys should never be shared. For team access, use multisig wallets or role-based access control. ```javascript // Example: Role-based access pattern class SecureWalletManager { constructor() { this.roles = new Map(); this.permissions = { 'admin': ['deploy', 'transfer', 'read'], 'developer': ['deploy', 'read'], 'viewer': ['read'] }; } assignRole(address, role) { this.roles.set(address, role); } canExecute(address, action) { const role = this.roles.get(address); return this.permissions[role]?.includes(action) || false; } } ``` ## Error Handling and Logging Proper error handling and logging are crucial for maintaining security and debugging issues in production environments. When implementing logging for blockchain applications, it's essential to balance transparency with security, ensuring that sensitive information like private keys and API secrets are never exposed in logs. #### Secure Logging Practices

Secure logging implementation

```javascript // Secure logging implementation const winston = require('winston'); // Create logger with security considerations const logger = winston.createLogger({ level: 'info', format: winston.format.combine( winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json(), // Custom format to redact sensitive information winston.format.printf(({ timestamp, level, message, ...meta }) => { // Redact sensitive data const sanitized = JSON.stringify(meta).replace( /(private_key|api_key|secret)":\s*"[^"]+"/gi, '$1": "[REDACTED]"' ); return `${timestamp} [${level}]: ${message} ${sanitized}`; }) ), transports: [ new winston.transports.File({ filename: 'error.log', level: 'error' }), new winston.transports.File({ filename: 'combined.log' }) ] }); // Error handling for RPC calls const safeRpcCall = async (provider, method, params) => { try { const result = await provider.send(method, params); logger.info('RPC call successful', { method, success: true }); return result; } catch (error) { // Log error without exposing sensitive information logger.error('RPC call failed', { method, error: error.message, code: error.code }); throw new Error(`RPC call failed: ${error.message}`); } }; ```

#### Error Recovery Strategies ```javascript // Implement retry logic with exponential backoff const retryRpcCall = async (provider, method, params, maxRetries = 3) => { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await safeRpcCall(provider, method, params); } catch (error) { if (attempt === maxRetries) { logger.error('Max retries exceeded', { method, attempts: attempt }); throw error; } const delay = Math.pow(2, attempt) * 1000; // Exponential backoff logger.warn('Retrying RPC call', { method, attempt, delay }); await new Promise(resolve => setTimeout(resolve, delay)); } } }; ``` ## Security Checklist * [ ] Store all sensitive keys in environment variables * [ ] Use private RPC endpoints for better performance and reliability * [ ] Implement IP whitelisting where supported * [ ] Set up regular key rotation schedules * [ ] Use hardware wallets for high-value operations * [ ] Implement proper error handling and logging * [ ] Never commit secrets to version control * [ ] Use role-based access control for team environments * [ ] Monitor and audit key usage regularly * [ ] Test environment variable loading in application context ## Conclusion By following these security practices, you'll significantly reduce the risk of key compromise and ensure your Somnia blockchain applications operate securely and reliably. Security is an ongoing process, and you should regularly review and update your practices as new threats emerge and best practices evolve. # Responsible Disclosure Policy This page serves as the unified communication hub for **Somnia developers, contributors, and security researchers**. It combines two essential areas: * **Developer Contact and Support:** How to reach the Somnia DevRel and technical teams. * **Responsible Disclosure:** How to report security vulnerabilities, contribute improvements, and participate in the future bounty ecosystem. *** ## Developer Contact and Support The Somnia developer community operates across several communication channels to provide quick technical assistance, feedback exchange, and support for integrations or bug reports. #### Active Support Channels * **Telegram (DevRel Team):** * [@emreyeth](https://t.me/emreyeth) * [@PromiseGameFi](https://t.me/PromiseGameFi) * [@emmaodia](https://t.me/emmaodia) * **Discord:** * Join the official [Somnia ](https://discord.gg/somnia)server. * For technical questions, use the `#dev-support` or `#dev-chat` channel. * To report issues privately, open a **support ticket** under “Bug Reports” * **Email:**\ Send an email to [**developers@somnia.network**](mailto:developers@somnia.network) for official inquiries, integration help, or collaboration requests. {% hint style="info" %} Response time varies based on the request type, but DevRel aims to reply within **24 hours**. {% endhint %} #### Types of Support Requests | Category | Description | Preferred Channel | | ----------------------- | --------------------------------------------- | ---------------------- | | **Integration Help** | RPC, SDK, and Smart Contract setup assistance | Discord / Email | | **Docs Contribution** | Reporting outdated or missing developer docs | GitHub PR / Email | | **Bug Report** | Contract, SDK, or explorer bugs | Discord Ticket / Email | | **Partnership Inquiry** | Technical collaborations or integration ideas | Email | *** ## Responsible Disclosure Somnia encourages ethical researchers and contributors to responsibly disclose vulnerabilities or security risks found in the ecosystem. Even though a formal bounty system is not yet live, this framework ensures findings are handled safely and recognized appropriately. *** ## Technical Disclosure Guidelines All vulnerability reports should follow a clear, reproducible structure for fast triage and validation. #### **Required Report Template** {% code title="Vulnerability Report Template" %} ```markdown # Vulnerability Report — Somnia Network ## Summary Brief description of the issue. ## Impact Potential risks if exploited. ## Steps to Reproduce 1. Step-by-step actions. 2. Include RPC endpoint, contract address, and network (Mainnet or Shannon Testnet). ## Expected vs Actual Behavior Explain the difference in observed vs intended behavior. ## Proof of Concept (PoC) Include transaction hash, minimal code snippet, or call trace. ## Suggested Fix (Optional) Provide insights or improvement recommendations. ## Contact Telegram / Discord handle / Email. ``` {% endcode %}

Example

{% code title="Example Vulnerability Report" %} ```markdown # Vulnerability Report — Somnia Bridge Contract ## Summary Bridge contract mishandles token decimals in cross-chain conversion. ## Impact Potential underflow on tokens with decimals < 18. ## Steps to Reproduce 1. Deploy ERC20 with 6 decimals. 2. Execute `bridgeToSomnia(token, 1000000)`. 3. Observe incorrect amount on destination. ## Expected vs Actual Expected: normalized 1 token. Actual: 0.000001 tokens received. ## Suggested Fix Add decimal normalization logic. ## Proof of Concept Testnet Tx: `0x92b...4fe1` ## Contact @emreyeth (Telegram) ``` {% endcode %}

*** ## Contribution Pathways for Developers Somnia invites developers to contribute beyond bug reporting. Follow these pathways to get involved. {% stepper %} {% step %} **Documentation Contributions** * Suggest edits or add missing examples in tutorials. * Create new pages under categories like *Debugging*, *Testing*, or *Security*. {% endstep %} {% step %} **Testing Best Practices** * Always test exploits or stress scenarios on **Shannon Testnet**, not on Mainnet. * Use local forks with Hardhat or Foundry for reproducibility. {% endstep %} {% endstepper %} *** ## Somnia Report Lifecycle {% stepper %} {% step %} **Submission** Researcher submits a report via email, Discord, or Telegram. {% endstep %} {% step %} **Verification** Somnia DevRel reproduces the issue and collects context. {% endstep %} {% step %} **Escalation** Valid issues are passed to Somnia Core Security. {% endstep %} {% step %} **Patch Deployment** Fix rolled out to Shannon Testnet, then Mainnet. (Based on where is it.) {% endstep %} {% step %} **Acknowledgment** Researcher credited publicly in Somnia Docs and Discord. {% endstep %} {% endstepper %} For multi-party vulnerabilities (e.g., involving validators or external oracles), coordinated disclosure will be handled privately. *** ## Ethical Rules {% hint style="warning" %} * Do **not** exploit vulnerabilities on Mainnet. * Do **not** disrupt network services or RPC endpoints. * Do **not** engage in social engineering or phishing. * Always disclose vulnerabilities privately and responsibly. Researchers acting in good faith will **not face any penalties** and will be publicly recognized for their ethical contributions. {% endhint %} *** ## Summary * Use **Telegram, Discord, or Email** to reach Somnia’s DevRel and security teams. * Follow the **Responsible Disclosure template** for structured vulnerability reports. * Contribute improvements via **Pull Requests** or documentation updates. * Future bounty and recognition programs will expand as Somnia Mainnet evolves. # Deployment and Production # Go-Live Checklist This page provides a **checklist for deploying Somnia applications to production (Mainnet)**. It ensures that all necessary environment variables, contract addresses, allowlists, and rollback strategies are correctly configured before launch. {% hint style="warning" %} Never commit secrets to git. Use encrypted secret storage or CI secret managers for production deployments. {% endhint %} *** ### Environment Variables * [ ] Store RPC URLs, private keys, and API keys in `.env` files (never commit to git). * [ ] Define `SOMNIA_RPC_MAINNET` and `SOMNIA_RPC_TESTNET` for switching between environments. * [ ] Configure block explorer API keys (for contract verification). * [ ] Separate `.env.production` vs `.env.development`. * [ ] Double-check secrets with `printenv | grep SOMNIA`. Example `.env.production`: {% code title=".env.production" %} ```bash SOMNIA_RPC_MAINNET=https://api.infra.mainnet.somnia.network/ PRIVATE_KEY=0xabc123... EXPLORER_API_KEY=... ALLOWED_ORIGIN=https://yourapp.com ``` {% endcode %} *** ### Contract Addresses * [ ] Verify all **core Somnia system contracts** (e.g., wrapped SOMI, multicall, registry). * [ ] Update deployed contract addresses in `.env` or config files. * [ ] Confirm that addresses match **Mainnet deployments** (not testnet). * [ ] Cross-check with block explorer for correct bytecode & verification. Example `config/addresses.json`: {% code title="config/addresses.json" %} ```json { "network": "mainnet", "dao": "0x1234...", "token": "0xabcd...", "subgraph": "https://subgraph.somnia.network/dashboard/subgraph/..." } ``` {% endcode %} *** ### Allowlists * [ ] Maintain allowlists for admin roles, multisigs, and privileged addresses. * [ ] Use multisig wallets ([Safe](https://safe.somnia.network/welcome)) for critical roles (owner, pauser, upgrader). * [ ] Double-check allowlist in contracts (no dev/test keys). * [ ] Store allowlist in version control (JSON/YAML). Example `allowlist.json`: {% code title="allowlist.json" %} ```json { "admins": ["0xAdmin1...", "0xAdmin2..."], "oracles": ["0xOracle1..."], "relayers": ["0xRelayer1..."] } ``` {% endcode %} *** ### Rollback Plan Having a clear rollback strategy is essential if something goes wrong during or after deployment. This should include both **technical measures** and **operational procedures**. #### Technical Rollback Steps * [ ] **Pause contracts** – ensure critical contracts implement a `pause()` function for emergencies. * [ ] **Feature flags** – enable/disable risky features without redeployment. * [ ] **Upgradable contracts** – if using proxies, keep previous implementation verified and ready. * [ ] **Role revocation** – remove compromised keys or revoke admin privileges quickly. * [ ] **Migration scripts** – maintain scripts to redeploy or roll forward to a safe version. #### Operational Rollback Steps * [ ] **Communication plan** – inform users immediately via Discord, Twitter, or status page. * [ ] **Validator coordination** – notify Somnia infra providers/validators in case of critical incidents. * [ ] **Emergency access** – keep a secure list of multisig signers available for urgent transactions. * [ ] **Data backups** – keep copies of config files, [subgraph](https://subgraph.somnia.network/) schemas, and off-chain DBs. * [ ] **Post-mortem process** – document the issue, resolution, and future prevention steps. *** ### Best Practices * Always test on **Shannon Testnet** before mainnet deployment. * Pin dependencies & compiler versions for reproducibility. * Run **audit checklist** (see Smart Contract Security 101). * Monitor deployed contracts with logging & health checks. * Communicate launch windows to your community in advance. # Explorer API Health and Monitoring A comprehensive guide for integrating Somnia Network explorer APIs with production-ready logging and health monitoring systems. This guide demonstrates how to build robust applications on Somnia Network using Blockscout's explorer APIs, implement enterprise-grade logging, and set up comprehensive health monitoring for your dApps. **What You'll Learn** * Somnia Network explorer API integration * Production logging with Winston * Health monitoring systems * Error handling and debugging * Performance optimization ## **Prerequisites** * Node.js 20+ * TypeScript/JavaScript knowledge * Blockchain/EVM concepts * Funded Somnia wallet * REST API experience ## **Explorer Endpoints** Somnia Network uses Blockscout as its blockchain explorer infrastructure: | Network | Explorer URL | API Endpoint | | ----------- | ----------------------------------------- | ------------ | | **Testnet** | | `/api` | | **Mainnet** | | `/api` | ### **Available APIs** Blockscout provides multiple API interfaces: * **REST API** - Primary interface for UI operations * **RPC API** - Etherscan-compatible endpoints * **ETH RPC API** - Standard [JSON-RPC methods](/developer/json-rpc-api) * **GraphQL** - Advanced querying capabilities ## Quick Start Initialize your Somnia integration project: ```bash mkdir somnia-explorer-integration cd somnia-explorer-integration npm init -y ``` ### **Dependencies** Install required packages: ```bash # Core dependencies npm install axios winston express helmet cors dotenv ethers # Development dependencies npm install --save-dev @types/node typescript ts-node nodemon @types/express @types/cors ``` ### **Core Dependencies:** * `axios` - Promise-based HTTP client used for making API requests to Somnia Network's Blockscout explorer APIs with automatic request/response logging and error handling * `winston` - Comprehensive logging library used for creating structured JSON logs with timestamps, component-specific loggers (API, explorer, health), and automatic log rotation * `express` - Minimal web framework used for creating health monitoring endpoints and serving the application * `helmet` - Security middleware used for setting HTTP security headers to protect against XSS, clickjacking, and other common web vulnerabilities * `cors` - Cross-Origin Resource Sharing middleware used for enabling secure cross-origin requests from frontend applications * `dotenv` - Environment variable loader used for managing configuration settings and sensitive information like API keys and network settings * `ethers` - Ethereum library used for blockchain interactions, RPC connections, and retrieving network information ### **Project Structure** ```bash mkdir src/{config,services,utils} logs ``` ### **Package Configuration** Update `package.json` with build scripts: ```json { "name": "somnia-explorer-integration", "version": "1.0.0", "description": "Somnia Network explorer integration with logging and health checks", "main": "dist/app.js", "scripts": { "build": "tsc", "start": "node dist/app.js", "dev": "nodemon --exec ts-node src/app.ts", "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": ["somnia", "blockchain", "explorer", "blockscout"], "author": "Your Name", "license": "MIT" } ``` ### Configuration **Network Settings** Create a configuration file for Somnia Network settings to: * Consolidate all Somnia Network endpoints (testnet/mainnet) in one location * Enable automatic environment-based network switching * Provide TypeScript interfaces for type safety * Make it easy to update endpoints without changing multiple files ```typescript // src/config/network.ts export const SOMNIA_CONFIG = { testnet: { name: 'Somnia Testnet', rpcUrl: 'https://dream-rpc.somnia.network', chainId: 50312, explorerUrl: 'https://shannon-explorer.somnia.network', explorerApiUrl: 'https://shannon-explorer.somnia.network/api' }, mainnet: { name: 'Somnia Mainnet', rpcUrl: 'https://somnia-json-rpc.stakely.io', chainId: 5031, explorerUrl: 'https://explorer.somnia.network', explorerApiUrl: 'https://explorer.somnia.network/api' } }; export const getCurrentNetwork = () => { return process.env.NODE_ENV === 'production' ? SOMNIA_CONFIG.mainnet : SOMNIA_CONFIG.testnet; }; ``` ### **Environment Variables** Why create a .env file: * Keeps sensitive information out of source code * Useful when using third-party RPC API Keys * Enables different configurations for development/production environments * Controls which Somnia network to use (testnet/mainnet) via `NODE_ENV` * Allows easy modification of settings without code changes ```bash # .env NODE_ENV=development PORT=3000 LOG_LEVEL=info ``` #### ## API Integration ### **Explorer Service** This service provides comprehensive logging for all API interactions and follows Blockscout's REST API patterns.

src/services/somniaExplorerService.ts

```javascript // src/services/somniaExplorerService.ts import axios, { AxiosInstance } from 'axios'; import { getCurrentNetwork } from '../config/network'; import { logger } from '../utils/logger'; export interface TransactionData { hash: string; blockNumber: number; from: string; to: string; value: string; gasUsed: string; status: string; timestamp: string; } export interface BlockData { number: number; hash: string; timestamp: number; transactions: string[]; gasUsed: string; gasLimit: string; miner: string; } export class SomniaExplorerService { private api: AxiosInstance; private network = getCurrentNetwork(); constructor() { this.api = axios.create({ baseURL: this.network.explorerApiUrl, timeout: 10000, headers: { 'Content-Type': 'application/json', 'User-Agent': 'Somnia-Explorer-Client/1.0', 'Cache-Control': 'no-cache' // Ensure fresh data for health checks } }); // Add request interceptor for comprehensive logging this.api.interceptors.request.use( (config) => { logger.info('Somnia Explorer API Request', { method: config.method?.toUpperCase(), url: config.url, baseURL: config.baseURL, timestamp: new Date().toISOString(), network: this.network.name }); return config; }, (error) => { logger.error('Somnia Explorer API Request Error', { error: error.message, timestamp: new Date().toISOString(), network: this.network.name }); return Promise.reject(error); } ); // Add response interceptor for logging this.api.interceptors.response.use( (response) => { logger.info('Somnia Explorer API Response', { status: response.status, url: response.config.url, responseTime: response.headers['x-response-time'] || 'unknown', timestamp: new Date().toISOString(), network: this.network.name }); return response; }, (error) => { logger.error('Somnia Explorer API Response Error', { status: error.response?.status, statusText: error.response?.statusText, url: error.config?.url, message: error.message, timestamp: new Date().toISOString(), network: this.network.name }); return Promise.reject(error); } ); } async getTransaction(txHash: string): Promise { try { const response = await this.api.get(`/v2/transactions/${txHash}`); logger.info('Successfully retrieved transaction', { txHash, blockNumber: response.data.block, network: this.network.name }); return response.data; } catch (error: any) { logger.error('Failed to fetch transaction', { txHash, error: error.message, network: this.network.name }); return null; } } async getBlock(blockNumber: number): Promise { try { const response = await this.api.get(`/v2/blocks/${blockNumber}`); logger.info('Successfully retrieved block', { blockNumber, hash: response.data.hash, txCount: response.data.tx_count, network: this.network.name }); return response.data; } catch (error: any) { logger.error('Failed to fetch block', { blockNumber, error: error.message, network: this.network.name }); return null; } } async getAddressTransactions(address: string, page = 1, limit = 20): Promise { try { const response = await this.api.get(`/v2/addresses/${address}/transactions`, { params: { page, limit } }); logger.info('Retrieved address transactions', { address, count: response.data.items?.length || 0, page, limit, network: this.network.name }); return response.data.items || []; } catch (error: any) { logger.error('Failed to fetch address transactions', { address, error: error.message, network: this.network.name }); return []; } } } ```

This `SomniaExplorerService` class provides comprehensive logging for all API interactions and follows Blockscout's REST API patterns. The service includes: * **Type-safe interfaces** for transaction and block data * **Axios interceptors** for automatic request/response logging * **Error handling** with detailed logging for debugging * **Network-aware configuration** that adapts to different Somnia environments Tip: The service automatically logs all API requests and responses, making it easy to debug issues and monitor performance. ### Logging System

src/utils/logger.ts

```javascript // src/utils/logger.ts import winston from 'winston'; import path from 'path'; // Custom log format for Somnia applications const somniaLogFormat = winston.format.combine( winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.errors({ stack: true }), winston.format.json(), winston.format.printf(({ timestamp, level, message, ...meta }) => { return JSON.stringify({ timestamp, level, message, service: 'somnia-explorer-client', network: process.env.NODE_ENV === 'production' ? 'mainnet' : 'testnet', ...meta }); }) ); // Create logger instance with Somnia-specific configuration export const logger = winston.createLogger({ level: process.env.LOG_LEVEL || 'info', format: somniaLogFormat, defaultMeta: { service: 'somnia-explorer-integration', version: '1.0.0', chain: 'somnia' }, transports: [ // Console transport for development new winston.transports.Console({ format: winston.format.combine( winston.format.colorize(), winston.format.simple() ) }), // File transport for all logs new winston.transports.File({ filename: path.join('logs', 'somnia-explorer.log'), maxsize: 5242880, // 5MB maxFiles: 5 }), // Separate file for API-specific logs new winston.transports.File({ filename: path.join('logs', 'api-requests.log'), level: 'info', maxsize: 5242880, maxFiles: 3, format: winston.format.combine( winston.format.timestamp(), winston.format.json() ) }), // Separate file for errors new winston.transports.File({ filename: path.join('logs', 'error.log'), level: 'error', maxsize: 5242880, maxFiles: 3 }) ], // Handle uncaught exceptions exceptionHandlers: [ new winston.transports.File({ filename: path.join('logs', 'exceptions.log') }) ], // Handle unhandled promise rejections rejectionHandlers: [ new winston.transports.File({ filename: path.join('logs', 'rejections.log') }) ] }); // Create specialized loggers for different components export const apiLogger = logger.child({ component: 'api' }); export const explorerLogger = logger.child({ component: 'explorer' }); export const healthLogger = logger.child({ component: 'health' }); ```

**Winston Configuration** This Winston configuration provides several enterprise-grade features that make it production-ready: * **Structured JSON logs**: logs are formatted as JSON objects with consistent fields like `timestamp`, `level`, `message`, and `metadata`. This makes it easy to parse logs programmatically, search for specific events, and integrate with log analysis tools like ELK Stack or Splunk. * **File rotation**: Automatically manages log file sizes by creating new files when they reach 5MB and keeping only the 5 most recent files. * **Component-specific loggers**: Creates separate logger instances for different parts of your application (API, Explorer, Health) using `logger.child()`. * **Error tracking with stack traces**: Captures complete error information including stack traces using `winston.format.errors({ stack: true })`. * **Performance metrics**: Logs response times and request metadata, allowing monitoring of API performance. * **Separate log files by purpose**: Different files for general logs, API requests, errors, exceptions, and promise rejections. {% hint style="danger" %} **Warning**: Ensure the `logs` directory exists before starting your application, or Winston will fail to write log files. {% endhint %} ### Usage Examples **Structured Logging Output** ```json { "timestamp": "2024-01-15 10:30:45", "level": "info", "message": "Somnia Explorer API Request", "service": "somnia-explorer-integration", "network": "testnet", "component": "explorer", "method": "GET", "url": "/v2/transactions/0x1234...", "baseURL": "https://shannon-explorer.somnia.network/api", "chain": "somnia" } ``` **API Service Usage** ```typescript // Initialize the explorer service const explorerService = new SomniaExplorerService(); // Get transaction data const txData = await explorerService.getTransaction('0x1234...'); if (txData) { console.log('Transaction found:', txData.hash); } // Get block data const blockData = await explorerService.getBlock(12345); if (blockData) { console.log('Block transactions:', blockData.transactions.length); } // Get address transactions const addressTxs = await explorerService.getAddressTransactions( '0xabcd...', 1, // page 10 // limit ); console.log('Address transactions:', addressTxs.length); ``` ## Troubleshooting

If API requests fail

* Verify Somnia Network explorer endpoints are accessible * Check network connectivity to shannon-explorer.somnia.network or explorer.somnia.network * Ensure correct API endpoint format matches Blockscout v2 schema

If logging doesn't work

* Ensure the logs directory exists: `mkdir logs` * Check file permissions for log files * Verify Winston configuration matches your environment

You've successfully implemented: * **Comprehensive API integration** with the Somnia Explorer using type-safe interfaces * **Enterprise-grade logging** with Winston, including structured JSON output and file rotation * **Error handling and monitoring** for production-ready applications * **Performance tracking** with request/response logging and timing metrics Your application now has robust blockchain data access with proper logging infrastructure that will help you monitor, debug, and maintain your Somnia-based applications in production. {% hint style="success" %} [Sample Project](https://github.com/PromiseGameFi/Somnia-sample-project/tree/main/somnia-explorer-integration) {% endhint %} # Somnia Gas Differences To Ethereum Somnia's gas costs work very differently to Ethereum's. For background: EVM gas fees are designed to approximate the load placed on the blockchain. They are used to charge users in proportion to the system resources they consume. A transaction's gas fee (in ETH or SOMI) is calculated as `number of units of gas * price per unit of gas`. The number of units of gas is just the sum of the gas costs of the transaction's operations. Because the price of a unit of gas is variable, the absolute cost of an operation in units of gas does not ultimately matter. What matters is the relative difference between operations' gas costs. In other words, if you doubled the gas costs for all operations, and halved the price per unit of gas, there would be no functional change. In regards to determining gas costs, there are two fundamental differences between Ethereum and Somnia: 1. Somnia's architecture and implementation has drastically reduced the real-world performance cost of most EVM operations, but not all. A few operations, such as third-party library precompiles, are just as performant on Ethereum as on Somnia - both use the same code. This relative difference requires us to adjust the relative gas costs of these operations. We could either reduce the gas costs of all operations that Somnia has improved, or increase the gas costs of all operations that Somnia has *not* improved - the result is equivalent. Somnia does the latter, as it fits better into the Ethereum developer ecosystem. 2. Ethereum charges a flat gas cost to read any existing value from storage for the first time in a transaction. This ends up hitting a database whose latency for this read can vary by multiple orders of magnitude. This gas cost inaccuracy is a big problem when scaling these blockchains, as it requires them to leave massive amounts of unused buffer in their execution budget to account for these unpredictable latencies. Somnia has built a new database, IceDb, that is designed to fix this problem. Only the (rare) reads which actually take a long time have a high gas cost; reading from cached state is far cheaper. These two factors mean that Somnia requires different gas semantics to Ethereum. The differences are detailed in this document. This document covers the number of units of gas each operation costs. Somnia also differs from Ethereum in the *price* charged per unit of gas: heavy, sustained users of the network automatically pay a discounted base gas price, as described in [Sustained Use Gas Discounts](/developer/deployment-and-production/sustained-use-gas-discounts). ## Precompiles These precompiles have flat multiples applied to [the same gas calculation that Ethereum uses](https://www.evm.codes/precompiled). * `ecRecover (0x01)` costs **50** times the Ethereum calculated gas usage. (i.e. **150,000** gas instead of **3000** gas.) * `SHA2-256 (0x02)` costs **50** times the Ethereum calculated gas usage. * `RIPEMD-160 (0x03)` costs **10** times the Ethereum calculated gas usage. * `modexp (0x05)` costs **10** times the Ethereum calculated gas usage. * `ecAdd (0x06)` costs **50** times the Ethereum calculated gas usage. * `ecMul (0x07)` costs **10** times the Ethereum calculated gas usage. * `ecPairing (0x08)` costs **250** times the Ethereum calculated gas usage. * `blake2f (0x09)` costs **10** times the Ethereum calculated gas usage. * `point evaluation (0x0a)` costs **50** times the Ethereum calculated gas usage. BLS operations: * `BLS12_G1ADD (0x0b)` costs **220** times the Ethereum calculated gas usage. * `BLS12_G1MSM (0x0c)` costs **110** times the Ethereum calculated gas usage. * `BLS12_G2ADD (0x0d)` costs **330** times the Ethereum calculated gas usage. * `BLS12_G2MSM (0x0e)` costs **50** times the Ethereum calculated gas usage. * `BLS12_PAIRING_CHECK (0x0f)` costs **50** times the Ethereum calculated gas usage. * `BLS12_MAP_FP_TO_G1 (0x10)` costs **120** times the Ethereum calculated gas usage. * `BLS12_MAP_FP2_TO_G2 (0x11)` costs **50** times the Ethereum calculated gas usage. ## Non-storage EVM operations * `SELFBALANCE` costs **305** gas instead of **5** gas. * `KECCAK256` costs `1250 + 300 * minimum_word_size` gas instead of `30 + 6 * minimum_word_size` gas. * `ADDMOD` costs **358** gas instead of **8** gas. * `MULMOD` costs **358** gas instead of **8** gas. ## Storage EVM operations Ethereum uses an [access list based gas model](https://www.evm.codes/about#access_list) for all storage operations, to charge extra gas depending on if the value being accessed has already been accessed *in the same transaction*, and if it is creating or deleting that state. As discussed above, Somnia instead charges extra gas based on a more accurate model of the real world latency it takes to read or write the value in question: ### `SLOAD` * If the storage slot key is in the set of most recently accessed **128 million** contract slot keys, **no extra gas is charged** (on top of the static op gas fee, which is **100** gas). * If the key does not exist, the access requires **at least 1,000,000 gas remaining**, but that gas is **not charged**, so there is no extra cost. * Otherwise, the read costs an additional **1,000,000** gas. ### `SSTORE` * If the storage slot key is in the set of most recently accessed **128 million** contract slot keys, **no extra gas is charged** (on top of the static op gas fee, which is **100** gas). * If the key does not exist and is being *written to zero*, the access requires **at least 1,000,000 gas remaining**, but that gas is **not charged**, so there is no extra cost. * If the key does not exist and is being *written to a non-zero value*, the access requires **at least 1,000,000 gas remaining**, but the caller is charged **200,000** gas. * Otherwise, the write costs an additional **1,000,000** gas. ### Account operations The following EVM operations access account state: * `BALANCE` * `EXTCODESIZE` * `EXTCODECOPY` * `EXTCODEHASH` * `CALL` * `CALLCODE` * `DELEGATECALL` * `STATICCALL` * `CREATE` * `CREATE2` * `SELFDESTRUCT` These have an additional storage gas fee (in place of Ethereum's dynamic access list gas fee): * If the account is in the set of most recently accessed **32 million** accounts, **no extra gas is charged**. * If the account does not exist and is being *read*, the access requires **at least 1,000,000 gas remaining**, but that gas is **not charged**, so there is no extra cost. * If the account does not exist and is being *created*, the access requires **at least 1,000,000 gas remaining**, but the caller is charged **400,000** gas for the new account. * Otherwise, the access costs **1,000,000** gas. ## EVM Logs Somnia charges an increased amount of gas for EVM logs due to the historical storage requirements. Ethereum charges: `375 + 375 * topic_count + 8 * size + memory_expansion_cost` gas Somnia charges: `3200 + 5120 * topic_count + 160 * size + memory_expansion_cost` gas To illustrate these changes with the five different EVM log operations: | EVM Op | Ethereum gas | Somnia gas | | -------------------------- | -----------: | ---------: | | LOG0 with 32 bytes of data | 631 | 8,320 | | LOG1 with 32 bytes of data | 1,006 | 13,440 | | LOG2 with 32 bytes of data | 1,381 | 18,560 | | LOG3 with 32 bytes of data | 1,756 | 23,680 | | LOG4 with 32 bytes of data | 2,131 | 28,800 | ## Contract bytecode deployment cost Ethereum charges **200** gas per byte of deployed bytecode. Somnia charges **3125** gas per byte of deployed bytecode. ## EIP-7702 delegation authorisations Ethereum charges **25,000** gas per authorisation in a [Set Code transaction](https://eips.ethereum.org/EIPS/eip-7702). **12,500** gas is refunded if account creation isn't required. Somnia charges **1,570,000** gas per authorisation in a Set Code transaction. **400,000** gas is refunded if account creation isn't required. # Sustained Use Gas Discounts Somnia automatically reduces the base gas price paid by accounts that consistently consume a lot of gas. The more gas you use over a sustained period, the less you pay for each unit of gas. There is nothing to opt into, claim, stake or sign. Discounts are computed by the network from observed gas usage and applied automatically when your transactions execute. ## How the discount is applied A discount is a percentage off the **base gas price only**. Any priority fee you pay is added on top, undiscounted: ``` price charged per gas = base_gas_price * (100 - discount_percent) / 100 + priority_fee ``` Discounts never reach 100% - gas is never free. The discount changes the **price** you pay per unit of gas. It never changes how many units of gas an operation costs, and it does not raise any gas limit. ## How usage is measured Usage is tracked per **sender address** - the `from` of the transaction, which is the account that pays. Gas consumed by contracts you call counts toward your usage, not theirs. Somnia divides time into **epochs**. On mainnet and testnet an epoch is 3000 ledger blocks, which is roughly **5 minutes** of wall-clock time. * **Every epoch, the gas used by each account is tracked.** An account is only recorded for that epoch if it consumed more than ten million gas units in that epoch, and only the 1000 heaviest gas consumers of the epoch are recorded. * **Your discount is derived from your total tracked gas across the most recent 16 epochs** - a rolling window of roughly **80 minutes**. As each epoch passes, the oldest epoch's usage drops out of the window. * That rolling total is compared against a table of tiers. Each tier names a total amount of gas and the discount earned by reaching it; you get the discount of the highest tier your rolling total reaches. Below the lowest tier, your discount is zero. A newly earned discount applies to every transaction you send from the **start of the next epoch**, so it takes effect at the next 5-minute boundary and reflects roughly your last 80 minutes of activity. ### Current tiers The tier table on mainnet: | Gas units used over the rolling window | Discount | | -------------------------------------- | -------- | | 900,000,000 | 70% | | 4,000,000,000 | 90% | At a base gas price of 6 gwei, sustaining those rates costs roughly **100 SOMI** and **430 SOMI** per day on gas at the undiscounted price. Tiers are network configuration and may be retuned over time; the authoritative table is always the live one returned by `getTiers()` (see [Reading discounts on chain](#reading-discounts-on-chain)). ### Which transactions accrue usage | Transaction type | Accrues usage | Receives a discount | | ------------------------------------------------------ | ----------------------------------- | ------------------- | | Ordinary transactions you sign and send | Yes | Yes | | Transactions that revert or run out of gas | Yes - you paid for the gas | Yes | | [Reactivity](/developer/reactivity) handler executions | Yes, to the subscription owner | Yes | | Reactivity subscription deactivations | No - they consume no chargeable gas | n/a | | Protocol-level and zero-gas transactions | No | No | Because a Reactivity subscription owner may be a contract, contract accounts can accrue usage and earn discounts for the handler executions they pay for. ## Keeping and losing a discount Your discount is derived from a rolling window, not from a single epoch, so it is stable across quiet periods. If you stop transacting entirely, your usage ages out gradually and your discount only reaches zero after the full window - 16 epochs, roughly 80 minutes - has passed with no activity. There is no penalty for bursty traffic. Usage accumulates into the window whenever you are busy, and a spike is credited in full. ## What this means for sending transactions {% hint style="warning" %} **You must still submit a `gasPrice` at or above the full, undiscounted base fee.** The discount is applied when your transaction executes, not when it is accepted. {% endhint %} Concretely: * **Transaction admission is undiscounted.** A transaction whose `gasPrice` is below the current base fee is rejected from the mempool, whatever your discount. Keep quoting `eth_gasPrice` (or your wallet's estimate) as normal. * **Balance requirements are undiscounted while pending.** The node reserves `gasPrice * gas` at the full price for in-flight transactions, so you need to be able to cover the undiscounted cost even though you will be charged less. * **You are charged the discounted price.** The saving shows up as a smaller balance deduction, and in `effectiveGasPrice` on the receipt. The practical upshot for a dApp is that no change to your submission logic is needed. Fee estimation, `gasPrice` selection and balance checks all continue to work against the undiscounted base fee; your users simply pay less. ## RPC behaviour No new RPC methods or response fields are involved. Existing fields reflect the discount where - and only where - they describe an actual charge. | Method / field | Reflects the sender's discount? | | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `effectiveGasPrice` on a transaction receipt | **Yes** - the price actually charged. This is the authoritative record. | | `gasPrice` on `eth_getTransactionByHash` / `...ByBlock...` | **Yes** - note this reports the price *charged*, which for a discounted sender is lower than the `gasPrice` you submitted. | | `debug_traceTransaction`, `debug_traceBlockByHash`, `debug_traceBlockByNumber` | **Yes** - replayed with exactly the discount that was charged at the time. | | `eth_call`, `eth_estimateGas`, `eth_createAccessList` against `latest` / `pending` | **Yes** - simulated with the `from` account's current discount. | | `eth_call` or `debug_traceCall` pinned to a **past** block | **No** - historical simulations deliberately run undiscounted. | | `eth_gasPrice` | **No** - the request has no sender, so it returns the network base price. | | `eth_feeHistory`, `block.baseFeePerGas` | **No** - these describe blocks, not senders. | | `eth_maxPriorityFeePerGas` | Unchanged (priority fees are never discounted). | {% hint style="info" %} Because receipts record the discount that was applied, a transaction's `effectiveGasPrice` is reproducible forever, even after the sender's discount has changed or expired. {% endhint %} ## Reading discounts on chain Discounts live in the enshrined `GasDiscounts` contract, at a per-network address. The contract is a UUPS proxy, so the address is stable across upgrades. Look the address up for the network you are on, rather than hardcoding it, using the `somnia_getProtocolParameters` method: ```bash cast rpc somnia_getProtocolParameters '["latest"]' \ --rpc-url https://api.infra.testnet.somnia.network \ | jq -r '.protocol_parameters.gas_discounts_contract_address' ``` The useful read-only views are: | View | Returns | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `getTiers() → (uint256 gasThreshold, uint256 discountBps)[]` | The live tier table. `gasThreshold` is gas used **over the whole rolling window**; thresholds are inclusive, and the highest one you reach applies. | | `getAccountsWithDiscountsForEpoch() → (address[] accounts, uint256[] discountBps, uint256 hotAccountGasThreshold, uint256 maxReportedAccounts)` | The discount set active for the current epoch - only accounts earning a non-zero discount, in ascending address order - plus the per-epoch minimum gas and the number of accounts recorded per epoch. | | `getTrackedAccounts() → (address[] accounts, uint256[] discountBps, uint256[] rollingGasUsed)` | Every account with a live usage window, including those not yet earning a discount, with each window's total. | | `lastReportedEpoch() → uint256` | The epoch of the most recent update. | Discount values in these responses are in basis points, where `10000` is 100% - so a 70% discount reads as `7000`. For example, to fetch the tier table and the current discount set: ```bash PROXY=$(cast rpc somnia_getProtocolParameters '["latest"]' \ --rpc-url $RPC | jq -r '.protocol_parameters.gas_discounts_contract_address') cast call $PROXY "getTiers()((uint256,uint256)[])" --rpc-url $RPC cast call $PROXY "getAccountsWithDiscountsForEpoch()(address[],uint256[],uint256,uint256)" --rpc-url $RPC ``` {% hint style="info" %} There is deliberately no per-account lookup function. To find your own discount, read the full set and filter client-side; both arrays are sorted ascending by address, so a binary search is possible. `rollingGasUsed` from `getTrackedAccounts()` is each window's total **as of the last update**, not aged forward to the current epoch. {% endhint %} The simplest way to confirm a discount is being applied to real transactions is to compare `effectiveGasPrice` on one of your receipts against the block's base gas price. ### Events | Event | Emitted | | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `DiscountSetComputed(uint256 indexed epochReceivingDiscounts, uint256 indexed setCounter, uint256 numDiscountedAccounts)` | Once per epoch, naming the epoch the new discount set applies to. | | `HotAccountsReported(uint256 indexed epoch, address[] accounts, uint256[] gasUsedInEpoch)` | Once per epoch, with that epoch's tracked usage. Addresses are in the payload, not indexed, so you cannot filter by address. | | `TiersUpdated(Tier[] newTiers)` | When the tier table changes. | | `ReportingParametersUpdated(uint256 hotAccountGasThreshold, uint256 maxReportedAccounts)` | When the per-epoch minimum gas or the number of accounts recorded per epoch changes. | Indexing `DiscountSetComputed` and `TiersUpdated` is the cheapest way to keep a dashboard in sync without polling the full set every epoch. ## See also * [Somnia Gas Differences To Ethereum](/developer/deployment-and-production/somnia-gas-differences-to-ethereum) - how Somnia's gas costs per operation differ from Ethereum's * [SOMI coin](/developer/network-info/somi-coin) - denominations and the native gas currency # Ecosystem # Ecosystem Showcase Please visit [Somnia Ecoystem](https://somnia.network/ecosystem) to explore projects within the ecosystem.

# Ecosystem Tools Somnia is built with a robust ecosystem of infrastructure providers that enable developers, projects, and businesses to integrate seamlessly with the network. With Somnia's ecosystem of infrastructure partners, developers have access to scalable RPCs, smart contract tools, oracles, account abstraction, identity solutions, and analytics. Each partner provides critical tooling, APIs, and services to power decentralized applications (dApps) on Somnia. Below is an overview of our key Infrastructure Partners and resources to get started. {% hint style="success" %} **Developers who are deploying Smart Contracts and need Somnia Test Tokens (STT):**\ \ Please join the [Discord](https://discord.com/invite/somnia). Go to the `#dev-chat` channel, tag the Somnia DevRel, `@emreyeth` and request Test Tokens.\ \ You can also join the [Somnia Developer Telegram](https://t.me/+s_oRMnGpOyQ3ODQ0) or use [Faucet](https://testnet.somnia.network/).\ \ You can also email `developers@somnia.foundation` with a brief description of what you are building and your GitHub profile. {% endhint %} | Service | Provider | | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [RPC](/developer/deployment-and-production/ecosystem/ecosystem-tools/rpc) | Ankr, Public Node, Stakely, Validation Cloud | | [Oracles](/developer/deployment-and-production/ecosystem/ecosystem-tools/oracles) | DIA | | [Subgraphs](/developer/deployment-and-production/ecosystem/ecosystem-tools/subgraphs) | Protofire, Ormi | | [Wallet Provider](/developer/deployment-and-production/ecosystem/ecosystem-tools/wallet-providers) | Privy, Thirdweb | | [Safes](/developer/deployment-and-production/ecosystem/ecosystem-tools/safes) | Palmera DAO | | [Explorers](/developer/deployment-and-production/ecosystem/ecosystem-tools/explorers) | Block Scout | | [SDKs](/developer/deployment-and-production/ecosystem/ecosystem-tools/sdks) | Sequence, Thirdweb | | [On Ramps](/developer/deployment-and-production/ecosystem/ecosystem-tools/on-ramps) | Banxa | | [APIs](/developer/deployment-and-production/ecosystem/ecosystem-tools/apis) | Ormi | | [Account Abstraction](/developer/deployment-and-production/ecosystem/ecosystem-tools/account-abstraction) | Pimlico |
# RPC ## [Ankr](https://ankr.com) Ankr provides scalable RPC and API services to interact with the Somnia blockchain efficiently. Developers can use Ankr's enterprise-grade infrastructure to enhance dApp performance. ### Resources * [Ankr RPC for Somnia](https://www.ankr.com/rpc/somnia/) *** ## Public Node Public Node by All Nodes provides fast, free, and privacy-first RPC endpoints for Somnia Network. ### Resources * [Public Node RPC for Somnia](https://somnia.publicnode.com/) *** ## Stakely Stakely is an enterprise-grade infrastructure providerr, trusted by developers and institutions. ### Resources * [Stakely RPC for Somnia](https://somnia-json-rpc.stakely.io/) *** ## Validation Cloud Validation Cloud is the world’s fastest node provider according to Compare Nodes. With 50 million compute units available for use without a credit card and a scale tier that never imposes rate limits, Validation Cloud is built to support the most rigorous, low-latency workloads. Somnia Testnet & Somnia Mainnet are supported. ### Resources * [Link](https://www.validationcloud.io/somnia) # Oracles ## [DIA](https://www.diadata.org/) DIA (Decentralized Information Asset) provides real-time on-chain oracles and trusted price feeds for decentralized applications on Somnia. This is critical for DeFi, lending, and trading protocols. ### Resources * [Somnia Price Oracles](https://docs.diadata.org/use-nexus-product/how-to-dia-nexus-oracles/access-the-oracle/somnia-price-oracles) * [How to Integrate DIA Price Feeds](/developer/building-dapps/oracles/dia-price-feeds) *** ## [Protofire](http://protofire.io/) Protofire deploys custom, compatible oracles using the same data providers and node operators, allowing protocols to connect to their network without modifying Smart Contracts. ### Resources * [Price Feeds](/developer/building-dapps/oracles/protofire-price-feeds) * [Verifiable Randomness Function](/developer/building-dapps/oracles/using-verifiable-randomness-vrf) --- [Next Page](/llms-full.txt/1)

HelloWorld Stream Reader

Schema Information

🛰️ Somnia Data Streams Reader

💬 Somnia Streams Chat (read-only)

💬 Somnia Data Streams Chat

🚀 Somnia Tap Game

Gasless NFT Minting on Somnia

Latest Token Transfers

Welcome to MyToken Dashboard

SomFlip

Somnia Network Balance Demo

Token Balances ({data.resultCount} tokens)

Somnia Network Balance Demo

Token Balances ({data.resultCount} tokens)

{selectedToken}/USD on Somnia

Welcome to MyDAO

Fetch a Proposal

Proposal #{proposalId}

Create Proposal

Fetch a Proposal

Proposal #{proposalId}