# Sunrise **The base layer for Interliquid Networks.** Sunrise is a next-generation Layer 1 blockchain that combines high-throughput data availability with a native liquidity hub. It integrates **Proof of Liquidity (PoL)** and **fee abstraction**, delivering immediate liquidity and flexible gas‑payment options to rollups and application chains. Validators secure the network by staking RISE and/or vRISE. Liquidity providers supply liquidity to pools and earn vRISE and trading fees. Sunrise interoperates with [Rollup and L2 Blockchain](/build/l2-blockchains), allowing developers to adopt Sunrise with minimal integration effort. {% hint style="warning" %} Feature requests or ideas? Open a thread on our [GitHub Discussions](https://github.com/orgs/sunriselayer/discussions). {% endhint %} ## Key Features | Feature | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Proof of Liquidity (PoL)** | Validators secure the network by staking RISE and/or vRISE, aligning security *and* liquidity. Liquidity providers earn vRISE and trading fees. | | **Fee Abstraction** | Any token can pay gas; Sunrise swaps a tiny slice to RISE under the hood. No need to hold multiple tokens for gas. | | **Off‑chain Data Availability** | Large data blobs are propagated and stored off-chain, while only a metadata URI pointing to these erasure-coded data shares are kept on-chain. Optimized for high-throughput rollups. | ## Blazing Fast Data Availability Sunrise's off‑chain data availability design unlocks unmatched throughput and cost‑efficiency without sacrificing on‑chain security. 1. **Off‑chain Erasure Coding**\ → Dramatically cuts validator compute & storage: only coded shards live on chain, full data reconstruction happens off‑chain. 2. **Off‑chain Blob Propagation**\ → Keeps the mempool lightweight and scales to **5 + MB/s**—validators sample availability while nodes fetch or prune blobs on demand. 3. **KZG Commitments**\ → Cryptographic anchors on‑chain enable sub‑second proof verification and instant challenge resolution. ## Data Availability Features Sunrise moves heavy data work off‑chain while keeping on‑chain proofs lean and verifiable. 1. **Off-chain Erasure Encoding**\ Dramatically cuts validator compute & storage: only a metadata URI pointing to these erasure-coded data shares on chain, full data reconstruction happens off‑chain. 2. **Off-chain Storage Integration**\ Utilizing decentralized storage solutions such as IPFS and Arweave, data shards are stored externally. MsgPublishData includes only a metadata URI pointing to these erasure-coded data shares, reducing the on-chain block size requirements for blob transactions and enhancing scalability. See [Data Availability](/learn/sunrise/data-availability) for more details. ## Why build on Sunrise? 1. **Gasless onboarding** – Users don't need a special gas token; your project's token works. 2. **Instant liquidity** – Provide liquidity and earn vRISE gauge rewards and trading fees. 3. **Rollkit / OP‑Stack ready** – Drop‑in adapters for sovereign or Ethereum‑settled rollups. ## Core Modules | Module | Purpose | | ------------------------------------------------------------ | --------------------------------------------------- | | [`x/da`](/learn/sunrise/data-availability) | Data Availlability layer data publication and proof | | [`x/liquiditypool`](/learn/sunrise/liquidity-pool) | PoL pools & Providing liquidity | | [`x/liquidityincentive`](/learn/sunrise/liquidity-incentive) | Gauge Voting for vRISE allocations & Bribes | | [`x/swap`](/learn/sunrise/swap) | AMM router supporting token swap | | [`x/tokenconverter`](/learn/sunrise/token-converter) | Conversion from vRISE to RISE | | [`x/fee`](/learn/sunrise/fee) | fee abstraction & revenue split | | [`x/lockup`](/learn/sunrise/lockup) | Locking of RISE for a certain period | | [`x/shareclass`](/learn/sunrise/shareclass) | Staking RISE to secure the network | ## Revenue Streams * **Tx fees** – Paid by RISE on sending transactions * **Swap fees** – Paid to liquidity providers ## Next Steps | Action | Link | | ---------------------- | ------------------------------------------------------- | | **Install a node** | [Node Setup Guide](/run-a-sunrise-node/types/consensus) | | **Launch a rollup** | [Rollkit Guide](/build/l2-blockchains/rollkit) | | **Become a validator** | [Validator Guide](/build/validators) | | **Join Discord** | [Discord Community](https://discord.gg/sunriselayer) | # Sunrise # Proof of Liquidity Proof of Liquidity (PoL) is a novel Sybil resistance mechanism that utilizes a user's history of providing liquidity as the basis for voting power in the network. This approach aligns economic incentives between validators, liquidity providers, and applications in a more sustainable way than traditional models. ## Core Concepts ### Theoretical Foundation Proof of Liquidity builds upon established DeFi mechanisms while solving key issues: 1. **Beyond ve-Tokenomics**: While ve (vote-escrowed) models like Curve's allow governance participation, PoL integrates liquidity provision directly with network security 2. **Separation of Economic Activities**: PoL uses distinct tokens for consensus security, governance, and transaction fees 3. **Sustainable Incentives**: Unlike traditional DEX inflation models that dilute token value, PoL creates a circular economic system ## Implementation Models ### Berachain Implementation Berachain pioneered the PoL model with a tri-token design: * **$BERA**: Transferable token used for transaction fees and staking (security layer) * **$BGT**: Non-transferable governance token earned by providing liquidity * **$HONEY**: Stablecoin for value transfer within the ecosystem **Key Technical Components:** * Validators stake $BERA to join the consensus set * Block rewards are paid in $BGT based on validator's "boost" percentage * "Boost" is calculated from delegated $BGT from token holders * Validators direct emissions to reward vaults, which distribute $BGT to liquidity providers **Flow of Value:** 1. Validators stake $BERA as security bond 2. Validators receive $BGT rewards for block production 3. Validators direct $BGT rewards to protocol reward vaults 4. Liquidity providers stake receipt tokens in reward vaults to earn $BGT 5. $BGT holders delegate to validators to boost their rewards 6. Protocols provide incentives to validators to attract emissions ### Sunrise Implementation Sunrise builds upon PoL concepts with its own architecture: * **vRISE**: Non-transferable token for staking and governance * **RISE**: Transferable token used as gas and fees **Technical Implementation:** * Liquidity providers in the `x/liquiditypool` module earn vRISE * vRISE holders can stake in the `x/staking` module * Stakers participate in gauge voting through the `x/liquidityincentive` module * Gauge voters decide which pools receive vRISE incentives * Voters earn rewards from pool profits, aligning incentives ## Technical Architecture ### Sunrise Modules The Sunrise implementation consists of several key modules that interact to create the PoL ecosystem: | | Function | | -------------------- | --------------------------------------- | | x/liquiditypool | Core AMM functionality | | x/liquidityincentive | Gauge voting and incentive distribution | | x/swap | Token swap implementation | | x/staking | vRISE staking management | ### Gauge Voting System The gauge voting system is the cornerstone of PoL implementations: 1. **Epoch-Based Voting**: * Voting power is determined by staked vRISE at epoch start * Each epoch spans a predefined number of blocks (configurable via governance) * Votes is cleared each time a new epoch is created 1. **Reward Distribution**: $$ \text{pool rewards} = \text{total rewards} \times \text{pool's voting power} / \text{total voting power of all pools} $$ $$ \text{user rewards} = \text{pool rewards} \times \text{user voting power} / \text{pool's voting power} $$ * Emissions are calculated per block * Distribution based on voted gauge weights and each user's voting power * Rewards are accumulated in the user's position. Can be claimed at any time ### Consensus Implementation Sunrise uses CometBFT (Tendermint) for consensus with the following specifications: * **Maximum Validator Set**: 100 validators * **Block Time**: \~10 seconds * **Validator Selection**: Based on stake weight Future plans include investigating Mysticeti integration to enhance throughput ## Technical Advantages ### Capital Efficiency Unlike traditional PoS where staked tokens are idle, PoL enables: * Active capital utilization through liquidity provision * Dual earning opportunities (staking + liquidity fees) * Lower opportunity cost for network security ### Economic Alignment The technical design creates circular dependencies that align incentives: * Validators need delegated RISE/vRISE to maximize rewards * Applications need validator emissions for liquidity * Users need to provide liquidity to earn governance tokens * The inflation rewards will be distributed with RISE which doesn't lead to the dilution of vRISE (governance token) | Function | Token(s) | Details | | ------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Security | ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) RISE + ![vRISE](/files/Div3EhI0oboVX6ho0wct) vRISE | Both vRISE & RISE can be staked for Consensus | | Governance | ![vRISE](/files/Div3EhI0oboVX6ho0wct) vRISE | vRISE is used for On-chain governance and Gauge Voting | | Security Emissions | ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) RISE | RISE is distributed for stakers as consensus rewards | | LP Emissions | ![vRISE](/files/Div3EhI0oboVX6ho0wct) vRISE | vRISE is distributed for LPs as incentives | | Fee | Any (swapped to [Fee Token](/learn/sunrise/fee)) | RISE is used as a transaction fee | **Legend:**\ ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) = RISE\ ![vRISE](/files/Div3EhI0oboVX6ho0wct) = vRISE > **Note:**\ > In Sunrise, the roles and rewards for each token are clearly defined.\ > This clear separation of functions helps prevent dilution of network security when governance or liquidity rewards are distributed. ### Security Considerations The implementation includes several security measures: * **Slashing Conditions**: Validators risk losing staked assets for misbehavior * **Governance Safeguards**: Weighted voting prevents capture * **Incentive Compatibility**: Economic design disincentivizes attacks ## Performance Considerations PoL implementations must balance several performance factors: * **Epoch Length**: Longer epochs reduce computational overhead but decrease responsiveness * **Validator Set Size**: Larger sets increase decentralization but may impact consensus speed * **Vote Processing**: Batch processing of votes at epoch boundaries to minimize gas costs * **Receipt Token Calculations**: Optimized tracking of liquidity positions and reward distribution ## Future Directions Several technical enhancements are being explored: 1. **Mysticeti Integration**: Investigating the adoption of Mysticeti consensus to enhance throughput 2. **Cross-Chain Gauges**: Enabling voting for liquidity on connected chains 3. **Dynamic Emission Schedules**: Algorithmic adjustment of emissions based on network metrics 4. **Advanced Reward Mechanisms**: More sophisticated reward distribution using bonding curves ## References * [Berachain: Flow of Value](https://blog.berachain.com/blog/flow-of-value-examining-the-differences-between-pos-and-pol-a-case-for-a-new-paradigm-in-sustainable-incentive-alignment-at-the-protocol-layer) * [ve(3,3) Tokenomics](https://andrecronje.medium.com/ve-3-3-44466eaa088b) * [Curve Finance ve-Token Model](https://curve.fi/files/CurveDAO.pdf) * [Mysticeti Consensus](https://sui.io/mysticeti) # Data Availability Sunrise Data Availability Layer is designed for high-throughput data availability, offering enhanced scalability and flexibility for applications. To achieve this, Sunrise adopts off-chain BLOB data and executes Erasure Coding for each Blob data, not entire block data. The `x/da` module provides these features. ## Key Features Sunrise's off‑chain DA design unlocks unmatched throughput and cost‑efficiency without sacrificing on‑chain security. 1. **Off-chain Erasure Encoding**\ Dramatically cuts validator compute & storage: only a metadata URI pointing to these erasure-coded data shares on chain, full data reconstruction happens off‑chain. 2. **Off-chain Storage Integration**\ Utilizing decentralized storage solutions such as IPFS and Arweave, data shards are stored externally. MsgPublishData includes only a metadata URI pointing to these erasure-coded data shares, reducing the on-chain block size requirements for blob transactions and enhancing scalability. ## DA Comparison | | Sunrise | Avail DA | Celestia | EigenDA | Ethereum (EIP-4844) | | ------------------------ | --------------------------------- | --------------------- | --------------------- | ----------------- | --------------------- | | Architecture | L1 with off-chain blobs | L1 Blockchain | L1 Blockchain | DA Service | L1 Blockchain (blobs) | | Throughput | 5+ MB/s | 0.2 MB/s (4MB/block) | 1.33 MB/s (8MB/block) | 15 MB/s | 0.064 MB/s | | Time to Finality | \~4min (7s+240s) | 40 seconds | 6 sec + 10 min | 12 min | 12 min | | Data Storage | Off-chain blobs | On-chain | On-chain | Committee storage | On-chain blobs | | Proof Mechanism | Optimistic with off-chain storage | Validity proof (KZG) | Fraud proof | Validity proof | Validity proof | | Long-term Retrievability | Seamless | Not native | Not native | Not native | Not native | | Cost Model | Fee Abstraction via liquidity | Direct fees | Direct fees | Committee fees | On-chain gas fees | | Consensus | Proof of Liquidity | Babe & Grandpa (NPoS) | Tendermint | N/A | Ghost & Casper | ## Design Overview ### Design patterns of other DA layers 1. **Data Availability Committee** Data Availability Committee (DAC) is the traditional method to construct alternative Data Availability layer with low costs. However, in DAC, it is impossible for clients to verify whether Data Availability attested by the committee is true or false, without downloading entire blob data. 2. **Data Availability Sampling** In the Data Availability layers which adopts Data Availability Sampling (DAS), block data are processed for Erasure Coding. Then clients can verify the Data Availability only with downloading a part of block data, and can verify the inclusion of blob data in the block by using Merkle Tree structure. In typical DAS setup, full nodes must transfer and download transaction data within the mempool. As blob data sizes grow, the network's throughput could be limited by these transaction transfers, creating challenges for applications handling large blob data. ### Sunrise's design To address these problems in DAC and DAS, Sunrise implements the following solutions: 1. **Off-chain Erasure Encoding** Blob data is processed for Erasure Coding in off-chain program, to reduce validator load. 2. **Blob data sharding** Not the entire block data but each blob is processed for Erasure Coding. Clients still can verify the Data Availability for each blob only with repeating to download shards, without downloading entire data. Clients also can verify the inclusion of blob in the block by using Merkle Tree structure. 3. **External Storage** Blob data is stored on decentralized storage platforms like IPFS and Arweave. Rather than containing blob data on-chain, MsgPublishData holds a metadata URI pointing to erasure-coded data shares. ```protobuf message MsgPublishData { option (cosmos.msg.v1.signer) = "sender"; string sender = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; string metadata_uri = 2; uint64 parity_shard_count = 3; repeated bytes shard_double_hashes = 4; string data_source_info = 5; } ``` Data availability is attested with Optimistic way. If enough invalidity challenges is submitted to the Sunrise network, validators will submit Zero-Knowledge Proofs (ZKP) using double-hashed shard data (`shard_double_hashes`), allowing validators to verify the presence of shard data without revealing it. ### Proof Lifecycle Submitted data will have one of the following statuses: * **Created** → **Challenge Period** → **Challenging** → **Verified** / **Rejected** * **Challenge Period:** After submission, data remains in this status for a set period. If enough invalidity challenges are submitted, it moves to Challenging; otherwise, it becomes Verified. * **Challenging:** Validators verify the data and submit proofs. If the validated shard meets the criteria, it becomes Verified; if not, Rejected. * **Verified:** The metadata URI is included in the block and can be referenced externally. * **Rejected:** The data was determined to be invalid and is not included in the block. {% @mermaid/diagram content="graph TD A\[Created] --> B\[Challenge Period] B -->|No challenge| C\[Verified] B -->|Challenged| D\[Challenging] D -->|Valid| C D -->|Invalid| E\[Rejected]" %} ### Flow of proof {% @mermaid/diagram content="%%{init: {"theme": "default", "themeVariables": { "background": "transparent", "primaryColor": "#22223b", "primaryTextColor": "#22223b", "lineColor": "#22223b", "textColor": "#22223b", "actorBorder": "#22223b", "actorTextColor": "#22223b", "sequenceNumberColor": "#22223b", "messageTextColor": "#22223b", "signalColor": "#22223b" }}}%% sequenceDiagram autonumber User->>Publisher Node: blob data Publisher Node->>Publisher Node: Erasure coding Publisher Node->>Decentralized Storage: Upload data shards Publisher Node->>Sunrise: MsgPublishData User->>Sunrise: Fraud Challenge if needed Sunrise->>Validator Set: Start Voting for Challenging Validator Set->>Sunrise: Zero Knowledge Validity Proof" %} ## Zero-Knowledge Proof System ### Terms and Notation * The hash function: $$H$$ * Set of validators: $$V$$ * Set of data shards: $$S\_d$$ * Set of parity shards: $$S\_p$$ * Set of shards: $$S$$ $$ S = S\_d \cup S\_p $$ ### Overview This system verifies the possession of data shard hash $$H(s\_i)$$ without exposing $$H(s\_i)$$ The circuit is for one shard $ s \in S $. 1. Public Inputs $$H\_{\text{public}}^2(s)$$ 2. Private Inputs $$H\_{\text{private}}(s)$$ 3. Circuit Constraints $$ H\_{\text{public}}^2(s) = H(H\_{\text{private}}(s)) $$ ## The condition of Data Availability ### Notations * Replication Factor (Based only on data shards): $$r$$ * Replication Factor (Based on including parity shards): $$r\_p$$ $$ r\_p = r \frac{|S\_d|}{|S\_d| + |S\_p|} $$ * The number of shards each validator is engaged in: $$n$$ $$ n = \text{ceil}\left( r\_p \frac{|S\_d| + |S\_p|}{|V|} \right) = \text{ceil} \left( r\frac{|S\_d|}{|V|} \right) $$ ### Requirements for each shard to prove Data Availability * Set of valid proofs for a shard `s` from validators engaged in this shard: $$Z\_s$$ $$ \frac{|Z\_s|}{r\_p} \ge \frac{2}{3} $$ * Set of shards which satisfy this condition: $$S^\text{available}$$ ### Requirements for tally to prove Data Availability $$ \begin{aligned} \frac{|S^\text{available}|}{|S|} &\ge \frac{|S\_d|}{|S\_d| + |S\_p|} \\ \Rightarrow |S^\text{available}| &\ge |S\_d| \end{aligned} $$ #### Example parameters * 10 validators: $$v\_1 , ..., v\_{10}$$ * 20 shards: $$s\_1, ..., s\_{20}$$ * 10 data shards * 10 parity shards * $$r = 6$$ * $$r\_p = 6 \times \frac{10}{10 + 10} = 3$$ * Each validator submits 6 shards proofs * $$3 \times \frac{20}{10} = 6$$ #### Case A: valid shard `s_1` * Validator $$v\_1$$, $$v\_3$$ and $$v\_9$$ 's proof contain shard $$s\_1$$ and other 5 shards * Validator $$v\_3$$ failed to contain the validity of shard $$s\_1$$ in its proof * However validator $$v\_1$$ and $$v\_9$$ succeeded to contain the validity of shard $$s\_1$$ in its proof, then * $$|Z\_{s\_1}| = 2$$ * It satisfies $$\frac{|Z\_{s\_1}|}{r\_p} \ge \frac{2}{3}$$ #### Case B: invalid shard `s_2` * Validator $$v\_2$$, $$v\_4$$ and $$v\_{10}$$ 's proof contain shard $$s\_2$$ and other 5 shards * Validator $$v\_2$$ and $$v\_4$$ failed to contain the validity of shard $$s\_2$$ in its proof * Only validator $$v\_{10}$$ succeeded to contain the validity of shard $$s\_2$$ in its proof, then * $$|Z\_{s\_2}| = 1$$ * It doesn't satisfy $$\frac{|Z\_{s\_2}|}{r\_p} \ge \frac{2}{3}$$ #### Case X: shard s\_1, s\_3-s\_11 are valid with the condition above * $$|S^\text{available}| = 10$$ * $$|S\_d| = 10$$ * It satisfies $$|S^\text{available}| \ge |S\_d|$$ #### Case Y: Only shard s\_1, s\_3 are valid with the condition above * $$|S^\text{available}| = 2$$ * $$|S\_d| = 10$$ * It doesn't satisfy $$|S^\text{available}| \ge |S\_d|$$ ## Parameters | Param | Default | Units | Description | | ----------------------- | ---------- | ------ | --------------------------------------------------------------------- | | publish\_data\_gas | 1,000,000 | gas | Gas cost for publishing data | | challenge\_threshold | 0.33 | ratio | Threshold of invalidity challenges required to enter challenge period | | replication\_factor | 5.0 | copies | Number of data shard replicas | | slash\_epoch | 120,960 | blocks | Epoch period for slash judgment (approximately 1 week) | | slash\_fault\_threshold | 0.5 | ratio | Threshold of invalid proofs that triggers validator slashing | | slash\_fraction | 0.001 | ratio | Voting power reduction rate during slashing | | challenge\_period | 4 minutes | time | Period for challenges after data published | | proof\_period | 10 minutes | time | Period for submitting proofs after challenge | ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgPublishData: Publish data with metadata URI and shard information * MsgSubmitInvalidity: Report data invalidity for specific indices * MsgSubmitValidityProof: Submit validity proof from a validator * MsgRegisterProofDeputy: Register a proof deputy for a validator * MsgUnregisterProofDeputy: Unregister a proof deputy ## Queries The module provides various query endpoints: * Params: Query module parameters * PublishedData: Get details of published data for a specific metadata URI * AllPublishedData: List all published data * ValidityProof: Get validity proof from a specific validator * AllValidityProofs: List all validity proofs for a specific metadata URI * Invalidity: Get invalidity report for a specific metadata URI and sender * AllInvalidity: List all invalidity reports for a specific metadata URI * ValidatorShardIndices: Get shard indices for a specific validator * ZkpProofThreshold: Get ZKP proof threshold for a specific number of shards * ProofDeputy: Get proof deputy for a specific validator See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/da) for details. # Liquidity Pool The `x/liquiditypool` module implements a concentrated liquidity automated market maker (AMM) mechanism for the Sunrise blockchain. This module enables users to create liquidity pools, add positions with specific price ranges, and earn rewards from trading fees and incentives. ## Key Features 1. **Concentrated Liquidity AMM:** * Follows a similar model to Uniswap V3, allowing liquidity providers to concentrate their assets within specific price ranges. * Improves capital efficiency compared to traditional constant product AMMs. 2. **Position-Based Liquidity:** * Users create positions with defined price ranges (ticks). * Each position has a unique ID and tracks the liquidity provider's contribution. 3. **Fee Generation:** * Positions earn fees from trades that occur within their price range. * Fees are collected in the base and quote denominations of the pool. 4. **`vRISE` Incentives:** * Liquidity providers earn vRISE tokens as additional incentives. * For more information, see [Liquidity Incentive](/learn/sunrise/liquidity-incentive) ## Core Functionality > **Note:** The following section covers advanced topics intended for experienced users or developers. ### Pool Management **Each pool is defined by several parameters:** * `id`: Unique identifier for the pool * `denom_base` & `denom_quote`: The token pair denominations * `fee_rate`: The fee charged on swaps within the pool * `tick_params`: Parameters defining the tick system * `current_tick`, `current_tick_liquidity`, `current_sqrt_price`: Current state variables ### Tick System The tick system is based on a price ratio formula: $$ \mathrm{price}(\mathrm{tick}) = \mathrm{price\_ratio}^{\mathrm{tick} - \mathrm{base\_offset}} $$ In the typical case with `price_ratio = 1.0001` and `base_offset = 0`: $$ \mathrm{price}(\mathrm{tick}) = 1.0001^{\mathrm{tick}} $$ This allows for precise positioning of liquidity within specific price ranges. ## Workflow: Creating and Using Positions > **Note:** The following section covers advanced topics intended for experienced users or developers. {% @mermaid/diagram content="sequenceDiagram participant User participant LiquidityPool as x/liquiditypool Module participant SwapModule as x/swap Module ``` User->>LiquidityPool: MsgCreatePosition LiquidityPool->>User: Return Position ID User->>LiquidityPool: MsgIncreaseLiquidity LiquidityPool->>User: Return new Position ID User->>LiquidityPool: MsgDecreaseLiquidity LiquidityPool->>User: Return Tokens User->>SwapModule: Perform Swap (via x/swap) SwapModule->>LiquidityPool: Use Pool Liquidity LiquidityPool->>LiquidityPool: Collect Fees for Positions LiquidityPool->>User: Send Swapped amount User->>LiquidityPool: MsgClaimRewards LiquidityPool->>User: Transfer Earned Fees & vRISE Incentives ``` " %} ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgCreatePool: Create a new liquidity pool with specified parameters * MsgCreatePosition: Create a position within a price range in a pool * MsgIncreaseLiquidity: Add liquidity to an existing position * MsgDecreaseLiquidity: Remove liquidity from an existing position * MsgClaimRewards: Claim accumulated fees and incentives for positions ## Queries The module provides various query endpoints: * Params: Query module parameters * Pool: Get details of a specific pool * Pools: List all liquidity pools * Position: Get details of a specific position * Positions: List all positions * PoolPositions: List positions in a specific pool * AddressPositions: List positions owned by an address * PositionFees: Get accrued fees for a position * CalculationCreatePosition: Preview position creation * CalculationIncreaseLiquidity: Preview liquidity increase See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/liquiditypool) for details. # Swap The module `x/swap` serves the functionalities to swap tokens with the liquidity in the `x/liquiditypool` module. ## Interface Provider Fee Rewards Any frontend application, wallet, dApp, or protocol that is built on top of the swap module has the ability to earn fees. This incentivizes open, composable infrastructure around the Sunrise AMM. There are 2 important parameters to note: * **interface\_fee\_rate**\ A fee, denoted in percentage, that is taken from the total amount of the swap. * **interface\_provider**\ An address that specifies where the fee will be sent. If no address is provided, no interface fee will be taken. When executing swaps through Sunrise AMM, you can **capture interface fees** by specifying your own fee recipient, maximizing profit per transaction. This function is designed to reward **any entity that facilitates swap volume**—from simple frontends to complex financial protocols. *** ### Swap Message Types There are 2 message types that can be used to specify the amount received or the amount sent. * **MsgSwapExactAmountIn** - Swap tokens with a specified input amount\ This message allows users to swap tokens by defining the exact amount of input tokens they wish to provide. The corresponding output will be calculated based on the specified input. * **MsgSwapExactAmountOut** – Swap tokens with a specified output amount This message enables users to swap tokens by defining the exact amount of output tokens they want to receive. The system will calculate the necessary input amount to achieve the desired output. *** ### Route > **Note:** The following section covers advanced topics intended for experienced users or developers. This module supports Swap Routes with a recursive structure, allowing for complex swaps involving multiple steps, either in sequence (Series) or simultaneously (Parallel). Each step in the route is validated and processed to ensure inputs and outputs are correctly handled. ```typescript message RoutePool { uint64 pool_id = 1; } message RouteSeries { repeated Route routes = 1 [ (gogoproto.nullable) = false, (amino.dont_omitempty) = true ]; } message RouteParallel { repeated Route routes = 1 [ (gogoproto.nullable) = false, (amino.dont_omitempty) = true ]; repeated string weights = 2 [ (cosmos_proto.scalar) = "cosmos.Dec", (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false, (amino.dont_omitempty) = true ]; } message Route { string denom_in = 1; string denom_out = 2; oneof strategy { RoutePool pool = 3; RouteSeries series = 4; RouteParallel parallel = 5; } } ``` *** ### Swap Middleware for ICS20 Token Transfers Swap functionality can be automatically triggered by ICS20 token transfer packets. This is similar to IBC Hooks and can be used by any developers who can use ICS20 in any chain (like Solidity IBC Eureka, CosmWasm on Sei, etc.) to interact with the swap module through IBC middleware. #### Metadata A serialized `PacketMetadata` JSON string needs to be placed in the `memo` field of the ICS20 transfer packet. ```typescript type PacketMetadata = { [namespace: string]: unknown; swap?: SwapMetadata; }; type SwapMetadata = { interface_provider: string; route: Route; forward?: ForwardMetadata; } & ( | { exact_amount_in: { min_amount_out: string; }; } | { exact_amount_out: { amount_out: string; change?: ForwardMetadata; }; } ); type ForwardMetadata = { receiver: string; port: string; channel: string; timeout: string; retries: number; next?: PacketMetadata; }; ``` The `ForwardMetadata` is derived from the [Packet Forward Middleware](https://github.com/cosmos/ibc-apps/tree/main/middleware/packet-forward-middleware). ## **Sequence diagrams** > **Note:** The following section covers advanced topics intended for experienced users or developers. ### Basic Swap Without Forwarding In this scenario, the token transfer occurs, followed by a swap, but there is no forwarding to another chain. {% @mermaid/diagram content="sequenceDiagram autonumber Chain A ->> Sunrise: Transfer token X Sunrise --> Sunrise: recv\_packet Sunrise ->> Sunrise: Swap token X to token Y Sunrise ->> Chain A: ack" %} #### Swap with Forwarding In this scenario, the token is transferred, swapped, and then forwarded to another chain. {% @mermaid/diagram content="sequenceDiagram autonumber Chain A ->> Sunrise: Transfer token X Sunrise --> Sunrise: recv\_packet Sunrise ->> Sunrise: Swap token X to token Y ``` Sunrise ->> Chain B: Forward token Y Chain B --> Chain B: recv_packet Chain B ->> Sunrise: ack Sunrise ->> Chain A: ack" %} ``` #### Swap with Excess Refunded and Forwarding When a swap specifies an exact output amount, any excess input is automatically refunded. After the swap, the remaining tokens are forwarded to another chain. {% @mermaid/diagram content="sequenceDiagram autonumber Chain A ->> Sunrise: Transfer token X Sunrise --> Sunrise: recv\_packet Sunrise ->> Sunrise: Swap token X to token Y ``` Sunrise ->> Chain A: Change token X Sunrise ->> Chain B: Forward token Y Chain A --> Chain A: recv_packet Chain B --> Chain B: recv_packet Chain A ->> Sunrise: ack Chain B ->> Sunrise: ack Sunrise ->> Chain A: ack" %} ``` ### Receiver Address Handling After the swap, even if a subsequent change or transfer fails, the confirmation of "token X transfer" will always succeed. The swapped tokens remain in the receiver's account. ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgSwapExactAmountIn: Swap tokens with a specified input amount * MsgSwapExactAmountOut: Swap tokens with a specified output amount ## Queries The module provides various query endpoints: * Params: Query module parameters * IncomingInFlightPacket: Get details of an incoming in-flight packet * IncomingInFlightPackets: List all incoming in-flight packets * OutgoingInFlightPacket: Get details of an outgoing in-flight packet * OutgoingInFlightPackets: List all outgoing in-flight packets * CalculationSwapExactAmountIn: Preview swap with exact input amount * CalculationSwapExactAmountOut: Preview swap with exact output amount See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/swap) for more details. # Liquidity Incentive The `x/liquidityincentive` module incentivizes liquidity providers by distributing rewards based on their contributions to liquidity pools. It uses an epoch-based reward system and a gauge voting mechanism to allocate rewards dynamically. This module ensures sustainable liquidity provisioning while allowing users to participate in governance through gauge voting. See the [Bribes](/learn/sunrise/liquidity-incentive/bribes) for more information on the bribe feature. ## Key Features 1. **Epoch-Based Reward Distribution**: * Rewards are distributed at the end of each epoch. * Lazy accounting minimizes computational overhead by calculating rewards only when claimed. 2. **Gauge Voting**: * Users can vote on which liquidity pools should receive incentives. * Voting power is determined by **`vRISE`** tokens (non-transferable staking tokens). 3. **Lazy Accounting for Rewards**: * Rewards are tracked using accumulators and distributed only when users claim them. * This reduces the computational load on the network. 4. **Dynamic Incentive Allocation**: * Incentives are allocated based on pool weights (gauges) determined through voting. ## **Core Concepts** ### Epochs > **Note:** The following section covers advanced topics intended for experienced users or developers. * Two epochs exist concurrently: 1. **Past Epoch**: The epoch that has ended. 2. **Current Epoch**: The ongoing epoch. * Each epoch has the following parameters: * **`id`**: The unique epoch ID. * **`start_block`**: The block where the epoch begins. * **`start_time`**: The Unix time where the epoch begins. * **`end_block`**: The block where the epoch ends. * **`gauges`**: A list of gauges (pool weights) for incentive distribution. ### Gauge > **Note:** The following section covers advanced topics intended for experienced users or developers. * A gauge represents a specific liquidity pool's weight in reward allocation. * Parameters: * **`pool_id`**: The ID of the liquidity pool. * **`voting_power`**: The voting power allocated to this pool. ### Lazy Accounting * Rewards are not distributed immediately but are calculated when claimed. * Formula for calculating rewards: $$ \text{ClaimAmount}*{ij} = \frac{\text{PositionUnclaimedAccumulation}*{ij}}{\text{PoolUnclaimedAccumulation}*{i}} \times \text{PoolUnclaimed}*{i} $$ ## Workflow {% @mermaid/diagram content="graph TD A{User A}-->|Provide Liquidity|B((Pool B)) A-->|Register a Bribe|C((Gauge for Pool B)) D{Users}-->|Vote|C C-.->|Distribute the Bribe|D C-.->|Allocate more vRISE|B B-.->|Distribute vRISE incentives|A" %} ### BeginBlocker 1. Transfers a portion of inflation rewards from the Fee Collector account to the **`x/liquidityincentive`** module account. 2. Rewards are converted to **`vRISE`** tokens (non-transferable staking tokens). 3. Rewards are accumulated in each pool's fee accumulator. ### MsgClaimRewards (`x/liquiditypool`) * Users claim rewards by interacting with their positions in liquidity pools. > **Note:**\ > The rewards discussed here are specifically **Gauge Voting rewards, allocated according to your vRISE voting power**.\ > These are distinct from standard LP rewards.\ > You claim Gauge Voting rewards by participating in Gauge Voting with your vRISE, which determines your share of the rewards for each pool per epoch. ## Sequence Diagram: Reward Distribution > **Note:** The following section covers advanced topics intended for experienced users or developers. {% @mermaid/diagram content="sequenceDiagram participant User as Liquidity Provider participant LiquidityPool as x/liquiditypool Module participant IncentiveModule as x/liquidityincentive Module participant Distribution as x/distribution Module ``` User->>LiquidityPool: Provide Liquidity LiquidityPool->>IncentiveModule: Track Position Accumulation IncentiveModule->>Distribution: Transfer Inflation Rewards User->>IncentiveModule: Claim Rewards IncentiveModule->>User: Calculate and Distribute Rewards" %} ``` ## Parameters | Parameter | Default | Units | Description | | ---------------------- | ------- | ------ | --------------------------------------------------- | | epoch\_blocks | 4,320 | blocks | Number of blocks per epoch (approximately 12 days) | | staking\_reward\_ratio | 0.50 | ratio | Ratio of vRISE allocated to staking (50%) | | bribe\_claim\_epochs | 5 | epochs | Number of epochs during which bribes can be claimed | ### Parameter Details 1. **epoch\_blocks** * Defines the length of each epoch in blocks * Default value is approximately 12 days (`DefaultParams().BlocksPerYear/365*12`) * Controls epoch start and end, determining reward distribution timing 2. **staking\_reward\_ratio** * Ratio of newly minted vRISE tokens allocated to staking rewards * Default value is 50% (`math.LegacyNewDecWithPrec(50, 2)`) * Remaining 50% is used for liquidity incentives 3. **bribe\_claim\_epochs** * Defines the period during which bribes can be claimed in epochs * Default value is 5 epochs * Bribes cannot be claimed after this period expires These parameters can be updated through governance. Parameter changes can significantly impact system behavior and should be carefully considered. ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgStartNewEpoch: Start a new epoch * MsgVoteGauge: Vote on pool weights for reward distribution * MsgRegisterBribe: Register a bribe for a specific pool and epoch * MsgClaimBribes: Claim accumulated bribes ## Queries The module provides various query endpoints: * Params: Query module parameters * Epoch: Get details of a specific epoch * Epochs: List all epochs * Vote: Get voting information for a specific address * Votes: List all votes * Bribe: Get details of a specific bribe * Bribes: List all bribes with optional filters * BribeAllocation: Get bribe allocation for a specific address, epoch, and pool * BribeAllocations: List all bribe allocations with optional filters * TallyResult: Get the tally result for the next epoch See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/liquidityincentive) for details. # Gauges Voting ## What is a Gauge? A Gauge in the Sunrise ecosystem is a mechanism that governs the issuance of `vRISE` tokens. Currently, the primary gauge product is the Liquidity Pool system. `vRISE` holders can vote to determine the allocation of newly minted `vRISE` tokens across different gauges. Liquidity pools that attract more voting power will receive a larger share of newly issued vRISE tokens, creating an incentive mechanism that aligns with community preferences. ## How the Voting System Works > **Note:** The following section covers advanced topics intended for experienced users or developers. ### Epoch-Based Voting Gauge weight voting operates on an epoch system: * Each epoch spans a predefined number of blocks (configurable via governance) * Votes are tallied at the beginning of each new epoch * Vote weight is determined by the voter's voting power at epoch starts * Voting is cleared when a new epoch starts {% @mermaid/diagram content="sequenceDiagram participant Voter as vRISE Holder participant Module as Liquidityincentive Module participant Gauges as Liquidity Pool Gauges Voter->>Module: Submit Vote (% allocation per gauge) Note over Module: Store vote preference Module->>Module: Epoch Begins Module->>Module: Tally Votes Module->>Gauges: Distribute vRISE According to Vote Weight Gauges->>Voter: Return Rewards Based on LP Position" %} > **Note:**\ > The rewards discussed here are specifically **Gauge Voting rewards, allocated according to your vRISE voting power**.\ > These are distinct from standard LP rewards.\ > Rewards are accumulated in the user's position and can be claimed at the same time as standard LP rewards in MsgClaimRewards (x/liquiditypool) ### Eligibility Requirements To participate in gauge voting: * **Token Requirement**: You must earn `vRISE` tokens, primarily by providing liquidity to pools * **Voting Power**: Voting Power can be gained by delegating to a validator. * **Tally Timing:** The voting pawer at the start of the epoch is applied. You can submit your vote even before you have voting power. Your voting preferences will be applied based on whatever voting power you have when the next epoch begins. ## How to Vote ### Step 1: Access Your Voting Dashboard Click **My Votes** to begin the voting process. ### Step 2: Select Gauges 1. Click "Select Pool" to open the pool selection interface 2. Choose the pools/gauges you wish to support 3. Your previous voting selections will be automatically loaded if applicable 4. Remove unwanted gauges by clicking the delete button ### Step 3: Allocate Voting Power Specify what percentage of your voting power to allocate to each selected gauge: * **Percentage-Based:** Allocations are specified as percentages rather than absolute amounts because: * Your vRISE balance may fluctuate between epochs * Percentage allocations automatically adjust to your current balance at epoch start * This approach eliminates the need to revote every epoch ### Step 4: Preview and Submit 1. Use the "Preview Vote" feature to see how your current vRISE balance would be distributed 2. Confirm your selections 3. Click Vote to submit your transaction 4. Your vote preferences will be applied to all future epochs until changed ### Step 5: Update (Optional) You can modify your vote at any time: * Your latest voting decision before an epoch begins will be applied * Changes take effect at the next epoch boundary * Simply repeat the voting process to update your preferences See [Liquidity Incentive](/learn/sunrise/liquidity-incentive) for more system details. # Bribes The `x/liquidityincentive` module implements a protocol-level mechanism that allows applications to reward vRISE holders for directing votes to specific pools. This creates an efficient market for liquidity allocation through a bribe-based incentive system. ## Key Features 1. **Protocol-Level Bribes:** * Applications can offer bribes to attract liquidity to specific pools * vRISE holders are incentivized to direct votes to pools with higher bribes * Creates an efficient market for liquidity allocation 2. **Epoch-Based System:** * Bribes are tied to specific epochs * System tracks expired epochs * Unclaimed bribes from expired epochs are processed and sent to fee collector 3. **Weight-Based Distribution:** * Fair allocation based on vote weights * Prevents double claiming * Transparent and verifiable on-chain 4. **Economic Efficiency:** * Creates a market for liquidity allocation * vRISE holders can maximize returns by directing votes * Unclaimed rewards are recycled to fee collector ## Core Functionality > **Note:** The following section covers advanced topics intended for experienced users or developers. ### Bribe Management **Each bribe is defined by several parameters:** * `id`: Unique identifier for the bribe * `epoch_id`: The epoch for which the bribe is valid * `pool_id`: The pool to which the bribe applies * `address`: The sender's address * `amount`: Total amount of the bribe * `claimed_amount`: Amount already claimed by voters ### Bribe Allocation The system tracks how bribes are allocated to voters: * `address`: Voter's address * `epoch_id`: Epoch for which the allocation is valid * `pool_id`: Pool to which the allocation applies * `weight`: Weight of the voter's votes * `claimed_bribe_ids`: List of bribe IDs already claimed *** ## Bribe System Architecture & Flow ### Key Components and Flows #### Bribe Registration * **User registers a bribe** by sending coins to the Bribe Account in the Liquidity Incentive module. * The system **creates a Bribe record** (with unique ID, epoch, pool, amount, and claimed amount). * When the epoch starts, **Bribe allocations** are created for voters based on their vote weights for the pool in that epoch. #### Bribe Claiming * **User initiates a claim** for their bribe allocation. * The system: * Verifies the bribe exists and is valid for the epoch/pool. * Checks the user's allocation and ensures the bribe hasn't been claimed. * Calculates the claimable amount based on the user's vote weight. * Transfers the appropriate amount from the Bribe Account to the user. * Updates the claimed amount and allocation records. #### Fee Processing * Unclaimed bribes from expired epochs are **returned to the Fee Collector**. * Fees are processed: * Transferred from the Fee Collector to the module account. * Converted to the bond denomination if needed. * Distributed to liquidity pools as incentives. #### Cleanup (Unclaimed Bribes) * At the end of each epoch, the system: * Processes expired epochs. * Calculates unclaimed bribe amounts. * Returns unclaimed funds to the Fee Collector. * Cleans up expired bribe and allocation records. #### State Transitions * **Bribe:** Created → Active → Claimed/Expired * **Allocation:** Created → Active → Claimed/Expired * **Funds:** User → Bribe Account → User/Fee Collector *** ### Bribe System Flowchart {% @mermaid/diagram content="flowchart TD User\[User] -->|Register Bribe| BribeAccount\[Bribe Account] BribeAccount -->|Allocate| Allocation\[Bribe Allocation] User -->|Claim| Allocation Allocation -->|Transfer| UserAccount\[User Account] Allocation -->|Unclaimed| FeeCollector\[Fee Collector]" %} **Flow Explanation:** 1. The user registers a bribe, which is deposited into the Bribe Account. 2. The system allocates bribe shares to eligible voters based on their voting weights. 3. Users can claim their allocated bribe rewards from the Bribe Allocation. 4. Claimed rewards are transferred to the user's account. 5. Any unclaimed bribes after the claim period are sent to the Fee Collector for redistribution or burning. *** ## Integration Points The bribe module integrates with several other modules: * Bank module for coin transfers * Account module for address handling * Staking module for vRISE holders * Governance module for parameter updates See [Liquidity Incentive](/learn/sunrise/liquidity-incentive) for more system details. # TokenConverter The `x/tokenconverter` module enables seamless conversion between `vRISE` and `RISE` tokens on the Sunrise blockchain. This module plays a crucial role in the ecosystem by allowing users to convert between the staking token and the fee token while maintaining an equivalent value relationship. ## Key Features 1. **Bidirectional Token Conversion:** * Convert `vRISE` (bond denomination) to `RISE` (fee denomination) and vice versa. * Maintain a 1:1 equivalent value relationship between the tokens. 2. **Permissionless Operation:** * Any user can perform token conversions at any time. * No slippage or fees applied to the conversion process. ## Core Functionality > **Note:** The following section covers advanced topics intended for experienced users or developers. ### Token Conversion The module provides a simple and direct conversion mechanism between `vRISE` and `RISE` tokens: * When converting vRISE to RISE, the module burns vRISE and mints an equivalent amount of RISE. * When converting RISE to vRISE, the module burns RISE and mints an equivalent amount of vRISE. (Not available for users) This process maintains the total economic value in the system while allowing users to hold the token type that best suits their needs. ## Workflow: Token Conversion Process > **Note:** The following section covers advanced topics intended for experienced users or developers. {% @mermaid/diagram content="sequenceDiagram participant User participant TokenConverter as x/tokenconverter Module participant BankKeeper as Bank Module ``` User->>TokenConverter: MsgConvert TokenConverter->>BankKeeper: Burn vRISE Tokens TokenConverter->>BankKeeper: Mint RISE Tokens TokenConverter->>User: Return Converted RISE Tokens" %} ``` ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgConvert: Convert tokens between bond and fee denominations ### MsgConvert Converts tokens between the bond and fee denominations. ```go type MsgConvert struct { Sender string Amount string } ``` ## Benefits 1. **Flexible Token Usage:** * Users can hold tokens in their preferred denomination. * Seamlessly switch between tokens based on intended use (staking vs fees). 2. **Ecosystem Integration:** * Supports the DA Fee Abstraction mechanism by allowing conversion between token types. * Facilitates the operation of other modules in the Sunrise ecosystem. 3. **Simple Design:** * Straightforward conversion with no fees or slippage. * Easy to understand and integrate with applications. See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/tokenconverter) for details. # Fee The `x/fee` module is a core component of the Sunrise blockchain responsible for managing transaction fees. It collects fees in a designated stablecoin (`fee_denom`) and then swaps a portion of these fees into RISE (`burned_denom`) to be burned. This module supports deflationary tokenomics for RISE while maintaining a stable fee system for users. ## Key Features of `x/fee` 1. **Burn Mechanism:** * A portion of collected fees (in `fee_denom`) is swapped to RISE (`burned_denom`) and then burned, reducing the circulating supply. * The burn ratio is determined by the `burn_ratio` parameter (default: 50%). * The swap and burn operations are atomic and verified on-chain. 2. **Fee Denomination (`fee_denom`):** * Specifies the denomination required for transaction fees (default: **`"uusdrise"`**). * Transactions must pay fees in this denomination unless bypassed. * Strict validation of fee denominations is enforced. 3. **Dynamic Parameter Configuration:** * Developers can configure parameters dynamically with validation enforced by the module. * Parameters can be updated through governance proposals. ## Core Functionality ### Fee Collection and Processing **Fee Collection Process:** 1. Fees are collected in `fee_denom` through the `FeeCollector` module account. 2. The system validates: * Only one fee denomination per transaction. * The fee denomination matches the configured `fee_denom`. * The fee amount is valid and non-zero. **Fee Processing Flow:** 1. A portion of the collected fees, determined by `burn_ratio`, is designated for burning. 2. This portion is swapped from `fee_denom` to `burned_denom` via the `x/swap` module. 3. The resulting `burned_denom` tokens are burned from the supply. 4. The remaining `fee_denom` (the portion not designated for burning) stays in the `FeeCollector` account for other protocol uses. ## Parameter Configuration > **Note:** The following section covers advanced topics intended for experienced users or developers. | Parameter | Description | Default Value | Constraints | | -------------- | ------------------------------------------------------- | ------------- | ---------------------------- | | `fee_denom` | Required denomination for transaction fees | `"uusdrise"` | Must be a valid denomination | | `burned_denom` | Denomination to be burnt at the time of fee settlement. | `"urise"` | Must be a valid denomination | | `burn_ratio` | Percentage of fees to burn | `0.5` | Must be between 0 and 1 | ## Workflow: Fee Processing > **Note:** The following section covers advanced topics intended for experienced users or developers. {% @mermaid/diagram content="sequenceDiagram participant User participant FeeModule as x/fee Module participant BankKeeper as Bank Keeper participant SwapModule as x/swap Module participant FeeCollector as Fee Collector participant BribeModule as x/bribe Module ``` User->>FeeModule: Submit Transaction FeeModule->>BankKeeper: Validate Fee Denomination BankKeeper->>FeeCollector: Transfer Fees (in fee_denom) note over FeeModule, SwapModule: Fee Processing FeeModule->>FeeModule: Calculate amount to swap & burn FeeModule->>SwapModule: Swap fee_denom to burned_denom SwapModule-->>FeeModule: Returns burned_denom FeeModule->>BankKeeper: Execute Burn (burned_denom) note over BribeModule, FeeCollector: Unclaimed Bribe Processing BribeModule->>FeeModule: Process Unclaimed Bribes FeeModule->>FeeCollector: Transfer Unclaimed Amounts" %} ``` For more details and implementation specifics, see the [GitHub repository](https://github.com/sunriselayer/sunrise/tree/main/x/fee). # Lockup Account The `x/lockup` module provides functionality for managing token lockups and delegations. This module supports operations such as creating lockup accounts, non-voting delegation, reward claiming, and token transfers. ## Key Features 1. **Lockup Account Management**: * Creation and management of lockup accounts * Setting lockup periods (start and end times) * Tracking of locked tokens 2. **Non-Voting Delegation**: * Delegation of locked tokens to validators * Undelegation functionality * Delegation reward claiming 3. **Token Management**: * Transfer of locked tokens * Querying spendable amounts * Tracking lockup status ## Core Concepts ### Lockup Account > **Note:** The following section covers advanced topics intended for experienced users or developers. A lockup account is defined by the following parameters: * **`address`**: The lockup account address * **`owner`**: The account owner's address * **`id`**: Unique identifier for the lockup account * **`start_time`**: Lockup start time (Unix timestamp) * **`end_time`**: Lockup end time (Unix timestamp) * **`original_locking`**: Original locked amount * **`delegated_free`**: Amount of delegated transfers available * **`delegated_locking`**: Delegated amount of locking amount * **`unbond_entries`**: List of unbonding entries * **`additional_locking`**: Additional locked amount ### Unbonding Entry An unbonding entry is defined by the following parameters: * **`creation_height`**: Block height when the entry was created * **`end_time`**: End time of the entry * **`amount`**: Unbonding amount * **`validator_address`**: Validator's address ## Workflow ### 1. Lockup Account Initialization * User creates a lockup account * Sets lockup period and amount * Specifies account owner ### 2. Non-Voting Delegation * Delegates locked tokens to validators * Executes undelegation * Claims delegation rewards ### 3. Token Transfer * Transfers tokens from lockup account * Verifies spendable amount * Executes transfer ## Sequence Diagram: Lockup Operations {% @mermaid/diagram content="sequenceDiagram participant User as User participant LockupModule as x/lockup Module participant Validator as Validator participant Bank as x/bank Module ``` User->>LockupModule: Create Lockup Account LockupModule->>Bank: Lock Tokens User->>LockupModule: Non-Voting Delegate LockupModule->>Validator: Delegate Tokens Validator->>LockupModule: Generate Rewards User->>LockupModule: Claim Rewards LockupModule->>User: Send Rewards" %} ``` ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgInitLockupAccount: Initialize a new lockup account with specified parameters * MsgNonVotingDelegate: Delegate tokens from a lockup account without voting rights * MsgNonVotingUndelegate: Undelegate tokens from a non-voting delegation * MsgClaimRewards: Claim delegation rewards for a lockup account * MsgSend: Send tokens from a lockup account to another address ## Queries The module provides various query endpoints: * Params: Query module parameters * LockupAccounts: List all lockup accounts for a given owner * LockupAccount: Get details of a specific lockup account * SpendableAmount: Get the spendable amount for a specific lockup account See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/lockup) for details. # Non-Voting Delegation The `x/shareclass` module enables users to delegate their RISE tokens without voting rights and earn staking rewards. This allows participation in staking using RISE tokens even without holding `vRISE` (non-transferable staking tokens). ## Key Features 1. **Non-Voting Delegation with RISE:** * Users can delegate their RISE tokens to validators. * Delegation does not grant voting rights, separating staking rewards from governance participation. 2. **Earning Staking Rewards:** * Delegators earn staking rewards based on their delegated RISE amount. * Provides an alternative way to earn rewards for RISE token holders. 3. **Validator Creation:** * Supports the creation of new validators within the network. ## Core Concepts ### Non-Voting Delegation Users can delegate their RISE tokens to a chosen validator. The module handles the calculation of shares and rewards. This mechanism allows users to benefit from staking rewards without needing to manage `vRISE` tokens or participate in governance directly. ### Reward Calculation Staking rewards are calculated based on the amount of RISE delegated and the reward parameters of the module. Users can claim their accumulated rewards. ## Workflow ### 1. Delegate RISE (Non-Voting) * User sends a `MsgNonVotingDelegate` transaction, specifying the validator and the amount of RISE to delegate. * The module records the delegation and calculates the corresponding shares. ### 2. Claim Rewards * User sends a `MsgClaimRewards` transaction to claim their accumulated staking rewards for a specific validator. * The module transfers the rewards to the user's account. ### 3. Undelegate RISE (Non-Voting) * User sends a `MsgNonVotingUndelegate` transaction to withdraw their delegated RISE. * The module processes the undelegation request, and the tokens become available after an unbonding period. ### 4. Create Validator (Optional) * A user can send a `MsgCreateValidator` transaction to register a new validator node on the network. ## Sequence Diagram: Non-Voting Delegation and Rewards {% @mermaid/diagram content="sequenceDiagram participant User participant ShareclassModule as x/shareclass Module participant StakingModule as x/staking Module participant BankModule as x/bank Module ``` User->>ShareclassModule: MsgNonVotingDelegate (RISE) ShareclassModule->>StakingModule: Delegate to Validator (internally) ShareclassModule-->>User: Return Shares and Initial Rewards (if any) loop Reward Period StakingModule-->>ShareclassModule: Distribute Staking Rewards end User->>ShareclassModule: MsgClaimRewards ShareclassModule->>BankModule: Transfer Rewards to User ShareclassModule-->>User: Confirm Reward Claim User->>ShareclassModule: MsgNonVotingUndelegate ShareclassModule->>StakingModule: Initiate Undelegation (internally) ShareclassModule-->>User: Confirm Undelegation and Completion Time" %} ``` ## Messages The module provides various message types: * MsgUpdateParams: Update module parameters (governance operation) * MsgNonVotingDelegate: Delegate RISE tokens to a validator without voting rights * MsgNonVotingUndelegate: Undelegate RISE tokens from a non-voting delegation * MsgClaimRewards: Claim accumulated staking rewards from non-voting delegation * MsgCreateValidator: Create a new validator in the network ## Queries The module provides various query endpoints: * Params: Query module parameters * CalculateBondingAmount: Calculate tokens that would be bonded for given shares * CalculateShare: Calculate shares that would be received for given tokens * AddressBonded: Get total bonded amount for a specific address * ClaimableRewards: Get claimable rewards for an address from a validator * AddressUnbonding: Get unbonding delegations for a specific address See [Github](https://github.com/sunriselayer/sunrise/tree/main/x/shareclass) for details. # Stable The `x/stable` module manages the minting and burning of a native stablecoin, backed by a basket of accepted collateral assets. ## Key Features 1. **Minting and Burning**: * Allows minting of the native stablecoin against approved collateral. * Allows burning of the native stablecoin to redeem collateral. 2. **Collateral Management**: * Supports a configurable basket of accepted collateral assets, typically IBC denoms. 3. **Permissioned Control**: * Restricts mint and burn operations to a whitelist of authorized addresses. 4. **Dynamic Exchange Rate**: * Calculates exchange rates dynamically based on the `exponent` (decimal places) of the involved tokens, ensuring fair value exchange. 5. **On-Chain Auditability**: * Provides full transparency of all operations and balances for easy auditing. ## Core Concepts > **Note:** The following section covers advanced topics intended for experienced users or developers. ### Parameters The `stable` module's behavior is controlled by a set of on-chain parameters: * **`authority_addresses`** (string\[]): A list of addresses authorized to execute `MsgMint` and `MsgBurn`. * **`accepted_denoms`** (string\[]): A whitelist of collateral asset denominations that can be deposited to mint the stablecoin. These are typically IBC denoms. * **`stable_denom`** (string): The denomination of the native stablecoin minted by the module (e.g., `uusdrise`). ### Exchange Rate Calculation The exchange rate between the collateral asset and the native stablecoin is not hardcoded. Instead, it is calculated dynamically using the `exponent` field from the `DenomMetadata` stored in the `x/bank` module. If `DenomMetadata` is not found for a given token, its exponent is assumed to be `0`. This ensures a fair exchange rate for tokens based on their specified decimal places. ## Workflow: Minting and Burning ### Sequence Diagram {% @mermaid/diagram content="sequenceDiagram participant Authority as Authorized Address participant StableModule as x/stable Module participant BankModule as x/bank Module ``` note over Authority, BankModule: Mint Process Authority->>StableModule: MsgMint activate StableModule StableModule->>BankModule: Transfer collateral from Authority to Module Account StableModule->>BankModule: Mint stablecoin to Module Account StableModule->>BankModule: Send stablecoin from Module Account to Authority deactivate StableModule note over Authority, BankModule: Burn Process Authority->>StableModule: MsgBurn activate StableModule StableModule->>BankModule: Transfer stablecoin from Authority to Module Account StableModule->>BankModule: Burn stablecoin from Module Account StableModule->>BankModule: Send collateral from Module Account to Authority deactivate StableModule" %} ``` ## Messages The module supports the following messages: * **MsgMint** * **Action**: An authorized sender deposits collateral to mint the native stablecoin. * **Process**: 1. Verifies the `sender` is in `authority_addresses`. 2. Confirms all deposited denoms are in `accepted_denoms`. 3. Transfers collateral from the sender to the module account. 4. Calculates the corresponding amount of `stable_denom` to mint using the exponent-based exchange rate. 5. Mints the calculated amount of `stable_denom` and sends it to the `sender`. * **MsgBurn** * **Action**: An authorized sender burns the native stablecoin to receive a chosen collateral asset. * **Process**: 1. Verifies the `sender` is an authority. 2. Confirms the requested `output_denom` is in `accepted_denoms`. 3. Transfers the `input_amount` of stablecoin from the sender to the module and burns it. 4. Calculates the corresponding amount of `output_denom` to return using the exponent-based exchange rate. 5. Transfers the calculated collateral amount from the module account to the `sender`. ## Queries The module provides various query endpoints: * **Params**: Query the current module parameters. * **ModuleAccountBalance**: Query the balance of all collateral assets held by the module account. ## Auditability All mint and burn operations, collateral balances held by the module, and the total supply of the stablecoin are publicly accessible on-chain. This design ensures that the stablecoin is always transparently and verifiably collateralized by the assets held in the module account. See [Github](https://github.com/sunriselayer/sunrise/tree/stable/x/stable) for details. # RISE RISE token is the native token of Sunrise network. Fees are paid in USDrise. A part of the USDrise tx fee will be swapped to RISE and then burnt in the [Fee](/learn/sunrise/fee) module. RISE is preserved as `urise` in the Sunrise blockchain. `1000000urise` on the Sunrise network converts to 1 RISE in the real world. * Ticker: $SUNRISE * Denomination on blockchain: `urise` RISE can be minted by burning vRISE 1 to 1. ## vRISE vRISE token is a non-transferable token for staking. The staked amount will be calculated as a voting power for the governance. * Denomination on blockchain: `uvrise` vRISE can be staked to the Sunrise network. The staked amount will be calculated as voting power for governance. Furthermore, the rewards for stakers will be distributed in proportion to the staked amount. To get vRISE, users need to provide liquidity in [Liquidity Pool](/learn/sunrise/liquidity-pool). ## Usage of Tokens | Function | Token(s) | Details | | ------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Security | ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) RISE + ![vRISE](/files/Div3EhI0oboVX6ho0wct) vRISE | Both vRISE & RISE can be staked for Consensus | | Governance | ![vRISE](/files/Div3EhI0oboVX6ho0wct) vRISE | vRISE is used for On-chain governance and Gauge Voting | | Security Emissions | ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) RISE | RISE is distributed for stakers as consensus rewards | | LP Emissions | ![vRISE](/files/Div3EhI0oboVX6ho0wct) vRISE | vRISE is distributed for LPs as incentives | | Fee | Any (swapped to ![USDrise](/files/4ghdAWYSxegI6ZvSHca7) USDrise) | USDrise is used as a transaction fee | **Legend:**\ ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) = RISE ![vRISE](/files/Div3EhI0oboVX6ho0wct) = vRISE ![USDrise](/files/4ghdAWYSxegI6ZvSHca7) = USDrise ## Tokenomics ### Summary * `[Supply] = [Supply of RISE] + [Supply of vRISE]` * Supply cap is 1,000,000,000. * It means `[Supply of RISE] + [Supply of vRISE] <= 1,000,000,000` * Initial Inflation Rate Cap is 10%. * Inflation Rate Cap will gradually diminish by 8% per year. * For example, Inflation Rate of 2nd year is 9.2%. * A part of tx fees (paid in USDrise) is swapped to RISE and burnt. * Supply will grow with following the Supply Cap and Inflation Rate Cap. * Observed Inflation Rate is different from Inflation Rate Cap. * Inflationally minted vRISE will be distributed among stakers validators and delegators for rewards. ### Formal expression * Year: $$t \in {0,\ 1,\ 2,\ \ldots}$$ * Supply of RISE: $$s\_t^{\text{RISE}}$$ * Supply of vRISE: $$s\_t^{\text{vRISE}}$$ * Supply: $$s\_t = s\_t^{\text{RISE}} + s\_t^{\text{vRISE}}$$ * Initial Supply: $$s\_0 = \text{500,000,000}$$ * Initial Inflation Rate Cap: $$\bar{\pi}\_0 = 0.1 = \text{10%}$$ * Disinflation rate: $$\delta = 0.08 = \text{8%}$$ * Supply Cap: $$\bar{s} = \text{1,000,000,000}$$ * It must be satisfied: $$s\_t \le \bar{s}$$ * Inflation Rate Cap: $$\bar{\pi}\_t$$ * Tx fee burnt RISE: $$b\_t$$ * Supply transition: $$s\_{t+1} = \min{(1 + \bar{\pi}\_t) (s\_t - b\_t),\ \bar{s}}$$ * Inflation Rate Cap transition: $$\bar{\pi}\_{t+1} = \max\left{(1 - \delta) \bar\pi\_t,\ \text{0.02} \right}$$ * It means: $$\min\_t \bar{\pi}\_t = \text{0.02} = \text{2%}$$ * Observed Inflation Rate: $$\pi*t = \frac{s*{t+1} - s\_t}{s\_t}$$ #### Simulation This simulation assumes that $$b\_t = 0$$ which means that tx fee is not burnt. * During year 0 to 10, actual Inflation Rate will be lower than this simulation because there must be burnt tx fees. * Zero Observed Inflation Rate doesn't mean zero rewards for validators and stakers. If $$b\_t > 0$$ , then $b\_t$ amount of vRISE will be minted for rewards * Inflation Rate Cap is strictly complied, so there is also a possibility of Observed Inflation Rate being negative value. | Year | Inflation Rate Cap | Total Supply | Observed Inflation Rate | | ---- | -----------------: | ------------: | ----------------------: | | 0 | 10.00% | 500,000,000 | 10.00% | | 1 | 9.20% | 550,000,000 | 9.20% | | 2 | 8.46% | 600,600,000 | 8.46% | | 3 | 7.79% | 651,434,784 | 7.79% | | 4 | 7.16% | 702,161,229 | 7.16% | | 5 | 6.59% | 752,463,565 | 6.59% | | 6 | 6.06% | 802,057,048 | 6.06% | | 7 | 5.58% | 850,690,179 | 5.58% | | 8 | 5.13% | 898,145,641 | 5.13% | | 9 | 4.72% | 944,240,170 | 4.72% | | 10 | 4.34% | 988,823,543 | 1.13% | | 11 | 4.00% | 1,000,000,000 | 0.00% | | 12 | 3.68% | 1,000,000,000 | 0.00% | | 13 | 3.38% | 1,000,000,000 | 0.00% | | 14 | 3.11% | 1,000,000,000 | 0.00% | | 15 | 2.86% | 1,000,000,000 | 0.00% | | 16 | 2.63% | 1,000,000,000 | 0.00% | | 17 | 2.42% | 1,000,000,000 | 0.00% | | 18 | 2.23% | 1,000,000,000 | 0.00% | | 19 | 2.05% | 1,000,000,000 | 0.00% | | 20 | 2.00% | 1,000,000,000 | 0.00% | | 21 | 2.00% | 1,000,000,000 | 0.00% | ## Supported wallet applications ### Wallets that support Cosmos blockchains * Keplr * Leap ### Command Line Interface (CLI) * sunrised ## Listed exchanges * Coming soon # Allocations | SEGMENT | TOTAL SUPPLY IN % | RELEASE SCHEDULE | | ------------------------------------------------ | ----------------- | -------------------------------------------------------------------------------------- | | Community Airdrop (Kaito not included) | 6.8% | 25% unlocked at TGE, 75% fully locked for 6 months and unlocked linearly for 24 months | | Community Contributors & Grants (Kaito included) | 30% | Fully locked for 3 months after TGE, unlocked linearly for 24 months | | Community Round | 1.5% | 100% unlocked at TGE | | Ecosystem | 27.2% | 25% unlocked at TGE, 75% unlocked linearly for 18 months | | Early backers | 14.5% | 5% unlocked at TGE, 95% fully locked for 3 months and unlocked linearly for 12 months | | Initial Core Contributors | 20% | Fully locked for 6 months and unlocked linearly for 18 months | Some parts will be converted to RISE in the genesis. # USDrise USDrise is the native stablecoin of the Sunrise protocol, issued by wrapping noble's USDN. This document provides an overview of USDrise, its features, and how it integrates into the Sunrise ecosystem. ## Overview USDrise is designed to be a stable and reliable medium of exchange within the Sunrise protocol. It aims to maintain a 1:1 peg with the US Dollar. There are two primary ways to acquire USDrise: 1. **Swap:** Users can also obtain USDrise by swapping other tokens, such as USDC, USDN, or RISE, through the `x/swap` module within the Sunrise ecosystem. 2. **Mint:** The issuance and burning of USDrise are managed by the `x/stable` module, which requires interaction through an authorized contract. Users can mint USDrise by depositing USDN at a fixed exchange rate of 1 USDN = 1 USDrise. This process ensures transparency and control over the token supply. For more detailed information on the `x/stable` module, please refer to the [x/stable module documentation](/learn/sunrise/stable). ## Key Features * **Transaction Fees:** All transaction fees within the Sunrise protocol are paid in USDrise, making it a central component of the network's economy. * **Yield Generation:** Because USDrise is collateralized with USDN, it generates yield that is distributed to RISE and vRISE stakers. ## Fee Mechanism and Distribution USDrise serves as the primary token for transaction fees within the Sunrise ecosystem. The collected fees, along with yield from the underlying USDN, are distributed to stakeholders, creating a sustainable economic loop. {% @mermaid/diagram content="graph TD; subgraph Revenue Collection User -- "Pay Fee in USDrise" --> Transaction; Transaction -- "Collect Fee" --> FeeCollector\["FeeCollector Module"]; USDN\_Yield\["USDN Yield"] -- "Accumulates" --> FeeCollector; end ``` subgraph Fee & Yield Processing FeeCollector -- "A portion of fees for burning" --> SwapModule; SwapModule -- "Swap USDrise to RISE" --> Burn[("🔥 Burn RISE")]; FeeCollector -- "Remaining Funds (Fees + Yield)" --> Distribution; Distribution -- "Rewards" --> vRISE_Stakers["vRISE Stakers"]; Distribution -- "Rewards" --> RISE_Stakers["RISE Stakers"]; end style Burn fill:#ffcccc,stroke:#333,stroke-width:2px" %} ``` ### Flow Breakdown 1. **Revenue Collection:** The `FeeCollector` module account accumulates funds from two primary sources: * **Transaction Fees:** Users pay transaction fees in **USDrise**. * **USDN Yield:** The yield generated from the underlying USDN backing USDrise is also directed to the `FeeCollector`. 2. **Burn Mechanism:** Based on the `burn_ratio` parameter in the `x/fee` module, a portion of the collected **fees** is swapped for **RISE** and subsequently burned. This acts as a deflationary mechanism for RISE. 3. **Reward Distribution:** All remaining funds in the `FeeCollector` (the portion of fees not burned, plus all USDN yield) are distributed as rewards to both **vRISE** and **RISE** stakers, incentivizing participation in governance and network security. This process ensures that the usage of the network directly contributes to the value of the native tokens and rewards its most committed participants. For more detailed information on the `x/fee` module, please refer to the [x/fee](/learn/sunrise/fee). ## About USDN USDrise is backed by Noble Dollar (USDN), a stablecoin from the noble network. It is important for users to understand the mechanics and risks associated with USDN. We strongly encourage users to conduct their own research on USDN to make informed decisions. Noble Dollar (USDN) is a stablecoin built on the foundation of composable yield. USDN leverages the M^0 Protocol to deliver stablecoin yield collateralized by short term U.S. Treasury Bills. USDN is purpose built for the modular ecosystem and is constructed to allow yield to be directed in a customizable, programmatic and transparent fashion. For more information, please refer to the official documentation from Noble: [Noble Dollar (USDN)](https://www.noble.xyz/usdn) ## Related Documents * [**x/stable Module**](/learn/sunrise/stable) # Gluon Gluon is an order‑book Layer‑2 blockchain built with [Rollkit](https://rollkit.dev/) and secured by Sunrise, a next-generation L1 combining data availability and liquidity.\ The base layer for Interliquid Networks.\ The rollup implements Sunrise's Proof‑of‑Liquidity (PoL) and leverages IBC for seamless asset movement. *** ## Key Features | Category | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------ | | **Order‑book DEX** | Deterministic matching logic, price‑time priority, and on‑chain settlement. | | **Web2‑style onboarding** | OAuth registration abstracts private‑key management; user keys never leave the client device. | | **Off‑chain matching** | High‑throughput matching engine batches trades before finalising them on chain. | | **Double‑signature model** | All funding transactions require both user and operator signatures, preventing unilateral withdrawals. | | **IBC deposits/withdraws** | Native IBC channels connect Gluon to external Cosmos‑SDK chains for trust‑minimised transfers. | *** ## Developer Overview * **Source code:** * **Sunrise Rollkit adapter:** * **Modules used:** `x/order`, `x/perp`, `x/customauth` (see protobuf definitions). *** ## Authentication & Key Management Gluon introduces a *CustomAuth* flow that pairs a web‑generated ECDSA key with an on‑chain account: 1. **OAuth sign‑up** → server deterministically derives user address. 2. **Device pairing** → browser generates an AES key and an ECDSA key; the latter is AES‑encrypted and stored server‑side. 3. **Verification key** is submitted on chain (pairing transaction). ### Sign‑up Flow The sign-up process is intentionally simple and user-friendly: * Users can sign up using familiar OAuth providers (Google, GitHub, etc.) * The application automatically derives a Sunrise address for the user * No manual wallet setup or seed phrase management required {% @mermaid/diagram content="sequenceDiagram autonumber User ->> App : OAuth sign‑up App --> App : Derive Sunrise address" %} This streamlined process ensures users can start trading quickly without blockchain complexity. ### Device‑Pairing Flow The device pairing process implements several security measures: * Generates unique encryption keys for each device * Keeps sensitive ECDSA keys encrypted and secure * Establishes a verification mechanism for future transactions {% @mermaid/diagram content="sequenceDiagram autonumber User ->> Browser : Initiate pairing Browser --> Browser : Generate AES key Browser --> Browser : Generate ECDSA key Browser --> Browser : Encrypt ECDSA with AES Browser ->> App : Upload encrypted key + verification key App ->> Gluon : Tx: register verification key" %} This multi-step process ensures secure key management while maintaining user control. ### Order Creation (off‑chain) The off-chain order creation process enables high-performance trading: * Orders are signed locally using the user's encrypted key * Signatures are verified before being accepted * Orders remain off-chain until batched for matching {% @mermaid/diagram content="sequenceDiagram autonumber User ->> Browser : Place order Browser --> Browser : Decrypt ECDSA key Browser --> Browser : Sign order payload Browser ->> App : Order + signature" %} This approach allows for sub-second order placement while maintaining security. ### Order Cancellation (on‑chain) The cancellation process ensures order integrity: * Cancellations are recorded on-chain for transparency * Prevents replay attacks of old signatures * Provides immutable proof of cancellation {% @mermaid/diagram content="sequenceDiagram autonumber User ->> App : Cancel order App ->> Gluon : Tx: register order + cancel" %} This on-chain record is crucial for maintaining order book integrity. ### Withdrawal (IBC) The withdrawal process implements multiple security layers: * Requires dual signatures from both user and operator * Implements a 24-hour security delay for new key pairs * Uses IBC for trust-minimized cross-chain transfers {% @mermaid/diagram content="sequenceDiagram autonumber User ->> Browser : Withdraw request Browser --> Browser : Decrypt ECDSA key & sign tx Browser ->> App : Signed withdrawal App --> App : Operator signs tx App ->> Gluon : Tx with dual signatures Gluon --> Gluon : Verify signatures & 24 h key‑pairing delay Gluon ->> ChainX : IBC transfer" %} This multi-layered approach ensures secure and reliable asset transfers across chains. > No external wallets (e.g., MetaMask) are required; keys remain client‑side and are revocable on‑chain. ## Trading Lifecycle ### Order Creation (off‑chain) Orders reside off‑chain until batched in the first matching transaction, enabling sub‑second UX. {% @mermaid/diagram content="sequenceDiagram autonumber User ->> Browser : Place order Browser --> Browser : Decrypt ECDSA key Browser --> Browser : Sign order payload Browser ->> App : Order + signature" %} ### Order Cancellation (on‑chain) An on‑chain record prevents operators from replaying stale user signatures. {% @mermaid/diagram content="sequenceDiagram autonumber User ->> App : Cancel order App ->> Gluon : Tx: register order + cancel" %} ### Withdrawal (IBC) A 24‑hour latency between key‑pairing and fund movements mitigates operator‑key compromise. {% @mermaid/diagram content="sequenceDiagram autonumber User ->> Browser : Withdraw request Browser --> Browser : Decrypt ECDSA key & sign tx Browser ->> App : Signed withdrawal App --> App : Operator signs tx App ->> Gluon : Tx with dual signatures Gluon --> Gluon : Verify signatures & 24 h key‑pairing delay Gluon ->> ChainX : IBC transfer" %} ## Order Module (protobuf) The order subsystem is defined in `gluon/order/*`. Core types: The `BaseOrder` message defines the fundamental structure for all orders in the system: * Each order is associated with a specific user address and trading pair * Orders can be either limit orders (with a specified price) or market orders * The expiry timestamp prevents replay attacks and ensures order freshness * Amount and price are stored as strings to handle arbitrary precision ```go message BaseOrder { string address = 1; // bech32 user address string denom_base = 2; // e.g., "uatom" string denom_quote = 3; // e.g., "uusdc" OrderDirection direction = 4; // BUY / SELL string amount = 5; // base amount string limit_price = 6; // optional google.protobuf.Timestamp expiry = 7; // anti‑replay } enum OrderDirection { ORDER_DIRECTION_UNSPECIFIED = 0; ORDER_DIRECTION_BUY = 1; ORDER_DIRECTION_SELL = 2; } ``` The `OrderDirection` enum provides a type-safe way to specify order sides: * Uses standard protobuf enum conventions with an UNSPECIFIED default * Clearly distinguishes between buy and sell orders * Helps prevent order-side related bugs through compile-time checking # GLU $GLU token is the native token of the Gluon rollup on Sunrise. It was formerly $GUU token on UnUniFi Layer 1 app chain. # Thesis ## Monolithic vs Modular There are four layers in a blockchain: * Execution layer * Settlement layer * Consensus layer * Data Availability layer "Modular blockchain" is a paradigm that combines these separated layers, and allows us to build a scalable blockchain. ## Data Availability layer In short, the Data Availability (DA) layer plays a role of storing transaction data of Layer 2 blockchains until the L2 transactions are finalized in the L1 blockchain. ## Combinations of layers ### Conventional rollup Example of Optimism: | | | | ----------------------- | -------- | | Execution layer | Optimism | | Settlement layer | Ethereum | | Consensus layer | Ethereum | | Data Availability layer | Ethereum | ### Smart contract rollup with altDA Example of Eclipse: | | | | ----------------------- | -------- | | Execution layer | Eclipse | | Settlement layer | Ethereum | | Consensus layer | Ethereum | | Data Availability layer | Celestia | ### Sovereign rollup Example of Gluon: | | | | ----------------------- | ------- | | Execution layer | Gluon | | Settlement layer | Gluon | | Consensus layer | Sunrise | | Data Availability layer | Sunrise | # App chain thesis The **app‑chain thesis** argues that the optimal way to scale Web3 is to give each major application its **own blockchain** and then connect those chains through an **interoperability layer — in the Cosmos world, IBC**.\ While compelling, the original (“monolithic”) version of this thesis carries hidden operational costs. A new **modular** approach, powered by sovereign rollups and *Rollup‑as‑a‑Service* (RaaS), eliminates most of those frictions. *** ## Monolithic App‑Chain Thesis > *“Every serious dApp deserves its own L1.”* ### Advantages * **Performance isolation** – no gas‑competition with unrelated apps. * **Full customisation** – application‑specific VM, fee logic, and governance. * **Native interoperability** – IBC packets for cross‑chain calls without trusted bridges. ### Core Weakness – *Validator Bootstrapping* Launching a bespoke L1 requires: 1. **Recruiting a validator set** (dozens of professional operators). 2. **Distributing a native token** with sufficient market cap to incentivise honest behaviour. 3. **Continuous DevOps** – chain upgrades, monitoring, slashing infrastructure, etc. This overhead slows adoption; many teams stay on shared L1s for simplicity. *** ## Modular App‑Chain Thesis > *“Keep sovereignty, outsource consensus.”* A **sovereign rollup** publishes its block data to a **shared data‑availability (DA) layer** (e.g., Celestia, Avail, EigenDA, Sunrise).\ Security is borrowed from the DA layer’s validator set; the rollup itself only needs a **sequencer** (or shared sequencer network) and application logic. ### Why It Solves Bootstrapping * **No new validator set** – DA layer provides consensus and economic security. * **Token optional** – the app token can focus on in‑app utility; it need not secure consensus. * **RaaS platforms** – Rollkit, Dymension, Eclipse, Sovereign SDK, Saga, etc., automate deployment, upgrades, and monitoring. ### Compatibility with IBC Sovereign rollups can embed **IBC light‑client verification** directly in their state machine, making them *first‑class citizens* in the Cosmos/IBC mesh even though they are not full L1s. *** ## Smart Contract vs. App Chains – A Hosting Analogy | Architecture | Infra Analogy | Operational Impact | | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------- | | **Smart Contract** | Shared hosting | Cheapest to deploy but subject to neighbour congestion and generic fee model. | | **Modular App‑Specific Chain** | Virtual Private Server | Near‑dedicated resources; security outsourced; inexpensive rollup bootstrap. | | **Monolithic App‑Specific Chain** | Dedicated bare‑metal | Complete control and isolation but highest cost to boot and maintain validators. | As IaaS evolved from VPS to fully managed platforms, **RaaS will commoditise sovereign rollup deployment** until spinning up a dedicated chain is almost as simple as deploying a smart contract today. *** ## Roadmap to a Modular Multichain Future 1. **Shared Sequencers & MEV markets** – reduce rollup latency and enable cross‑rollup atomicity. 2. **Universal IBC clients** – Tendermint, Ethereum‑style SSZ, and ZK‑light clients packaged as reusable modules. 3. **Permissionless DA pricing** – pay‑per‑byte markets (e.g., Avail’s Proof‑of‑Liquidity) lower fixed costs. 4. **Inter‑rollup composability** – ICS applications (ICS‑20, ICS‑721, Interchain Accounts) running natively between sovereign rollups. 5. **Turn‑key governance** – on‑chain upgrade managers and shared security (e.g., Replicated Security, Babylon BTC staking). The modular app‑chain thesis retains the **sovereignty and customisability** of dedicated chains while achieving **ease‑of‑deployment and economic efficiency** unprecedented in earlier models. # Interoperability Sovereign rollups mark a significant evolution in Layer 2 design. Instead of delegating cross‑chain validation to a settlement‑layer bridge contract, a sovereign rollup *runs its own light‑client verification* of counterpart chains and therefore decides—at the application level—*how* and *with whom* it communicates.\ This architecture preserves rollup autonomy while still allowing trust‑minimised data availability (DA) and settlement on an external layer. *** ## Traditional Smart‑Contract Rollups In a classical optimistic/ZK rollup, every cross‑chain action must pass through **one hard‑coded “enshrined” bridge** that lives on the Layer 1 settlement chain. **Execution path** 1. **Rollup contract on L1** – stores state roots and bridge logic. 2. **Proof/optimistic window** – rollup posts proofs or roots; the bridge contract adjudicates fraud/ZK proofs. 3. **Outbound transfers** – users lock assets inside the bridge; withdrawal proofs are verified by the contract. 4. **Upgrade friction** – any change to bridge semantics requires an L1 contract upgrade (often via governance hard fork). **Limitations** * **Single‑point trust** – the bridge contract becomes systemic risk. * **No heterogeneous bridges** – applications cannot add new channels without L1 governance. * **Wrapped assets** – most bridges mint IOU tokens instead of native transfers. * **Throughput bottleneck** – all messages queue in the same contract; gas spikes propagate to rollup users. *** ## Sovereign Rollups A sovereign rollup publishes its data (blobs, state roots) to a DA layer but *self‑verifies* other chains via on‑chain light clients or validity proofs.\ Bridges become regular modules that can be permissionlessly deployed and upgraded. ### Technical Properties | Capability | Implementation Detail | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Self‑sovereign verification** | Embedded light client or ZK verifier for each remote chain; no dependency on an external bridge contract. | | **Multiple protocols** | Support for IBC, custom SNARK bridges, or token‑specific channels in parallel. | | **Native asset movement** | Light‑client verification lets the rollup unlock *original* tokens, avoiding wrapped IOUs. | | **Composable channels** | Each application can instantiate independent channels with custom fee logic, rate limits, or middleware. | | **Decoupled upgrades** | Bridge logic is a rollup module; upgrading does **not** require L1 governance—only rollup governance or code update. | *** ## IBC — De‑Facto Standard for Sovereign Interoperability The **Inter‑Blockchain Communication (IBC)** protocol (originating in the Cosmos SDK) provides: * **Client–Connection–Channel abstraction** – layered handshake that cleanly separates authentication (light clients) from application semantics. * **Commit‑only light clients** – each chain stores the other chain’s header commitments and verifies Merkle proofs on‑chain. * **Permissionless relayers** – off‑chain processes broadcast packets; any actor can relay without gaining trust power. * **ORDERED / UNORDERED channels** – deterministic packet sequencing suited for both fungible tokens (ICS‑20) and arbitrary data (ICS‑27, ICS‑721, etc.). * **Timeout & upgrade paths** – channels can close on misbehaviour; light clients autonomously upgrade using on‑chain proof of new client state. Because sovereign rollups already own their state transition function, integrating IBC requires only: 1. Importing an IBC *core* module (client, connection, channel logic). 2. Supplying a light‑client implementation for each counterparty (e.g., Tendermint‑BFT, zk‑based header proof, Ethereum‑SSZ). 3. Defining application modules (token transfers, cross‑rollup DEX, etc.) that marshal packets. *** ## Comparison: Traditional vs. Sovereign Interoperability | Feature | Traditional Rollups | Sovereign Rollups | | -------------------- | --------------------------- | ---------------------------------------- | | Bridge Authority | L1 settlement layer | Self‑sovereign verification | | Bridge Customisation | Limited or none | Fully customizable | | Protocol Support | Proprietary, single bridge | Multiple (IBC, ZK bridges, custom) | | Asset Types | Often limited to tokens | Tokens, NFTs, arbitrary data packets | | Security Model | Inherits L1 bridge contract | Choice of light‑client or validity proof | | Upgrade Path | Dependent on L1 governance | Independent—rollup‑level governance | *** ## Sovereign Rollup Tooling & Ecosystem | Framework / Component | Interoperability Features | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Rollkit** | Plug‑and‑play modular rollup framework; native IBC wiring; supports Tendermint, Celestia, and Sunrise DA back‑ends. | | **Sovereign SDK** | Rust toolkit for zero‑knowledge or fraud‑proof sovereign chains; ships generic IBC light‑client traits and relayer hooks. | | **Sunrise DA** | Provides data availability with Proof of Liquidity (PoL); exposes an IBC interface so sovereign rollups built on Sunrise inherit connectivity to the broader IBC mesh. | | **Application Patterns** | *Cross‑Chain DeFi* (omni‑liquidity pools), *Interoperable Gaming* (asset portability), *Multi‑Chain Identity* (DID packets), *Chain‑Agnostic DAOs* (governance spanning multiple rollups). | # App Sunrise is a decentralized application (dApp) that provides a comprehensive suite of tools for interacting with the Sunrise blockchain and its ecosystem. This guide provides an overview of the key concepts and features to get you started. ## The Sunrise Token Trio: RISE, vRISE, and USDrise The Sunrise ecosystem is powered by three distinct tokens, each with a specific purpose. * ![RISE](/files/PFYveJ8w0TFAzZjbApfL) **RISE**: The primary value-accrual and consensus token of the network. It can be staked to help secure the network and earn rewards. * ![vRISE](/files/7nDX5eFhO62xiPXWzLAl) **vRISE**: The non-transferable governance and utility token. **vRISE is essential for participating in the protocol's governance.** * **How to Earn vRISE**: You can only earn vRISE by providing liquidity in the [**Liquidity Pool**](/learn/sunrise-app/liquidity-pool). * **How to Use vRISE**: Stake your vRISE to gain voting power for [**Governance**](/learn/sunrise-app/gov) proposals and to direct liquidity pool incentives through Gauge Voting. * ![USDrise](/files/0mj6Cs3MTZyuZNMWRIJ7) **USDrise**: The native stablecoin of the protocol. It is used as the base currency for all transaction fees. ## Core Features Here's a quick overview of the primary sections of the app. Each feature has its own detailed documentation page. * [**Liquidity Pool**](/learn/sunrise-app/liquidity-pool) * Provide liquidity to various token pairs to earn trading fees and **vRISE rewards**. Managing your liquidity positions is the key to earning vRISE. * [**Swap**](/learn/sunrise-app/swap) * Exchange tokens seamlessly across different blockchains. * [**Governance**](/learn/sunrise-app/gov) * Use your staked **vRISE** to vote on governance proposals and liquidity pool incentives. You can also stake RISE to earn consensus rewards. * [**Lockup**](/learn/sunrise-app/lockup) * Manage your locked tokens received from airdrops or other programs. You can stake these locked tokens to earn rewards while they vest. * [**Point Program**](/learn/sunrise-app/point-program) * Earn points by participating in various activities within the ecosystem, such as staking, providing liquidity, and referring new users. ## Understanding Fees on Sunrise The Sunrise Chain uses a Fee Abstraction mechanism, making transactions smooth for users. * **USDrise is the Core Fee Token**: All transaction fees on the network are calculated and paid in USDrise. * **Pay with (Almost) Any Token**: Thanks to Fee Abstraction, you can select another token you hold to pay for fees. The protocol automatically handles the swap to USDrise on-chain as part of the transaction. For a more detailed explanation of how fees work and how to configure your preferred fee token, please see the [**Fee Documentation**](/learn/sunrise-app/fee). ## Connecting Your Wallet To get started, you'll need to connect a Cosmos wallet. Sunrise currently supports the following wallets: * Keplr * Leap ### How to Connect 1. Click the **"Connect Wallet"** button, usually found in the header. 2. A list of supported wallets (Keplr or Leap) will be displayed. 3. Select the wallet you want to use and approve the connection request within the wallet extension. Once connected, your address will appear in the header, and you can click it to copy the address or disconnect. ## Settings You can customize your app experience through the **Settings** menu, accessible via the gear icon in the header. * **Theme**: Choose between System, Light, or Dark mode to suit your preference. * **Fee Token**: Select which token you prefer to use for paying transaction fees. * **Assets Visibility**: Manage which tokens from external blockchains are visible throughout the app. * **Node Selection**: Advanced users can select specific RPC nodes to connect to for network interactions. # Liquidity Pool Sunrise's Liquidity Pools (LPs) are a core feature of the decentralized exchange (DEX), allowing users to deposit tokens to provide liquidity and earn rewards such as trading fees and vRISE tokens in return. ## Pool List On the Liquidity Pool page, you can see a list of all available pools. Each pool displays the following information: * **Pair**: The pair of tokens that make up the pool. * **ID**: The identification number of the pool. * **TVL**: Total Value Locked in the pool. * **Fees (24h)**: Trading fees generated in the last 24 hours. * **Volume (24h)**: Trading volume in the last 24 hours. * **vRISE Reward Allocation**: The amount of vRISE rewards allocated to this pool. * **APR (Fees + vRISE)**: The Annual Percentage Rate, combining fees and vRISE rewards. From the "View Your Positions" button at the top of the page, you can check all the liquidity positions you are providing. ## Pool Details Selecting a specific pool from the list will take you to its details page. * **Rewards For Liquidity Providers**: Details on the rewards that liquidity providers can earn in this pool. * **Fee Rate**: The trading fee rate for swaps in the pool. * **vRISE Reward APR**: The APR from vRISE token rewards. This value fluctuates based on gauge votes. * **Price Chart**: A chart showing the price fluctuations of the token pair. * **Statistics**: Statistical information such as TVL, 24h volume, 24h fees, and average APR. * **Your Liquidity**: A list of your liquidity positions in this pool. ## Managing Liquidity ### Adding Liquidity You can add liquidity by clicking the "Add Liquidity" button on the pool details page or your positions page. #### 1. Set Price Range Select the price range for which you want to provide liquidity. * **Full Range**: Sets the price range from zero to infinity. This allows you to provide liquidity continuously regardless of price fluctuations, but it is less capital-efficient. * **Custom**: Set a specific price range. Liquidity will only be provided and earn fees when the price is within your set range. This is more capital-efficient, but you will not earn fees if the price goes out of range. * You can use the `log±X%` buttons to quickly set a range based on a percentage from the current price, or manually adjust the range with the slider. #### 2. Enter Token Amounts Enter the amount of tokens you want to provide. When you enter the amount for one token, the amount for the other token will be automatically calculated based on the selected price range. {% hint style="info" %} If your set price range is entirely above or below the current price, the amount for one of the tokens will be fixed at 0. {% endhint %} ### Viewing Your Positions You can view your liquidity positions on the "View Your Positions" page or at the bottom of each pool's detail page. Selecting a position will show the following details: * **Position Status**: Indicates whether the current price is `IN RANGE` or `OUT OF RANGE` of your set prices. * **Price Range**: The price range you have set for providing liquidity. * **Claimable Rewards**: The unclaimed trading fees generated by your position. * **Assets in Position**: The amount of assets currently in your position. ### Increasing Liquidity You can add more liquidity to an existing position by selecting "Increase Liquidity" on the position details page. {% hint style="warning" %} **Important**: When you increase liquidity, your existing position is liquidated and a new one is created. In this process, any unclaimed rewards are automatically sent to your wallet. {% endhint %} ### Decreasing Liquidity You can withdraw some or all of your liquidity from a position by selecting "Decrease Liquidity" on the position details page. You can choose the percentage to withdraw (25%, 50%, 75%, 100%) using the slider or buttons. ### Claiming Rewards You can claim your accumulated trading fees from the "Claim" button on the position details or pool details page. If you have multiple positions, you can also claim all rewards at once. # Swap Sunrise's Swap feature is a powerful tool for directly exchanging tokens across different blockchains. It utilizes IBC and other cross-chain technologies to provide a seamless asset exchange experience. The swap page has two main functions: * **Inter-Blockchain Swap**: Exchange assets between different chains (e.g., Cosmos, Ethereum). * **vRISE**: Convert vRISE tokens to RISE tokens. It also provides a feature to check your past transaction history. ## Inter-Blockchain Swap This is the standard swap feature in Sunrise. You can exchange your desired tokens between various supported blockchains. ### How to Perform a Swap 1. **Select Source and Destination**: * In the `From` field, select the asset you want to swap and the blockchain it's on. * In the `To` field, select the asset you want to receive and its blockchain. 2. **Enter the Amount**: * When you enter the amount of tokens you want to swap in the `From` field, the amount of tokens you will receive is automatically calculated and displayed in the `To` field. * Conversely, you can also enter the desired amount in the `To` field to calculate the required amount of the source token. (This reverse calculation may not be available for some routes, such as those involving EVM chains). 3. **Check Rate and Details**: * After entering an amount, the current exchange rate is calculated. You will be notified upon successful calculation. * Note that this rate is an estimate and may change by the time the transaction is included in a block. 4. **Confirm the Swap**: * Review the details and click the "Swap" button to approve the transaction. Wallet connection and approval are required. ### Notes and Errors * **Fees**: Swaps may incur fees. Standard IBC transfers between chains within the Cosmos ecosystem typically do not have relay fees. However, for swaps with chains outside of Cosmos, such as Ethereum, a relay fee is incurred as it uses "IBC Eureka" from [Skip Protocol](https://docs.skip.build/go/general/fee-info). This fee is automatically included in the rate calculation. * **Calculation Error**: If you see a "Failed to calculate swap rate" error, the amount you entered may be too low to cover the fees or too high for the liquidity pool's capacity. Try a different route or adjust the amount. * **Clear Function**: The "Clear All" button resets all the information you have entered. ## Transaction History You can view your past swap transaction history in a side panel by clicking the "View History" button in the upper-right corner. * **Display**: Shows the source and destination chains, assets, transaction hashes, and timestamps. * **Explorer**: Each transaction hash is a link to the corresponding blockchain explorer for more details. * **Clear History**: Clicking the trash can icon allows you to delete the locally stored history. (This does not erase the on-chain record). ## vRISE to RISE Conversion This is a dedicated feature for converting vRISE tokens to RISE tokens on a 1-to-1 basis. * **Purpose**: Use this to convert vRISE obtained from staking or other activities back into tradable RISE. * **How to use**: Enter the amount of vRISE you wish to convert and click the "Convert vRISE to RISE" button. * **Direction**: This conversion is one-way only, from vRISE to RISE. # Governance Sunrise's governance system allows you to contribute to the network's security and participate in shaping the protocol's future by staking (delegating) your vRISE or RISE tokens. There are two main aspects to governance: * **Governance Proposals**: Chain-wide decisions such as protocol upgrades, parameter changes, and use of community pool funds. * **Gauge Voting**: Voting to determine the allocation of incentives (vRISE emissions) to liquidity pools. {% hint style="info" %} **Important**: To get voting power in both Governance Proposals and Gauge Voting, you must stake **vRISE**. Staking RISE does not grant voting power, but you will still earn staking rewards. {% endhint %} ## Staking (Delegation) You can earn staking rewards by delegating your tokens to a validator. The characteristics of delegating differ between vRISE and RISE. | Feature | 　![vRISE](/files/7nDX5eFhO62xiPXWzLAl) vRISE | ![RISE](/files/PFYveJ8w0TFAzZjbApfL) RISE | | ------------------- | -------------------------------------------- | ----------------------------------------- | | **Voting Power** | Yes (Proposals & Gauges) | No | | **Staking Rewards** | Yes (Auto-compounding) | Yes (Manual claim) | | **Transferability** | No | Yes | | **Redelegation** | Yes | No | ### How to Stake 1. Click the "Stake" button on the Governance page or navigate to the "Delegate" page. 2. Select the "vRISE" or "RISE" tab. 3. Choose a validator to delegate to from the list. 4. Enter the amount of tokens you want to delegate and approve the transaction. {% hint style="warning" %} To stake locked RISE, you must do so from the [**Lockup**](/learn/sunrise-app/lockup) page, not this one. Please refer to the "Lockup" documentation for details. {% endhint %} ### Managing Your Delegations On the "Delegations" page, you can manage your current delegated positions. * **vRISE**: * **Rewards**: Rewards are automatically compounded into your staked position, so no manual claim is necessary. * **Redelegate**: Instantly switch your delegation to another validator without unstaking. * **Undelegate**: Unstake your delegation. There is an unbonding period before the tokens become available. * **RISE**: * **Claim Rewards**: Manually claim your accrued staking rewards, which will be sent to your wallet. * **Undelegate**: Unstake your delegation. Like vRISE, an unbonding period applies. You can check the status of your unbonding delegations on the "Pending Unstake" page within the "Delegations" section. ## Governance Proposals Important protocol decisions, such as chain parameter changes or the use of community funds, are made through governance proposals. ### Viewing and Voting on Proposals 1. On the "Proposals" page, you can see a list of current and past proposals. 2. Click on a proposal to view its details, current voting status (percentage of Yes, No, Abstain votes), and the voting period. 3. If a proposal is in its voting period, you can cast your vote using your voting power (based on your staked vRISE amount). The voting options are: * **Yes** * **No** * **Abstain** * **No With Veto**: A strong "No" vote that can override a proposal and burn the deposit. ## Gauge Voting Gauge Voting is the mechanism for deciding how vRISE incentives are allocated to the various liquidity pools in the next epoch. ### How Gauge Voting Works * **Voting Power**: Your voting power is determined by the amount of vRISE you have staked. * **Voting**: On the "Your Vote" page in the "Gauge Voting" section, you can allocate your voting power to different liquidity pools by percentage. The total must add up to 100%. * **Epochs**: Voting occurs in periods called epochs. When a new epoch begins, the vRISE reward distribution rate for each pool is determined based on the voting results. ### Bribes Bribes are incentives offered to encourage users to vote for a specific pool. * **Offering a Bribe**: Users can offer a bribe (e.g., in RISE) for a specific pool to attract votes. This can be done from the "Register Bribe" page in the "Bribes" section. * **Earning Bribes**: Users who vote for a pool with bribes will earn a share of those bribes, proportional to their voting power cast on that pool. Bribes can be claimed from the "Claimable" page in the "Bribes" section. # Lockup The Lockup feature is for managing tokens that have been distributed through airdrops or other incentive programs and are locked for a specific period. These tokens are progressively unlocked over the set duration. ## Lockup Overview On the main "Lockup" page, you can see a list of all your lockup accounts. Each account displays details of the locked assets and the lockup period. Clicking on an item in the list will take you to the details page for that lockup account. ## Lockup Account Details The details page provides a comprehensive view of the current state of your locked assets. * **Original/Additional Locking**: The original and any additional amounts of the lockup. * **Lockup Start/End**: The date and time when the lockup started and when it will fully end. * **Currently Locked/Unlocked**: A breakdown of currently locked and unlocked assets. * **Delegated (Locked/Unlocked)**: A breakdown of the assets being staked, showing both locked and unlocked portions. From this page, you can perform three main actions related to your lockup account. ### 1. Staking Locked Assets (Delegate) You can delegate your locked RISE to a validator to earn staking rewards. {% hint style="danger" %} **Important**: While you can earn staking rewards from delegating via a lockup account, this **does not grant you voting power** in Governance Proposals or Gauge Voting. {% endhint %} * **How to operate**: Select "Delegate" on the lockup details page, choose a validator and amount, and delegate your assets. ### 2. Managing Delegations Check the status of and manage your currently delegated assets. * **Claim Rewards**: Manually claim the accrued staking rewards and return them to your lockup account. * **Undelegate**: Unstake your assets. * Undelegated tokens do not become available immediately; they enter an **unbonding period** (a waiting period). * You can check the status of your unbonding assets on the "Pending Unstake" page. ### 3. Withdrawing Unlocked Assets You can withdraw assets that have completed their lockup period and are not delegated to your main wallet. * **Withdrawal Conditions**: You can only withdraw assets that are both **unlocked** and **not delegated**. * **To withdraw delegated assets**: You must first undelegate them and wait for the unbonding period to end. After the period is over, the assets will become available for withdrawal. * **How to operate**: Select "Withdraw" on the lockup details page and enter the amount of unlocked assets you wish to withdraw. # Point Program A sustainable, multi-layered point system rewarding long-term alignment with the Sunrise ecosystem. ## Program Overview Sunrise Point Program rewards users across multiple dimensions: ### Daily Activities * Staking vRISE * Providing Liquidity (LP) ### Ongoing (Up to specific time) * Referring new users ### One-time Actions * Connecting EVM wallet * Connecting X (Twitter) *** ## Daily: ![vRISE](/files/7nDX5eFhO62xiPXWzLAl) vRISE Staking Claim your staking points once every 24 hours. Points are calculated based on your current staking amount. {% hint style="info" %} Acquiring vRISE requires providing liquidity. {% endhint %} **Formula: `1 vRISE = 100 points / day`** {% hint style="info" %} Only delegations to `Bonded` validators are eligible. If the validator you are delegating to becomes unbonded, you can redelegate to another `Bonded` validator to continue earning points. {% endhint %} The dashboard shows: * Your available points to claim * Your current staked amount * Your staking distribution across validators * The remaining cooldown timer ## Daily: Liquidity Provision (LP) Claim your LP points once every 24 hours. Points are based on your active LP positions. {% hint style="info" %} Creating a position with RISE will be possible after the RISE token is launched through the Token Generation Event (TGE). {% endhint %} {% hint style="info" %} An LP position is considered `valid` when the current price is within the price range you set for the position. Invalid positions do not earn points. {% endhint %} ### Point Calculation Points are calculated based on the USD value of your liquidity. * **USDrise / USDN LP**: `1 USD equivalent = 120 points` * **Other LP**: `1 USD equivalent = 100 points` The dashboard shows: * Your claimable LP points * Your active LP balance * Your valid vs. invalid positions * The remaining cooldown timer *** ## Referral Program ### How It Works * Share your unique referral link to earn additional points. * You earn **10% of your referee’s points** each time they make a successful claim. * Referral bonuses are calculated and awarded independently for each referee. ### Referral Cap {% hint style="info" %} There is a limit to the number of users you can invite. No points can be earned from users invited beyond this limit. The cap is updated at regular intervals. {% endhint %} *** ## NFT Holder Boost {% hint style="warning" %} This feature is planned for a future update and is not yet active. {% endhint %} Holding a specific NFT provides a boost to your earnings. ### With NFT * Your daily points are multiplied: `Daily points × (1 + x%)` * Your referral bonus also receives this boost. * **Example**: 1,000 vRISE staking points with a 10% boost: `1,000 vRISE × 100 pt × 1.1 = 110,000 points` ### Without NFT * You earn the base rate of points with no multipliers. * Your referral bonus is calculated from your referee's base points only. ### Referral Boost Scenarios **Scenario 1: Neither you (referrer) nor your referee has an NFT** * **You (A)**: Your base points + 10% of referee (B)'s base staking/LP points. * **Referee (B)**: Base rewards only. **Scenario 2: Only you (referrer) have an NFT** * **You (A)**: `(Your base points × (1 + x%))` + `10% of referee (B)'s base staking/LP points`. * **Referee (B)**: Base rewards only. **Scenario 3: Both you (referrer) and your referee have an NFT** * **You (A)**: `(Your base points × (1 + x%))` + `10% of (referee (B)'s base points × (1 + x%))`. * **Referee (B)**: `(Their base points × (1 + x%))`. *** ## One-time Bonuses Earn a one-time point bonus for connecting your accounts. * **EVM Wallet Connection**: `+500 points` * This connection is required for the NFT Holder Boost. * **X (Twitter) Connection**: `+100 points` * This is also required for participation in upcoming retweet campaigns. *** ## Claim Rules * All point claims are manual and must be initiated by you. * Each category (Staking, LP) has its own 24-hour cooldown period after a claim. * You can continue staking, providing liquidity, and referring during cooldown periods. * Points are calculated at the moment you click the "Claim" button. # Fee The Sunrise Chain utilizes a **Fee Abstraction** mechanism for paying transaction fees. ## Base Currency for Transaction Fees The base currency for transaction fees on the Sunrise Chain is ![USDrise](/files/4ghdAWYSxegI6ZvSHca7) **USDrise** . All transaction fees are internally calculated and processed in USDrise. For more details on USDrise, please refer to this document: * [What is USDrise?](/learn/usdrise) ## Fee Abstraction Fee Abstraction is a feature that allows users to pay transaction fees with tokens other than USDrise. This feature enables users to use the tokens they hold directly for fees. Even when a token other than USDrise is set as the fee token using this feature, the fee displayed in your wallet (e.g., Keplr) will still be denominated in USDrise. When the transaction is executed, the selected token is automatically swapped to USDrise at the current swap rate to pay the fee. ### Available Tokens for Fees Only tokens that have a liquidity pair with USDrise in a liquidity pool can be set as a fee token through Fee Abstraction. *** ## How to Configure the Fee Token You can change the token used for transaction fees from the application's settings screen. 1. **Open Settings**: Click the gear icon in the application header to open the settings menu. 2. **Fee Token Section**: In the settings menu, you will find a "Fee Token" section. 3. **Select a Token**: Choose your desired fee token from the dropdown menu. Only tokens that are swappable with USDrise will be displayed. After selection, future transactions will use the specified token for fees. *** ## USDrise Converter Guide The USDrise Converter is a utility that allows eligible users to convert a fixed amount of RISE into USDrise. This is intended as a one-time opportunity for early participants in the ecosystem. ### Eligibility To use the USDrise Converter, your wallet address must be included in the official whitelist. This list is comprised of accounts from the `genesis.json` file, which includes participants from events like the Airdrop and Public Sale. If your connected wallet address is on the whitelist, the "USDrise Converter" button will automatically appear in the application's header. If the button is not visible, your address is not eligible. ### How to Use 1. **Connect Your Wallet**: Start by connecting the wallet that holds your whitelisted address. 2. **Find the Converter Button**: If eligible, you will see a "USDrise Converter" button in the header menu. 3. **Open the Converter**: Click the button to open the conversion dialog. 4. **Review and Confirm**: The dialog will display the fixed conversion rate: * **You Send**: ![RISE](/files/TUKUPlQeRvD8HnKUHgpf) 0.625 RISE * **You Receive**: ![USDrise](/files/4ghdAWYSxegI6ZvSHca7) 0.05 USDrise 5. **Submit the Request**: Click the "Send Request" button to proceed. The transaction will be processed, and you will receive USDrise in your wallet. ### Important Notes * **Fixed Rate**: The conversion amounts are fixed and cannot be changed. * **One-Time Action**: Each whitelisted address can only use the converter once. * **TGE Price**: Please be aware that this conversion rate may be lower than the TGE (Token Generation Event) price of RISE. # Validators In addition to producing and verifying blocks, validators on Sunrise play a crucial role in the security and stability of the network. This section provides an overview of a validator's responsibilities, setup, and related operations. ## How to Become a Validator To become a validator on Sunrise, you must stake a minimum of **1 vRISE**. vRISE is a non-transferable governance token that can only be obtained as an incentive for providing liquidity. For detailed instructions on creating and setting up a validator, please refer to the following document: * [How to Become a Validator](/build/validators/validator) ## Key Responsibilities and Setup ### Data Availability Verification Beyond generating blocks, Sunrise validators have the critical duty of verifying data on the Data Availability (DA) layer that has been flagged as potentially fraudulent. To automate this verification process, a validator node must constantly run the following three daemons: 1. `sunrised` (Integration with Cosmovisor is recommended) 2. `sunrise-data validator` 3. `IPFS Daemon` For more details on the DA verification mechanism and setup, please see here: * [Data Availability Proof](/build/validators/data-availability-proof) ## Self-Delegating RISE Validators can delegate their own RISE (from either a regular or a locked balance) to themselves. This self-delegation can increase their block production allocation and allow them to earn more staking rewards. The specific methods for self-delegation are detailed in the following document: * [Self Delegation](/build/validators/self-delegation) # How to Become a Validator This document explains the steps to become a validator on the Sunrise chain. ## Prerequisites Before operating a validator, you must set up a [Full Consensus Node](/run-a-sunrise-node/types/consensus/full-consensus-node) and be fully synchronized with the network. ## Data Availability Verification {% hint style="warning" %} Validators on the Sunrise network are required to verify data for the Data Availability (DA) layer. This is a crucial responsibility. Please see the [Proof of the Data Availability Layer](/build/validators/data-availability-proof) guide for instructions on how to set this up. {% endhint %} ## Setup Cosmovisor For mainnet, it is strongly recommended to use Cosmovisor to run your node. Cosmovisor allows you to perform chain upgrades smoothly with minimal downtime. Follow the [Cosmovisor setup tutorial](/run-a-sunrise-node/types/consensus/setup-cosmovisor) for details. It is recommended to set the following environment variable to enable automatic upgrades: ```bash export DAEMON_ALLOW_DOWNLOAD_BINARIES=true ``` ## Binary and Genesis File When setting up a validator, it is crucial to use the correct version of the binary and `genesis.json`. * **Binary:** The latest binary can be downloaded from the [GitHub releases](https://github.com/sunriselayer/sunrise/releases/tag/v1.0.0). * **Genesis File:** The `genesis.json` file is located in the [network repository](https://github.com/sunriselayer/network/tree/main/sunrise-1). ## Creating a Validator There are two ways to create a validator: joining at genesis and joining after the chain has started. ### Join as a Genesis Validator (Gentx) To join as a validator before the network starts (as a genesis validator), you need to generate and submit a `gentx` (genesis transaction). For detailed instructions, please refer to the [README in the sunriselayer/network repository](https://github.com/sunriselayer/network/blob/main/sunrise-1/gentx/README.md). ### Join as a Validator After the Chain Has Started If the chain is already running, you can create a validator with the following method. #### `tx staking create-validator` This is the standard Cosmos SDK method, which uses a `validator.json` file to create a validator. This method requires `vRISE` for self-delegation. This method requires `vRISE` for self-delegation. 1. **Get the Validator's Public Key** Run the `sunrised tendermint show-validator` command to get the validator's public key (pubkey). ```bash sunrised tendermint show-validator ``` 2. **Create the `validator.json` file** Create a `validator.json` file with the following content. Set the `pubkey` with the value obtained above. ```json { "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"oWg2ISpLF405Jcm2vXV+2v4fnjodh6aafuIdeoW+rUw="}, "amount": "1000000uvrise", "moniker": "myvalidator", "identity": "optional identity signature (ex. UPort or Keybase)", "website": "validator's (optional) website", "security": "validator's (optional) security contact email", "details": "validator's (optional) details", "commission-rate": "0.1", "commission-max-rate": "0.2", "commission-max-change-rate": "0.01", "min-self-delegation": "1" } ``` * The `amount` is specified in `uvrise`. * The `min-self-delegation` is also the amount of `vRISE`. 3. **Send the `create-validator` transaction** ```bash sunrised tx staking create-validator path/to/validator.json --from --chain-id --gas="auto" --gas-prices= -y ``` **Usage:** ```bash sunrised tx staking create-validator [path/to/validator.json] [flags] ``` ## Backup Backing up key files is crucial for validator operations. Please back up the following files to a secure location: * `~/.sunrise/config/priv_validator_key.json` * `~/.sunrise/config/node_key.json` It is strongly recommended to encrypt these backup files. # Proof of Data Availability Sunrise's Data Availability Layer is validated by validators. Validators must validate data that may not be valid and send the proofs to chain. This section describes how validators prove data. ## Proof The only data that require proof are those that have been sent MsgSubmitInvalidity and the status has been changed to `CHALLENGING`. The threshold for `CHALLENGING` is when MsgSubmitInvalidity is sent for 33% (the default in genesis) of the entire shards. The validator is then validated. If more than a certain number of shards are proved, the status changes to `VERIFIED` as usual. If not, the status changes to `REJECTED`. See [Data Availability](/learn/sunrise/data-availability) for status and proof of data in the Data Availability Layer. ## Sunrise-Data for Validator sunrise-data provides validators with the functions to monitor and prove data that has become `CHALLENGING`. ### Register proof deputy of your validator Although validators can send tx themselves to send proof data, it is recommended to use a deputy address to prevent leakage of keys. First, create a new account to serve as the deputy. ```bash sunrised keys add your_deputy_account --keyring-backend=test ``` Next, send some `uusdrise` to this account using the `tx bank send` command. This will be used to pay for gas fees when submitting `SubmitValidityProof` transactions. ```bash DEPUTY_ADDRESS=$(sunrised keys show your_deputy_account -a --keyring-backend=test) sunrised tx bank send [your_validator_key] $DEPUTY_ADDRESS 1000000uusdrise \ --chain-id=$CHAIN_ID \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` Finally, register the deputy address with your validator. This transaction must be sent from your validator's account and only needs to be done once. ```bash sunrised tx da register-proof-deputy $DEPUTY_ADDRESS \ --from [your_validator_key] \ --chain-id=$CHAIN_ID \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` Register the address of the deputy to be used on `sunrise-data`. ### How to set up 1. Running `sunrised` as a validator See [Validator Node](/run-a-sunrise-node/types/consensus/validator-node) for setting up. 2. Clone sunrise-data repo ```bash cd ~ git clone https://github.com/sunriselayer/sunrise-data.git cd sunrise-data make install ``` 3. Create and edit `config.toml` ```bash cp config.default.toml config.toml vi config.toml ``` To connect to a local IPFS daemon, leave the `ipfs_api_url` field empty Change `home_path` to your .sunrise directory, `proof_deputy_account` to your sunrised key's name and `validator_address` to your validator address. ```toml [api] port = 8000 ipfs_api_url = "" ipfs_address_info = "" [chain] address_prefix="sunrise" home_path="/home/ubuntu/.sunrise" keyring_backend="test" sunrised_rpc="http://localhost:26657" [validator] proof_deputy_account="your_deputy_account" validator_address="sunrisevaloper1a8jcsmla6heu99ldtazc27dna4qcd4jyv75vcz" proof_fees="10000uusdrise" proof_interval=5 ``` ### Run IPFS on local 1. Run IPFS ```bash wget https://dist.ipfs.tech/kubo/v0.31.0/kubo_v0.31.0_linux-amd64.tar.gz tar -xvzf kubo_v0.31.0_linux-amd64.tar.gz cd kubo sudo ./install.sh ipfs init --profile=lowpower ipfs daemon ``` 2. Check the IPFS node ID and optionally share and add a remote peer ```bash ipfs id ``` ### Start to proof data On your sunrise-data directory, ```bash sunrise-data validator ``` Or register as a service ```bash vi /etc/systemd/system/sunrise-data.service systemctl enable sunrise-data systemctl start sunrise-data ``` ```service [Unit] Description = sunrise-data validator daemon After=network-online.target [Service] User=ubuntu WorkingDirectory=/home/ubuntu/sunrise-data ExecStart = /home/ubuntu/go/bin/sunrise-data validator Restart=on-failure RestartSec=3 LimitNOFILE=1400000 [Install] WantedBy = multi-user.target ``` If the setup is successful, the display will look like this ```bash $ sunrise-data validator {"level":"info","time":"2025-02-19T18:32:52+09:00","message":"Starting validator task"} {"level":"info","time":"2025-02-19T18:32:52+09:00","message":"validator: sunrisevaloper1a8jcsmla6heu99ldtazc27dna4qcd4jyv75vcz deputy: sunrise155u042u8wk3al32h3vzxu989jj76k4zcc6d03n"} {"level":"info","time":"2025-02-19T18:32:52+09:00","message":"On-chain data is checked every 5 sec"} ``` # Self Delegation Validators can self-delegate RISE to themselves to earn staking rewards. {% hint style="warning" %} **Note**: Unlike delegating vRISE, delegating RISE does not grant any governance voting power. {% endhint %} The method for delegating RISE differs depending on whether the tokens are in a regular wallet balance or a lockup account. The module and command used will be different for each case. *** ## Delegating from a Regular Balance (`x/shareclass`) To delegate RISE held directly in your wallet, use the `non-voting-delegate` command from the `x/shareclass` module. ### How to Delegate **Usage:** ```bash sunrised tx shareclass non-voting-delegate [validator_address] [amount] [flags] ``` **Example:** ```bash # Get validator address VALIDATOR_ADDRESS=$(sunrised keys show --bech val -a) # Execute delegation sunrised tx shareclass non-voting-delegate $VALIDATOR_ADDRESS 10000000urise \ --from \ --chain-id \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` ### How to Claim Rewards Use the `claim-rewards` command from the `x/shareclass` module to claim your accumulated staking rewards. The rewards will be sent to your wallet. **Usage:** ```bash sunrised tx shareclass claim-rewards [validator_address] [flags] ``` **Example:** ```bash VALIDATOR_ADDRESS=$(sunrised keys show --bech val -a) sunrised tx shareclass claim-rewards $VALIDATOR_ADDRESS \ --from \ --chain-id \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` *** ## Delegating from a Lockup Account (`x/lockup`) To delegate RISE that is part of a lockup (e.g., from an airdrop), you must use the `x/lockup` module. ### 1. Find Your Lockup Account ID First, you need to identify the ID of the lockup account you wish to delegate from. You can list all lockup accounts owned by your key using the `lockup-accounts` query. **Usage:** ```bash sunrised query lockup lockup-accounts [owner] [flags] ``` **Example:** ```bash OWNER_ADDRESS=$(sunrised keys show -a) sunrised query lockup lockup-accounts $OWNER_ADDRESS --output json ``` From the output of this command, find the correct account and note its `id`. ### 2. How to Delegate Once you have the lockup account ID, use the `non-voting-delegate` command from the `x/lockup` module. **Usage:** ```bash sunrised tx lockup non-voting-delegate [lockup_account_id] [validator_address] [amount] [flags] ``` **Example:** ```bash LOCKUP_ID="" VALIDATOR_ADDRESS=$(sunrised keys show --bech val -a) sunrised tx lockup non-voting-delegate $LOCKUP_ID $VALIDATOR_ADDRESS 10000000urise \ --from \ --chain-id \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` ### 3. How to Claim Rewards Use the `claim-rewards` command from the `x/lockup` module. {% hint style="info" %} **Important**: Rewards claimed from a lockup delegation are sent back to the lockup account itself, not your main wallet. The RISE portion of the rewards will be subject to the original lockup schedule. {% endhint %} **Usage:** ```bash sunrised tx lockup claim-rewards [lockup_account_id] [flags] ``` **Example:** ```bash LOCKUP_ID="" sunrised tx lockup claim-rewards $LOCKUP_ID \ --from \ --chain-id \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` *** ## Using the Sunrise App These delegation and reward claiming operations can also be performed easily through the **Sunrise App** interface. For more details, please refer to the following documents: * **For regular delegation:** [Governance](/learn/sunrise-app/gov) * **For delegating locked assets:** [Lockup](/learn/sunrise-app/lockup) # L2 Blockchains ## Sunrise Documents * [Rollkit](/build/l2-blockchains/rollkit) * [Sunrise Data](/build/l2-blockchains/rollkit/sunrise-data) - Configure and run the Sunrise DA relay * [Rollkit L2 Chain](/build/l2-blockchains/rollkit/rollkit) - Build and deploy a Rollkit-based L2 * [Optimism OP Stack](/build/l2-blockchains/optimism) * [Sunrise Data](/build/l2-blockchains/optimism/sunrise-data) - Set up Sunrise DA for OP Stack * [OP Stack L2 Chain](/build/l2-blockchains/optimism/op-stack) - Deploy an OP Stack L2 with Sunrise ## How to create L2 It is recommended to run the full consensus node locally, without relying on an external RPC. This ensures better reliability and control over your L2 deployment. [Sunrise Consensus Node Document](/run-a-sunrise-node/types/consensus) ### Rollkit `sunrise-data`, and `rollkit` need to be run. The integration provides: * Native data availability through Sunrise * Sovereign rollup capabilities * Customizable execution environment * Simple configuration and deployment ### OP Stack `sunrise-data`, `optimism` and `op-geth` need to be run. Key points: * The local EVM L1 chain is only used to meet OP Stack requirements * The actual data (metadata) is stored in Sunrise * Use Ganache, Hardhat, Anvil or similar for local L1 chain * Sunrise handles the actual data availability ## Requirements | Type | CPU | Architecture | Mem | Disk | Bandwidth | Purpose | | ----------------------- | ------ | ------------ | ----- | -------- | --------- | ----------------------- | | Rollkit + Sunrise Data | 4 Core | x86\_64 | 16 GB | 1 TB SSD | 1 Gbps | Development and testing | | OP Stack + Sunrise Data | 6 Core | x86\_64 | 32 GB | 1 TB SSD | 1 Gbps | Production deployment | Additional considerations: * SSD should be enterprise-grade for production * Bandwidth requirements increase with transaction volume * Memory requirements scale with state size ## Official Document * [Rollkit](https://rollkit.dev/learn/intro) * [BeaconKit (option)](https://rollkit.dev/tutorials/execution/beaconkit): By combining BeaconKit and Rollkit, EVM compatible L2 blockchain is possible to develop. * Provides full EVM compatibility while maintaining Sunrise DA benefits * [OP Stack](https://docs.optimism.io/stack/getting-started) * Comprehensive documentation for OP Stack deployment * Integration guides for various components ## Integration Architecture ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ │ │ L2 Blockchain │────▶│ Sunrise DA │────▶│ Validator │ │ │ │ Layer │ │ Network │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ ▲ │ │ │ ▼ ▼ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ │ │ User │ │ DA Proof │─────────────┘ │ Applications │ │ Verification │ └─────────────────┘ └─────────────────┘ ``` ## Common Integration Steps 1. **Setup Sunrise DA Node** * Deploy a Sunrise node or connect to the testnet * Configure network parameters * Set up validator if needed * Verify node synchronization 2. **Configure L2 Framework** * Install required dependencies * Set up configuration files * Connect to Sunrise DA layer * Configure network parameters 3. **Implement DA Integration** * Configure blob submission * Set up proof verification * Implement fee handling * Set up monitoring 4. **Testing and Deployment** * Test on testnet * Verify DA proofs * Deploy to production * Monitor performance ## Configuration Examples ### Rollkit Configuration ```yaml [da] rpc_address = "http://localhost:26657" fee_denom = "uusdrise" gas_price = "0.025" [rollup] chain_id = "my-rollup-1" ``` ### OP Stack Configuration ```bash # Environment variables DA_SERVER=http://localhost:8547 BLOB_RPC=http://localhost:26657 ``` ## Best Practices 1. **Security** * Always verify DA proofs * Use secure RPC endpoints * Implement proper error handling * Regular security audits 2. **Performance** * Optimize blob sizes * Implement proper caching * Monitor gas costs * Regular performance testing 3. **Reliability** * Implement retry mechanisms * Monitor DA proof status * Set up proper logging * Regular backups ## Troubleshooting | Issue | Solution | Prevention | | ----------------------- | -------------------------------------------------- | ------------------------------- | | DA proofs not verifying | Check RPC connection and proof format | Regular connection testing | | High gas costs | Optimize blob size and frequency | Monitor and adjust gas settings | | Connection issues | Verify network configuration and firewall settings | Regular network monitoring | ## Additional Resources * [Rollkit Documentation](/build/l2-blockchains/rollkit) * [OP Stack Integration](/build/l2-blockchains/optimism) * [Data Availability Proofs](/build/validators/data-availability-proof) * [Fee Abstraction](https://github.com/SunriseLayer/gitbook/blob/main/learn/sunrise/fee-abstraction.md) # Rollkit Sunrise's Data Availability Layer supports Layer 2 blockchains created using [Rollkit](https://github.com/rollkit/rollkit) This is a guide to connecting an L2 chain created using Rollkit to Sunrise chain with [Sunrise Data](https://github.com/sunriselayer/sunrise-data). Data Availability layer is supported in Sunrise v0.3.1-rc1 and later. ## Sunrise Data **Before optimism start, set up sunrise-data.**[Sunrise Data Document](/build/l2-blockchains/rollkit/sunrise-data) It is recommended to run the full consensus node locally, without relying on an external RPC.[Sunrise Consensus Node Document](/run-a-sunrise-node/types/consensus) ## Rollkit Start your Rollkit L2 chain. [Rollkit L2 Chain Document](/build/l2-blockchains/rollkit/rollkit) # Sunrise Data [Sunrise Data](https://github.com/sunriselayer/sunrise-data) acts as a relay server connecting the L2 chain to the Sunrise DA layer. ## Sunrise Consensus Node Requires a networked Sunrise node to operate. [Networks](/run-a-sunrise-node/networks) running Sunrise v0.3.0 or higher support Data Availability Layer. Follow the [Node Guide](/run-a-sunrise-node/types/consensus) on how to create a consensus node. ### How to set up sunrise-data 1. Running `sunrised` See [Consensus Node](https://github.com/SunriseLayer/gitbook/blob/main/build/node/types/consensus/full-consensus-node.md) for setting up. 2. Clone sunrise-data repo ```bash cd ~ git clone https://github.com/sunriselayer/sunrise-data.git cd sunrise-data make install ``` 3. Create and edit `config.toml` ```bash cp config.default.toml config.toml nano config.toml ``` To connect to a local IPFS daemon, leave the `ipfs_api_url` field empty Change `home_path` to your .sunrise directory and `publisher_account` to your sunrised key's name ```toml [api] port = 8000 ipfs_api_url = "" ipfs_addrinfo = "" [chain] address_prefix="sunrise" home_path="/home/ubuntu/.sunrise" keyring_backend="test" sunrised_rpc="http://localhost:26657" [publish] publisher_account="your_publisher_account" publish_fees="10000uusdrise" [rollkit] port=7980 data_shard_count=5 parity_shard_count=5 ``` `home_path`, `keyring_backend`, `publisher_account` must be entered values on your sunrised keyring. See [Local Key Pair document](/run-a-sunrise-node/types/consensus/full-consensus-node#create-or-restore-a-local-key-pair) and set with `--keyring-backend test` option. For `home_path`, enter the path where the sunrise keyring exists. 　 For `sunrised_rpc`, it is preferable to run sunrised locally, but if this is not possible, use the published RPC. See our [Network Document](/run-a-sunrise-node/networks). A local key pair is still required in such cases. The other fields can be left as is. ### Run IPFS on local 1. Run IPFS ```bash wget https://dist.ipfs.tech/kubo/v0.31.0/kubo_v0.31.0_linux-amd64.tar.gz tar -xvzf kubo_v0.31.0_linux-amd64.tar.gz cd kubo sudo ./install.sh ipfs init --profile=lowpower ipfs daemon ``` 2. Check the IPFS node ID and optionally share and add a remote peer ```bash ipfs id ``` ### Start ```bash sunrise-data rollkit ``` # Rollkit L2 Chain As an example, here is how to use Rollkit to create an L2 chain and run it on the Sunrise's Data Availability Layer. ## Dependencies Dependencies and general installation instructions for Ubuntu 22.04. ## Set up Sunrise Data Rollkit support is provided via a server included in sunrise-data. See [Rollkit documentation](https://rollkit.dev/tutorials/da/overview) for the role of the DA server. See [Sunrise Data document](/build/l2-blockchains/rollkit/sunrise-data) to set it up. By default, the GRPC server for Rollkit support listens on port 7980. ## Run Rollkit 1. Clone rollkit repo ```bash cd ~ git clone https://github.com/rollkit/rollkit.git cd rollkit git checkout v0.14.1 # latest major version make install ``` 2. Start rollkit chain Use `--rollkit.da_address` option to connect to the DA server. The other port specification options are used to avoid conflicts when running sunrised locally. See [Rollkit documentation](https://rollkit.dev/) for other chain configuration. ```bash rollkit start --rollkit.aggregator \ --rollkit.sequencer_rollup_id sunrise \ --rollkit.da_address grpc://localhost:7980 \ --p2p.laddr tcp://0.0.0.0:25656 --rpc.laddr tcp://127.0.0.1:25657 ``` 3. Work ## Links * [Rollkit](https://rollkit.dev/learn/intro) # OP Stack Sunrise's Data Availability Layer supports Layer 2 blockchains created using [OP Stack](https://github.com/ethereum-optimism/optimism) This is a guide to connecting an L2 chain created using OP Stack to Sunrise chain with [Sunrise Data](https://github.com/sunriselayer/sunrise-data). Data Availability layer is supported in Sunrise v0.3.0 and later. ## Sunrise Data **Before optimism start, set up sunrise-data.** [Sunrise Data Document](/build/l2-blockchains/optimism/sunrise-data) It is recommended to run the full consensus node locally, without relying on an external RPC. [Sunrise Consensus Node Document](/run-a-sunrise-node/types/consensus) ## OP Stack Start your OP Stack L2 chain with [Alt-DA mode](https://docs.optimism.io/operators/chain-operators/features/alt-da-mode). Follow the latest documentation. It may be necessary to have a local EVM chain to meet the requirements. [OP Stack L2 Chain Document](/build/l2-blockchains/optimism/op-stack) # Sunrise Data [Sunrise Data](https://github.com/sunriselayer/sunrise-data) acts as a relay server connecting the L2 chain to the Sunrise DA layer. ## Sunrise Consensus Node Requires a networked Sunrise node to operate. [Networks](/run-a-sunrise-node/networks) running Sunrise v0.3.0 or higher support Data Availability Layer. Follow the [Node Guide](/run-a-sunrise-node/types/consensus) on how to create a consensus node. ### How to set up sunrise-data 1. Running `sunrised` See [Consensus Node](https://github.com/SunriseLayer/gitbook/blob/main/build/node/types/consensus/full-consensus-node.md) for setting up. 2. Clone sunrise-data repo ```bash cd ~ git clone https://github.com/sunriselayer/sunrise-data.git cd sunrise-data make install ``` 3. Create and edit `config.toml` ```bash cp config.default.toml config.toml nano config.toml ``` To connect to a local IPFS daemon, leave the `ipfs_api_url` field empty Change `home_path` to your .sunrise directory and `publisher_account` to your sunrised key's name ```toml [api] port = 8000 ipfs_api_url = "" ipfs_addrinfo = "" [chain] address_prefix="sunrise" home_path="/home/ubuntu/.sunrise" keyring_backend="test" sunrised_rpc="http://localhost:26657" [publish] publisher_account="your_publisher_account" publish_fees="10000uusdrise" [optimism] listen_address="127.0.0.1" port=3100 data_shard_count=10 parity_shard_count=10 ``` 　 `home_path`, `keyring_backend`, `publisher_account` must be entered values on your sunrised keyring. See [Local Key Pair document](/run-a-sunrise-node/types/consensus/full-consensus-node#create-or-restore-a-local-key-pair) and set with `--keyring-backend test` option. For `home_path`, enter the path where the sunrise keyring exists. 　 For `sunrised_rpc`, it is preferable to run sunrised locally, but if this is not possible, use the published RPC. See our [Network Document](/run-a-sunrise-node/networks). A local key pair is still required in such cases. The other fields can be left as is. ### Run IPFS on local 1. Run IPFS ```bash wget https://dist.ipfs.tech/kubo/v0.31.0/kubo_v0.31.0_linux-amd64.tar.gz tar -xvzf kubo_v0.31.0_linux-amd64.tar.gz cd kubo sudo ./install.sh ipfs init --profile=lowpower ipfs daemon ``` 2. Check the IPFS node ID and optionally share and add a remote peer ```bash ipfs id ``` ### Start ```bash sunrise-data optimism ``` # OP Stack L2 Chain Sunrise's Data Availability Layer supports Layer 2 blockchains created using [OP Stack](https://github.com/ethereum-optimism/optimism) This is a guide to connecting an L2 chain created using OP Stack to Sunrise chain with [Sunrise Data](/build/l2-blockchains/optimism/sunrise-data). Data Availability layer is supported in Sunrise v0.3.0 and later. This version of the OP Stack requires the L1 EVM chain for operation. Use some kind of testnet or local chain. ## How to set up OP Stack As an example, here is how to use OP Stack to create an L2 chain and run it on the Sunrise's Data Availability Layer. This guide uses the Ethereum Sepolia testnet to meet the OP Stack requirements, but a local EVM chain will also work. {% @mermaid/diagram content="sequenceDiagram autonumber L2 ->> Ethereum Sepolia: Send Tx (e.g. token transfer) Ethereum Sepolia --> L2: API & Tx Response L2 ->> Sunrise: Send Block Data and Save" %} ### Dependencies Dependencies and general installation instructions for Ubuntu 22.04. * node ```bash curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs ``` * [pnpm](https://pnpm.io/ja/installation) ```bash curl -fsSL https://get.pnpm.io/install.sh | sh - ``` * [foundry](https://book.getfoundry.sh/getting-started/installation) ```bash curl -L https://foundry.paradigm.xyz | bash ``` * just ```bash wget -qO - 'https://proget.makedeb.org/debian-feeds/prebuilt-mpr.pub' | gpg --dearmor | sudo tee /usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg 1> /dev/null echo "deb [arch=all,$(dpkg --print-architecture) signed-by=/usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg] https://proget.makedeb.org prebuilt-mpr $(lsb_release -cs)" | sudo tee /etc/apt/sources.list.d/prebuilt-mpr.list sudo apt update sudo apt install just ``` ### Set up Optimism Rollup Testnet ### Optimism 1. **Clone the optimism repo** ```bash git clone https://github.com/ethereum-optimism/optimism.git ``` 2. Check out the correct branch ```bash cd optimism git checkout v1.9.1 ``` 　We have confirmed the operation with the latest version at the time of document update. If you use other versions, please check the differences. 1. **Run the following to check you have all dependencies** ```bash ./packages/contracts-bedrock/scripts/getting-started/versions.sh ``` 2. Build all packages associated with Optimism ```bash make op-node op-batcher op-proposer ``` If you are having issues with this step, make sure your versions match those in the optimism docs. Specifically, you may have to downgrade your go version. 3. Clone and build op-geth ```bash cd ~ git clone https://github.com/ethereum-optimism/op-geth.git cd op-geth make geth ``` 　 For more information on supported \`op-geth, please check the [Production Releases](https://github.com/ethereum-optimism/optimism/tree/v1.12.0?tab=readme-ov-file#production-releases) in the optimism repository. 1. Fill out environment variables ```bash cd ~/optimism cp .envrc.example .envrc ``` Run the script to generate addresses with the following command in the optimism repo: `./packages/contracts-bedrock/scripts/getting-started/wallets.sh` The output will look like the following which will you need to paste into the environment file as well: ```bash ################################################## # Getting Started # ################################################## # Admin account export GS_ADMIN_ADDRESS=0x82eeB61600f290ce3F9400d345aAEcBe5faF7AEB export GS_ADMIN_PRIVATE_KEY=0x7c726817d047ee62cbb060312fe2620ba5462495e34f7e8279ba22faa96bca20 # Batcher account export GS_BATCHER_ADDRESS=0x7BECbC4C747922d92e4F917951D9D8c3Ada7eb60 export GS_BATCHER_PRIVATE_KEY=0xc7dfaa7b8449f00480196377da50d29318b2397fd0296d0ab4f11d48ee3cf723 # Proposer account export GS_PROPOSER_ADDRESS=0x773F4527fECc889d6DD3Cd7d044F4AC1Ad765a31 export GS_PROPOSER_PRIVATE_KEY=0xed6029a5928e83c5d2a28d9574304bae9a825e19f7f18a50d34edc13b505afed # Sequencer account export GS_SEQUENCER_ADDRESS=0x2B43c41FCbabc5437A6E1B97F47cA085a4B16f61 export GS_SEQUENCER_PRIVATE_KEY=0x0a7d4ce467fe4d00b8930215c98335e06c16db34cd501c8c3f3173015487662e ################################################## # Chain Information # ################################################## # L1 chain information export L1_CHAIN_ID=11155111 export L1_BLOCK_TIME=12 # L2 chain information export L2_CHAIN_ID=42069 export L2_BLOCK_TIME=2 ################################################## # op-node Configuration # ################################################## # The kind of RPC provider, used to inform optimal transactions receipts # fetching. Valid options: alchemy, quicknode, infura, parity, nethermind, # debug_geth, erigon, basic, any. export L1_RPC_KIND=infura ################################################## # Contract Deployment # ################################################## # RPC URL for the L1 network to interact with export L1_RPC_URL=https://sepolia.infura.io/v3/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` API key for RPC URL can be found in [Infura](https://www.infura.io/) or other providers. 2. Fund the addresses with enough Sepolia ETH, the optimism docs recommend the following: * Admin — 0.5 Sepolia ETH * Proposer — 0.2 Sepolia ETH * Batcher — 0.1 Sepolia ETH Ref: [Sepolia PoW Faucet](https://sepolia-faucet.pk910.de/) 3. Load environment variables with direnv `direnv allow` You should see something similar to this after: ```bash direnv: loading ~/optimism/.envrc direnv: export +DEPLOYMENT_CONTEXT +ETHERSCAN_API_KEY +GS_ADMIN_ADDRESS +GS_ADMIN_PRIVATE_KEY +GS_BATCHER_ADDRESS +GS_BATCHER_PRIVATE_KEY +GS_PROPOSER_ADDRESS +GS_PROPOSER_PRIVATE_KEY +GS_SEQUENCER_ADDRESS +GS_SEQUENCER_PRIVATE_KEY +IMPL_SALT +L1_RPC_KIND +L1_RPC_URL +PRIVATE_KEY +TENDERLY_PROJECT +TENDERLY_USERNAME ``` If you do not see any output, try `nano ~/.zshrc` `nano ~/.bashrc` Add the following line depending on whether you use bash or zsh ```bash eval "$(direnv hook zsh)" ``` ```bash eval "$(direnv hook bash)" ``` Save the changes with `source ~/.zshrc` `source ~/.bashrc` 4. Configure the network ```bash cd ~/optimism/packages/contracts-bedrock ./scripts/getting-started/config.sh ``` You can view the config in the **`deploy-config/getting-started.json`** file Add the following at the bottom of the config generated ```bash nano deploy-config/getting-started.json ``` ```json ... "preimageOracleMinProposalSize": 1800000, "preimageOracleChallengePeriod": 300, "useAltDA": true, "daCommitmentType": "GenericCommitment", "daChallengeWindow": 160, "daResolveWindow": 160, "daBondSize": 1000000, "daResolverRefundPercentage": 0 } ``` 5. Deploy the L1 contracts ```bash just install DEPLOYMENT_OUTFILE=deployments/artifact.json \ DEPLOY_CONFIG_PATH=deploy-config/getting-started.json \ forge script scripts/deploy/Deploy.s.sol:Deploy \ --broadcast --private-key $GS_ADMIN_PRIVATE_KEY \ --rpc-url $L1_RPC_URL --slow ``` L2 Allocs ```bash CONTRACT_ADDRESSES_PATH=deployments/artifact.json \ DEPLOY_CONFIG_PATH=deploy-config/getting-started.json \ STATE_DUMP_PATH=deploy-config/statedump.json \ forge script scripts/L2Genesis.s.sol:L2Genesis \ --sig 'runWithStateDump()' \ --chain 42069 ``` Use your L2 chain id in `--chain`. > If you see a nondescript error that includes `EvmError: Revert` and `Script failed` then you likely need to change the `IMPL_SALT` environment variable. This variable determines the addresses of various smart contracts that are deployed via [CREATE2(opens in a new tab)](https://eips.ethereum.org/EIPS/eip-1014). If the same `IMPL_SALT` is used to deploy the same contracts twice, the second deployment will fail. **You can generate a new `IMPL_SALT` by running `direnv allow` anywhere in the Optimism Monorepo.** 6. Generate the L2 config files ```bash cd ~/optimism/op-node ./bin/op-node genesis l2 \ --deploy-config ../packages/contracts-bedrock/deploy-config/getting-started.json \ --l1-deployments ../packages/contracts-bedrock/deployments/artifact.json \ --outfile.l2 genesis.json \ --outfile.rollup rollup.json \ --l1-rpc $L1_RPC_URL \ --l2-allocs ../packages/contracts-bedrock/deploy-config/statedump.json ``` Check the end of the generated `rollup.json` ```json "alt_da": { "da_challenge_contract_address": "0x0000000000000000000000000000000000000000", "da_commitment_type": "GenericCommitment", "da_challenge_window": 160, "da_resolve_window": 160 } ``` 7. Create an authentication key ```bash openssl rand -hex 32 > jwt.txt ``` 8. Copy genesis files into op-geth directory ```bash cp genesis.json ~/op-geth cp jwt.txt ~/op-geth ``` 9. Initialize `op-geth` ```bash cd ~/op-geth mkdir datadir make geth build/bin/geth init --datadir=datadir genesis.json ``` ## Start L2 **Before optimism start, set up `sunrised` & `sunrise-data`, etc.** [**Sunrise Data**](/build/l2-blockchains/optimism/sunrise-data) 1. Start `op-geth` ```bash ./build/bin/geth \ --datadir ./datadir \ --http \ --http.corsdomain="*" \ --http.vhosts="*" \ --http.addr=0.0.0.0 \ --http.port=9545 \ --http.api=web3,debug,eth,txpool,net,engine \ --ws \ --ws.addr=0.0.0.0 \ --ws.port=9546 \ --ws.origins="*" \ --ws.api=debug,eth,txpool,net,engine \ --syncmode=full \ --nodiscover \ --maxpeers=0 \ --networkid=42069 \ --authrpc.vhosts="*" \ --authrpc.addr=0.0.0.0 \ --authrpc.port=9551 \ --authrpc.jwtsecret=./jwt.txt \ --rollup.disabletxpoolgossip=true ``` 2. Start `op-node` ```bash cd ~/optimism/op-node ./bin/op-node \ --l2=http://localhost:9551 \ --l2.jwt-secret=./jwt.txt \ --sequencer.enabled \ --sequencer.l1-confs=5 \ --verifier.l1-confs=4 \ --rollup.config=./rollup.json \ --rpc.addr=0.0.0.0 \ --rpc.port=8547 \ --p2p.disable \ --rpc.enable-admin \ --p2p.sequencer.key=$GS_SEQUENCER_PRIVATE_KEY \ --l1=$L1_RPC_URL \ --l1.rpckind=$L1_RPC_KIND \ --altda.enabled=true \ --altda.da-server=http://localhost:3100 \ --altda.da-service=true \ --l1.beacon.ignore=true ``` \--altda.da-server is your da-serer’s http URL 3. Start `op-batcher` ```bash cd ~/optimism/op-batcher ./bin/op-batcher \ --l2-eth-rpc=http://localhost:9545 \ --rollup-rpc=http://localhost:8547 \ --poll-interval=1s \ --sub-safety-margin=6 \ --num-confirmations=1 \ --safe-abort-nonce-too-low-count=3 \ --resubmission-timeout=30s \ --rpc.addr=0.0.0.0 \ --rpc.port=8548 \ --rpc.enable-admin \ --max-channel-duration=1 \ --l1-eth-rpc=$L1_RPC_URL \ --private-key=$GS_BATCHER_PRIVATE_KEY \ --altda.enabled=true \ --altda.da-service=true \ --altda.da-server=http://localhost:3100 ``` 4. Start `op-proposer` ```bash cd ~/optimism/op-proposer ./bin/op-proposer \ --poll-interval=12s \ --rpc.port=9560 \ --rollup-rpc=http://localhost:8547 \ --l2oo-address=$(cat ../packages/contracts-bedrock/deployments/42069-deploy.json | jq -r .L2OutputOracleProxy) \ --private-key=$GS_PROPOSER_PRIVATE_KEY \ --l1-eth-rpc=$L1_RPC_URL ``` 5. Work # Client The Sunrise client libraries let you **query** the chain, **submit blobs** and **sign / broadcast transactions** from your application without having to run custom protobuf tooling or hand‑craft Tendermint JSON‑RPC calls. ## Available SDKs * **JavaScript / TypeScript** - Primary SDK available on npm * **Rust** - gRPC + protobuf type generation with Buf/Prost * **Go** and **Python** bindings - Coming soon (contributions welcome) ## JavaScript / TypeScript SDK [Sunrise Client](https://github.com/sunriselayer/sunrise-client-js) ### Installation ```bash npm install @sunriselayer/client @cosmjs/proto-signing @cosmjs/stargate # or pnpm add @sunriselayer/client @cosmjs/proto-signing @cosmjs/stargate # or yarn add @sunriselayer/client @cosmjs/proto-signing @cosmjs/stargate ``` ### Basic Usage The client is designed to be used with [CosmJS](https://cosmos.github.io/cosmjs/), the standard library for interacting with Cosmos SDK chains. Here's an example of how to create a concentrated liquidity position: ```typescript import { createEncodeObject, sunriseTypesRegistry, } from "@sunriselayer/client"; // The schemas and types for all modules are exported from the client. // Here, we import the schema for the `MsgCreatePosition` message. import { MsgCreatePositionSchema } from "@sunriselayer/client/types/liquiditypool"; import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing"; import { SigningStargateClient, coin } from "@cosmjs/stargate"; const RPC = "https://goldberg-rpc.sunrise.node"; // Replace with your node const SENDER_MNEMONIC = process.env.MNEMONIC!; // Never commit private keys // This is a simplified example. In a real application, you would fetch pool details // from a query client and calculate ticks from user-provided prices. const MOCK_POOL_ID = 1n; // NOTE: Use BigInt for uint64 fields const MOCK_LOWER_TICK = -20000n; const MOCK_UPPER_TICK = 20000n; async function main() { // 1. Create a wallet and a signer from a mnemonic const signer = await DirectSecp256k1HdWallet.fromMnemonic(SENDER_MNEMONIC, { prefix: "sunrise", // The Bech32 address prefix for Sunrise }); const [account] = await signer.getAccounts(); const senderAddress = account.address; console.log("Sender address:", senderAddress); // 2. Create a signing client with the signer and type registry const client = await SigningStargateClient.connectWithSigner(RPC, signer, { registry: sunriseTypesRegistry, // The custom type registry for Sunrise messages }); console.log("Successfully connected to", RPC); // 3. Prepare a 'Create Position' transaction message // All message fields are fully typed and validated. const msg = createEncodeObject(MsgCreatePositionSchema, { sender: senderAddress, poolId: MOCK_POOL_ID, lowerTick: MOCK_LOWER_TICK, upperTick: MOCK_UPPER_TICK, // Use the `coin` helper from @cosmjs/stargate to create Coin objects tokenBase: coin("1000000", "urise"), // 1 RISE tokenQuote: coin("5000000", "uusdc"), // 5 USDC (example) minAmountBase: "0", // Slippage protection minAmountQuote: "0", // Slippage protection }); // 4. Define the fee and sign and broadcast the transaction const fee = { amount: [coin("10000", "uusdrise")], gas: "400000", // Gas limit }; const memo = "Created position via @sunriselayer/client"; console.log("Broadcasting transaction..."); const { transactionHash } = await client.signAndBroadcast( senderAddress, [msg], fee, memo ); console.log("Successfully created position!"); console.log("Transaction hash:", transactionHash); } main().catch(console.error); ``` All methods are fully typed when using TypeScript. ## Rust SDK (Coming Soon) The Rust SDK is currently implemented through protobuf generation. Here's how to set it up: ### Project Structure ``` my-sunrise-client/ ├── src/ │ └── main.rs ├── buf.yaml └── buf.gen.yaml ``` ### Configuration Files 1. `buf.yaml`: ```yaml version: v2 deps: - buf.build/cosmos/cosmos-sdk - buf.build/cosmos/cosmos-proto - buf.build/cosmos/gogo-proto - buf.build/protocolbuffers/wellknowntypes ``` 2. `buf.gen.yaml`: ```yaml version: v2 managed: enabled: true plugins: - remote: buf.build/community/neoeinstein-prost:v0.4.0 out: src opt: - compile_well_known_types - extern_path=.google.protobuf=::pbjson_types - remote: buf.build/community/neoeinstein-prost-serde:v0.3.1 out: src - remote: buf.build/community/neoeinstein-tonic:v0.4.1 out: src opt: - compile_well_known_types - extern_path=.google.protobuf=::pbjson_types inputs: - git_repo: https://github.com/sunriselayer/sunrise.git branch: main subdir: proto ``` ### Setup and Generation ```bash # Add required dependencies cargo add tonic tonic-build pbjson-types # Update dependencies and generate code buf dep update buf generate ``` ### Example Usage ```rust use tonic::transport::Channel; use sunriselayer::sunrise::da::v1::query_client::QueryClient; use sunriselayer::sunrise::da::v1::ParamsRequest; #[tokio::main] async fn main() -> anyhow::Result<()> { let mut client = QueryClient::connect("http://localhost:9090").await?; let resp = client.params(ParamsRequest {}).await?; println!("DA params: {:?}", resp.into_inner()); Ok(()) } ``` ## Additional Resources * [Full JavaScript Method Reference](https://github.com/SunriseLayer/gitbook/blob/main/build/client/reference/README.md) * [Rollup Integration Examples](/build/l2-blockchains) * [Data Availability Proofs](/build/validators) ## Troubleshooting | Problem | Solution | | -------------------- | ---------------------------------------------------------- | | Connection refused | Verify RPC URL and ensure DA node is running | | Authentication error | Ensure account has sufficient funds | | Rust build failure | Update to Rust 1.74+ and run `cargo clean && buf generate` | # Networks This section provides details about the official networks operated by the Sunrise Layer team. * [Mainnet](/run-a-sunrise-node/networks/mainnet) * [Testnet](/run-a-sunrise-node/networks/testnet) # Mainnet The main network of Sunrise. Use tokens with real value. ## Mainnet Details [sunrise-1 Network Configuration](https://github.com/sunriselayer/network/tree/main/sunrise-1) [genesis file](https://github.com/sunriselayer/network/blob/main/sunrise-1/genesis.json) [Snapshot (Provided by Polkachu)](https://www.polkachu.com/tendermint_snapshots/sunrise) | Detail | Value | | ------ | ---------------------------------------------------- | | RPC | | | REST | | ## Third-party Services In addition to the official endpoints, several third parties provide public endpoints and other services for the Sunrise mainnet. For a more comprehensive list of RPC, REST, gRPC endpoints, and explorers, please refer to the [Chain Registry](https://github.com/cosmos/chain-registry/blob/master/sunrise/chain.json). | Provider | Node Services (Snapshot, Peers, etc.) | | ------------- | -------------------------------------------------- | | Polkachu | | | NodeStake | | | Krews | | | MekongLabs | | | Synergy Nodes | | ## Frontend | Name | URL | | ------------------- | ----------------------------------- | | APP (Tx Portal) | | | Risescan (Explorer) | | ## Mainnet Software Please check our proposals and community. See [sunrise-1](https://github.com/sunriselayer/network/tree/main/sunrise-1) for setup. The genesis binary is `v1.0.0`. [Released Binary](https://github.com/sunriselayer/sunrise/releases) ### Network Upgrade | Name | Height | | --------------------------------------------------------------------- | ------ | | [v1.1.0](https://github.com/sunriselayer/sunrise/releases/tag/v1.1.0) | 234700 | | [v1.2.0](https://github.com/sunriselayer/sunrise/releases/tag/v1.2.0) | 765000 | ## IBC Config | Dst Chain | Dst Port | Dst Channel | Src Chain | Src Port | Src Channel | | ------------- | ---------- | ------------ | ----------- | ---------- | ----------- | | `noble-1` | `transfer` | channel-168 | `sunrise-1` | `transfer` | channel-0 | | `cosmoshub-4` | `transfer` | channel-1421 | `sunrise-1` | `transfer` | channel-1 | ## IBC Denom | Name | Chain | Original Denom | IBC denom | Decimals | | ---- | ------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------- | | USDN | `noble-1` | `uusdn` | `ibc/A7AD825A4B48DDA0138D118655E60100D22A4D690C45B95221520B58C9A64B63` | 6 | | USDC | `noble-1` | `uusdc` | `ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5` | 6 | | USDY | `noble-1` | `ausdy` | `ibc/AAF322A78A0E34B76CDA05BA9AE96DC1521F9E103EC576AB9931116B2AB8C26B` | 18 | | ATOM | `cosmoshub-4` | `uatom` | `ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9` | 6 | | USDT | `cosmoshub-4` | `ibc/E7E51FFF94A8B55BE84CEB0345E5CAF0A5DAEB374C6806CE908098B8996C7782` | `ibc/D4FF12988C31AD8E3D2555621F95C7EB2B6FBAAD2F9487FB11A2A8BBB004B4B3` | 6 | | WBTC | `cosmoshub-4` | `ibc/D742E8566B0B8CC8F569D950051C09CF57988A88F0E45574BFB3079D41DE6462` | `ibc/0E293A7622DC9A6439DB60E6D234B5AF446962E27CA3AB44D0590603DFF6968E` | 8 | | WETH | `cosmoshub-4` | `ibc/C0B53D3D23827AE38058BED0BDCD554229278AF530A8D265FCF6DFF7C4B2ADFF` | `ibc/694A6B26A43A2FBECCFFEAC022DEACB39578E54207FDD32005CD976B57B98004` | 18 | ## Mint USDrise from USDN on Mainnet The address of the contract to mint USDrise is `sunrise14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9s2v9j75`. You can mint the same amount of USDrise using USDN. ```bash sunrised tx wasm execute sunrise14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9s2v9j75 \ '{"mint":{"amount":"1000000","recipient":"[your-address]"}}' \ --amount 1000000ibc/A7AD825A4B48DDA0138D118655E60100D22A4D690C45B95221520B58C9A64B63 \ --from=[your-account] --chain-id=sunrise-1\ --gas-prices=0.025uusdrise --gas-adjustment=1.5 --gas=auto -y ``` ## Redeem USDrise to USDN on Mainnet The address of the contract to redeem USDrise to USDN is `sunrise14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9s2v9j75`. You can redeem the same amount of USDN using USDrise. ```bash sunrised tx wasm execute sunrise14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9s2v9j75 \ '{"burn":{"amount":"1000000"}}' \ --amount 1000000uusdrise \ --from=[your-account] --chain-id=sunrise-1 \ --gas-prices=0.025uusdrise --gas-adjustment=1.5 --gas=auto -y ``` # Testnet ## Dawn Testnet {% hint style="warning" %} **Important**: This is a testnet. Tokens on this network are for testing purposes only and have no real-world value. The network state may be reset at any time for bug fixes or upgrades, and its persistence is not guaranteed. {% endhint %} This network is used to test some functions on the mainnet. ### Dawn Testnet Details [dawn-1 Network Details](https://github.com/sunriselayer/network/tree/main/dawn-1) | Detail | Value | | ------ | ----------------------------------------- | | RPC | | | REST | | ### Dawn Testnet Frontend | Name | URL | | -------------------- | ----------------------------------------- | | Dawn APP (Tx Portal) | | | Risescan (Explorer) | | ### Dawn Testnet Software Please check our proposals and community. See [dawn-1 Github](https://github.com/sunriselayer/network/tree/main/dawn-1) for setup. [Released Binary](https://github.com/sunriselayer/sunrise/releases) ### Dawn Testnet Faucet RISE & USDrise faucet is available for Dawn testnet. This faucet is provided within the Dawn APP. To use it, it must be signed in a wallet that has at least 0.01 ETH on the Ethereum mainnet. No cost. ### Mint USDrise from USDN on Dawn Testnet The address of the contract to mint USDrise is `sunrise1suhgf5svhu4usrurvxzlgn54ksxmn8gljarjtxqnapv8kjnp4nrs4ef8ka`. You can mint the same amount of USDrise using USDN. ```bash sunrised tx wasm execute sunrise1suhgf5svhu4usrurvxzlgn54ksxmn8gljarjtxqnapv8kjnp4nrs4ef8ka \ '{"mint":{"amount":"1000000","recipient":"[your-address]"}}' \ --amount 1000000ibc/A7AD825A4B48DDA0138D118655E60100D22A4D690C45B95221520B58C9A64B63 \ --from=[your-account] --gas-prices=0.025uusdrise --gas-adjustment=1.2 --gas=auto -y ``` ### IBC Config on Dawn Testnet | Dst Chain | Dst Port | Dst Channel | Src Chain | Src Port | Src Channel | | ---------- | ---------- | ------------- | --------- | ---------- | ----------- | | `grand-1` | `transfer` | `channel-554` | `dawn-1` | `transfer` | `channel-0` | | `provider` | `transfer` | `channel-493` | `dawn-1` | `transfer` | `channel-1` | `grand-1` is current Noble testnet [Grand-1 Testnet](https://www.noble.xyz/dev-hub) [Noble Testnet chain-registry](https://github.com/cosmos/chain-registry/tree/master/testnets/nobletestnet) `provider` is current CosmosHub testnet [Cosmos ICS Provider Testnet](https://hub.cosmos.network/main/hub-tutorials/join-testnet) [provider chain-registry](https://github.com/cosmos/chain-registry/tree/master/testnets/cosmosicsprovidertestnet) ## IBC Denom on Dawn Testnet | Name | Chain | Original Denom | IBC denom | | ---- | ---------- | -------------- | ---------------------------------------------------------------------- | | USDN | `grand-1` | `uusdn` | `ibc/A7AD825A4B48DDA0138D118655E60100D22A4D690C45B95221520B58C9A64B63` | | USDC | `grand-1` | `uusdc` | `ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5` | | ATOM | `provider` | `uatom` | `ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9` | ## Deprecated Testnets ### DA Testnet {% hint style="warning" %} `sunrise-test-da-1`, `sunrise-test-da-2`, `sunrise-test-da-3`, `sunrise-test-da-4`, `sunrise-test-da-5` is deprecated. Please use `dawn-1` instead. {% endhint %} This network is used to test Data Availability functions on the mainnet. ### Incentivized Testnet 0.2 {% hint style="warning" %} **IMPORTANT**: This testnet is closed on May 21, 2025 at 0:00 UTC. Currently only the DA 3 Testnet is running. {% endhint %} This network is used to test operations on the mainnet. Normally, the same environment as the mainnet is provided, but tokens have no value. ### Incentivized Testnet 0.2 Details [sunrise-test-0.2 Network Details](https://github.com/sunriselayer/network/tree/main/sunrise-test-0.2) | Detail | Value | | ------ | ------------------------------------------------ | | RPC | | | REST | | In some cases b-d is also in operation; check with [RiseScan](https://testnet.risescan.sunriselayer.io/). ### Incentivized Testnet 0.2 Software Please check our proposals and community. See [sunrise-test-0.2](https://github.com/sunriselayer/network/tree/main/sunrise-test-0.2) for setup. Currently, Testnet uses v0.2.x binaries for blockchain compatibility. [Released Binary](https://github.com/sunriselayer/sunrise/releases) # Types of Nodes There are many ways you can participate in the Sunrise [networks](/run-a-sunrise-node/networks). Sunrise node operators can run several options on the network. ## Consensus * [Validator node](/run-a-sunrise-node/types/consensus/validator-node): This type of node participates in consensus by producing and voting on blocks. * [Full consensus node](/run-a-sunrise-node/types/consensus/full-consensus-node): A sunrise-app Full node to sync blockchain history. ## Requirements | Type | CPU | Architecture | Mem | Disk | Bandwidth | | -------------- | ------ | ------------ | ---- | ---------- | --------- | | Validator | 6 Core | x86\_64 | 8 GB | 500 GB SSD | 1 Gbps | | Full Consensus | 4 Core | x86\_64 | 8 GB | 250 GB SSD | 1 Gbps | You can learn more about how to set up each different node by going through each tutorial guide. # Consensus ## Overview * [Validator node](/run-a-sunrise-node/types/consensus/validator-node): This type of node participates in consensus by producing and voting on blocks. * [Full consensus node](/run-a-sunrise-node/types/consensus/full-consensus-node): A sunrise-app Full node to sync blockchain history. {% hint style="info" %} **Data Availability Layer**: In addition to standard consensus tasks, Validator Nodes on Sunrise are responsible for verifying data for the Data Availability (DA) layer. This requires running additional daemons alongside the main `sunrised` process. See the [validator documentation](/build/validators) for more details. {% endhint %} ### Requirements | Type | CPU | Architecture | Mem | Disk | Bandwidth | | -------------- | ------ | ------------ | ---- | ---------- | --------- | | Validator | 6 Core | x86\_64 | 8 GB | 500 GB SSD | 1 Gbps | | Full Consensus | 4 Core | x86\_64 | 8 GB | 250 GB SSD | 1 Gbps | # Full Consensus Node Full consensus nodes allow you to sync blockchain history in the Sunrise consensus layer. ## Chain upgrades For streamline chain upgrades and minimize downtime, you may want to set up [Cosmovisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) to manage your node. Follow [Cosmovisor tutorial](/run-a-sunrise-node/types/consensus/setup-cosmovisor) To automate on-chain upgrades, set the following options. ```yml DAEMON_ALLOW_DOWNLOAD_BINARIES=true ``` ## Backups If you are using a recent version of Cosmovisor, then the default configuration is that a state backup will be created before upgrades are applied. This can be turned off using [environment flags](https://docs.cosmos.network/main/build/tooling/cosmovisor#command-line-arguments-and-environment-variables). ## Alerting and monitoring Alerting and monitoring are desirable as well - you are encouraged to explore solutions and find one that works for your setup. Prometheus is available out-of-the-box, and there are a variety of open-source tools. ## Hardware requirements The following hardware minimum requirements are recommended for running the validator node: * Memory: 8 GB RAM (minimum) * CPU: 4 cores * Disk: 250 GB SSD Storage * Bandwidth: 1 Gbps for Download/1 Gbps for Upload If you are not using pruning, you are running an archive node, and it is recommended to have 500 GB of SSD storage. ## Dependencies The tutorial is done on Ubuntu 22.04 (LTS). Follow [the environment tutorial](/run-a-sunrise-node/resources/environment) ## Run the full consensus node ### Install [Install Go](https://go.dev/doc/install) 1.24.2 ```bash git clone https://github.com/sunriselayer/sunrise.git cd sunrise git checkout $TAG make install ``` {% hint style="info" %} When synchronizing from the genesis, use the binary version as of the genesis. If you are using snapshots, you must check the height of the snapshot and use the binary at that height. See [upgrade doc](/run-a-sunrise-node/resources/upgrade) for more details. {% endhint %} ### Initialize Set `chain-id` & `moniker`. `moniker` is just a name for your node. ```bash CHAIN_ID=sunrise-1 // mainnet MONIKER="node-name" sunrised init "$MONIKER" --chain-id $CHAIN_ID ``` This will generate the following files in `~/.sunrise/config/` * `genesis.json` * `node_key.json` * `priv_validator_key.json` ## Download the genesis file Check the `genesis.json` of the currently running network on [our Github](https://github.com/sunriselayer/network) Example: For mainnet: ```bash rm ~/.sunrise/config/genesis.json curl -L https://raw.githubusercontent.com/sunriselayer/network/main/sunrise-1/genesis.json -o ~/.sunrise/config/genesis.json ``` ### Set minimum gas prices For RPC nodes and Validator nodes, we recommend setting the following minimum-gas-prices. As we are a permissionless wasm chain, this setting will help protect against contract spam and potential wasm contract attack vectors. In `$HOME/.sunrise/config/app.toml`, set minimum gas prices: ```bash sed -i.bak -e "s/^minimum-gas-prices *=.*/minimum-gas-prices = \"0.025uusdrise\"/" $HOME/.sunrise/config/app.toml ``` {% hint style="warning" %} Do NOT set too high gas prices. If you are a validator, your proposed block will not include transactions. This reduces the number of transactions the entire network can process. {% endhint %} ### Option: Set seeds & persistent peers * Seeds "Seeds" provides a list of other validators that a newly joining validator should initially connect to. Once a validator connects to the network, it primarily relies on `persistent_peers` for connections, reducing the importance of `seeds`. ```bash SEEDS=$(curl -sL https://raw.githubusercontent.com/sunriselayer/network/main/sunrise-1/seeds.txt | tr '\n' ',') echo $SEEDS sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/.sunrise/config/config.toml ``` * Persistent Peers "Persistent Peers" is a list of trusted validators that the validator should maintain connections with at all times. Connections to validators listed in persistent\_peers are prioritized to maintain network stability. ```bash PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/sunriselayer/network/main/sunrise-1/peers.txt | tr '\n' ',') echo $PERSISTENT_PEERS sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/.sunrise/config/config.toml ``` ### Option: Additional settings If necessary, Edit config files `$HOME/.sunrise/config/app.toml` * Enable defines if the API server should be enabled. ```bash sed -i '/\[api\]/,+3 s/enable = false/enable = true/' $HOME/.sunrise/config/app.toml; ``` * EnableUnsafeCORS defines if CORS should be enabled (unsafe - use it at your own risk). ```bash sed -i 's/enabled-unsafe-cors = false/enabled-unsafe-cors = true/' $HOME/.sunrise/config/app.toml; ``` * By default, RPC and REST are not public, so if you want to make it a public node, configure as follows ```bash sed -i 's/address = "localhost:9090"/address = "0.0.0.0:9090"/' $HOME/.sunrise/config/app.toml; sed -i 's#address = "tcp://localhost:1317"#address = "tcp://0.0.0.0:1317"#' $HOME/.sunrise/config/app.toml; sed -i 's#laddr = "tcp://127.0.0.1:26657"#laddr = "tcp://0.0.0.0:26657"#' $HOME/.sunrise/config/config.toml; ``` ### Storage and pruning configurations If your consensus node is being connected to a sunrise-node bridge node, you will need to enable transaction indexing and retain all block data. This can be achieved with the following settings in `config.toml`. #### Enable transaction indexing ```toml indexer = "kv" ``` #### Retain all block data And in `app.toml`, `min-retain-blocks` should remain as the default setting: ```toml min-retain-blocks = 0 ``` #### Accessing historical state If you want to query the historical state — for example, you might want to know the balance of a wallet at a given height in the past — you should run an archive node with `pruning = "nothing"` in `app.toml`. Note that this configuration is resource-intensive and will require significant storage: ```toml pruning = "nothing" ``` If you want to save on storage requirements, consider using `pruning = "everything"` in app.toml to prune everything. ```toml pruning = "everything" ``` ### Create (or restore) a local key pair Either create a new key pair or restore an existing wallet for your validator: ```bash # Create new keypair sunrised keys add # Restore existing sunrise wallet with mnemonic seed phrase. # You will be prompted to enter mnemonic seed. sunrised keys add --recover # Query the keystore for your public address sunrised keys show -a ``` Replace `` with a key name of your choosing. ### Get some RISE tokens You will require some vRISE tokens to bond to your validator (and some RISE tokens for fees). To be in the active set you will need to have enough tokens. ### Start the consensus node Follow the instructions to set up Cosmovisor and start the node. See [Cosmovisor tutorial](/run-a-sunrise-node/types/consensus/setup-cosmovisor) {% hint style="info" %} Using cosmovisor is completely optional. If you choose not to use cosmovisor, you will need to be sure to attend network upgrades to ensure your validator does not have downtime and get jailed. {% endhint %} If you are not using Cosmovisor, run the following: ```bash sunrised start ``` ### Syncing the node After starting the `sunrised` daemon, the chain will begin to sync to the network. The time to sync to the network will vary depending on your setup and the current size of the blockchain but could take a very long time. To query the status of your node: ```bash # Query via the RPC (default port: 26657) curl http://localhost:26657/status | jq .result.sync_info.catching_up ``` This command returning `true` means that your node is still catching up. Otherwise, your node has caught up to the network's current block and you are safe to proceed to upgrade to a validator node. If you want to shorten the time to catch up to the latest block, consider using snapshots from other nodes. ### Option: Use a snapshot If you want to shorten the time to catch up to the latest block, consider using snapshots. Snapshots allow a node to be bootstrapped from a specific height, reducing the need to sync from genesis. Our partner at [Polkachu](https://www.polkachu.com/tendermint_snapshots/sunrise) provides daily snapshots for the Sunrise network. Please visit their website to get the latest snapshot URL. # Validator Node (Genesis) Validator nodes allow you to participate in consensus in the Sunrise network. {% hint style="info" %} You can only join as a validator in this way before the network starts(genesis). If the network has already started, please see [this tutorial](/run-a-sunrise-node/types/consensus/validator-node). {% endhint %} ## Hardware requirements The following hardware minimum requirements are recommended for running the validator node: * Memory: 8 GB RAM (minimum) * CPU: 6 cores * Disk: 500 GB SSD Storage * Bandwidth: 1 Gbps for Download/1 Gbps for Upload ## Run the Node First, follow the instructions on [setting up a full consensus node](/run-a-sunrise-node/types/consensus/full-consensus-node). ### Optional: Reset working directory If you have already initialized a working directory for sunrised in the past, you must clean up before reinitialized a new directory. You can do so by running the following command: ```bash sunrised tendermint unsafe-reset-all ``` ### Initialize a working directory Check [our Github](https://github.com/sunriselayer/network) to know the current `chain-id` and run the following command: ```bash CHAIN_ID=sunrise-1 MONIKER="validator-name" sunrised init "$MONIKER" --chain-id $CHAIN_ID ``` Change `genesis.json` to the one in the network repository. ```bash wget https://raw.githubusercontent.com/sunriselayer/network/main/sunrise-1/gentx/genesis.json cp genesis.json $HOME/.sunrise/config/genesis.json ``` ### Create a new key ```bash VALIDATOR_WALLET="validator" sunrised keys add $VALIDATOR_WALLET --keyring-backend test ``` ### Create the genesis transaction for new chain ```bash STAKING_AMOUNT=1000000uvrise sunrised genesis gentx $VALIDATOR_WALLET $STAKING_AMOUNT --chain-id $CHAIN_ID \ --pubkey=$(sunrised tendermint show-validator) \ --moniker=$MONIKER \ --commission-rate=0.1 \ --commission-max-rate=0.2 \ --commission-max-change-rate=0.01 \ --min-self-delegation=1 \ --keyring-backend test ``` You will find the generated gentx JSON file inside `$HOME/.sunrised/config/gentx/gentx-*.json` ### Create Pull Request to register your gentx To register your gentx, create a pull-request to the [network repository](https://github.com/sunriselayer/network/tree/main/sunrise-1/gentx). # Validator Node Validator nodes allow you to participate in consensus in the Sunrise network. ## Hardware requirements The following hardware minimum requirements are recommended for running the validator node: * Memory: 8 GB RAM (minimum) * CPU: 6 cores * Disk: 500 GB SSD Storage * Bandwidth: 1 Gbps for Download/1 Gbps for Upload ## Run the Node First, follow the instructions on [setting up a full consensus node](/run-a-sunrise-node/types/consensus/full-consensus-node). ### Optional: Reset working directory If you have already initialized a working directory for sunrised in the past, you must clean up before reinitialized a new directory. You can do so by running the following command: ```bash sunrised tendermint unsafe-reset-all ``` ### Initialize a working directory Run the following command: ```bash CHAIN_ID=sunrise-1 # For mainnet MONIKER="validator-name" sunrised init "$MONIKER" --chain-id $CHAIN_ID ``` Check [our Github](https://github.com/sunriselayer/network) to know the current chain-id. ### Create a new key ```bash VALIDATOR_WALLET="validator" sunrised keys add $VALIDATOR_WALLET --keyring-backend test ``` ### Validator Public Key The last thing needed before initializing the validator is to obtain your validator public key which was created when you first initialized your node. To obtain your validator pubkey: ```bash sunrised tendermint show-validator {"@type":"/cosmos.crypto.ed25519.PubKey","key":"ZQweivhEkT/akg5RT6RWkElt43rr5cf+qu/QQ5jOpmQ="} ``` ### Create Validator A minimum of 1 vRISE is required to create a validator. vRISE is non-transferable, so if you have no balance in your account, please create a position in the Liquidity Pool to earn vRISE. First, create validator config file \[\~/.sunrise/config/validator.json]. ```json { "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"ZQweivhEkT/akg5RT6RWkElt43rr5cf+qu/QQ5jOpmQ="}, "amount": "1000000uvrise", "moniker": "your_validator's_name", "identity": "optional identity signature (ex. UPort or Keybase)", "website": "validator's (optional) website", "security": "validator's (optional) security contact email", "details": "validator's (optional) details", "commission-rate": "0.1", "commission-max-rate": "0.2", "commission-max-change-rate": "0.01", "min-self-delegation": "1" } ``` Next, run the following command ```bash sunrised tx staking create-validator [path/to/validator.json] \ --chain-id=$CHAIN_ID \ --from=$VALIDATOR_WALLET \ --keyring-backend=test \ --gas-prices=0.025uusdrise --gas-adjustment 1.2 \ --gas=auto \ -y ``` ## Backup There are certain files that you need to backup to be able to restore your validator if, for some reason, it is damaged or lost in some way. Please make a secure backup of the following files located in `~/.sunrise/config/`: * `priv_validator_key.json` * `node_key.json` It is recommended that you encrypt the backup of these files. ## Additional incentives for validators {% hint style="warning" %} The application period for "Additional incentives for validators" closed on October 15th, 2025. The reopening date is undecided. For those who have already registered in the chain-registry and meet the requirements, the delegation has been completed. Due to the depletion of the funding pool for the program, fulfilling the requirements now (e.g., enabling the tx indexer) will not make you eligible for additional delegation. Please be aware of this. {% endhint %} The core team will delegate more RISE to validators who serve the following services: ### RPC/API/gRPC * **Delegation Amount:** 250,000 RISE for each service (RPC, API, gRPC), up to a maximum of 750,000 RISE. * **Conditions:** * Your endpoint must be submitted via a pull request to [chain-registry](https://github.com/cosmos/chain-registry/blob/master/sunrise/chain.json) and get merged. * Transaction indexer and CORS must be enabled. ### Explorer * **Delegation Amount:** 25,000 RISE. * **Conditions:** * Your explorer must be submitted via a pull request to [chain-registry](https://github.com/cosmos/chain-registry/blob/master/sunrise/chain.json) and get merged. * **Additional Delegation:** * We offer additional delegation if your explorer is used within the official Sunrise services. We will contact you individually. Please note that the content of these incentives may change depending on the number of participants. # Setup Cosmovisor **For mainnet, it's recommended to use Cosmovisor to run your node.** Setting up Cosmovisor is relatively straightforward. However, it does expect certain environment variables and folder structure to be set.\ Cosmovisor allows you to download binaries ahead of time for chain upgrades, meaning that you can do zero (or close to zero) downtime chain upgrades. It's also useful if your local timezone means that a chain upgrade will fall at a bad time.\ Rather than having to do stressful ops tasks late at night, it's always better if you can automate them away, and that's what Cosmovisor tries to do. ## Install First, go and get cosmovisor (recommended approach): ```bash # to target a specific version: go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v1.0.0 ``` ### Add environment variables to your shell Some environment variables must be set to appropriate values for each node and each network. ```bash echo "export DAEMON_NAME=sunrised" >> ~/.profile echo "export DAEMON_HOME=$HOME/.sunrised" >> ~/.profile echo "export DAEMON_ALLOW_DOWNLOAD_BINARIES=true" >> ~/.profile echo "export DAEMON_LOG_BUFFER_SIZE=512" >> ~/.profile echo "export DAEMON_RESTART_AFTER_UPGRADE=true" >> ~/.profile echo "export UNSAFE_SKIP_BACKUP=true" >> ~/.profile ``` Then source your profile to have access to these variables: ```bash source ~/.bash_profile ``` ### Set up folder structure ```bash mkdir -p $DAEMON_HOME/cosmovisor mkdir -p $DAEMON_HOME/cosmovisor/genesis mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin mkdir -p $DAEMON_HOME/cosmovisor/upgrades ``` ### Set up genesis binary Cosmovisor needs to know which binary to use at genesis. We put this in `$DAEMON_HOME/cosmovisor/genesis/bin` Check [our Github](https://github.com/sunriselayer/network) to know the binary version of genesis. ```bash wget https://github.com/sunriselayer/sunrise/releases/download//sunrised cp sunrised $DAEMON_HOME/cosmovisor/genesis/bin ``` ### Set up service Commands sent to Cosmovisor are sent to the underlying binary. For example, `cosmovisor version` is the same as typing `sunrised version`. Nevertheless, just as we would manage `sunrised` using a process manager, we would like to make sure Cosmovisor is automatically restarted if something happens, for example, an error or reboot. First, create the service file: ```bash sudo vi /lib/systemd/system/cosmovisor.service ``` Change the contents of the below to match your setup ```bash [Unit] Description=Cosmovisor daemon After=network-online.target [Service] Environment="DAEMON_NAME=sunrised" Environment="DAEMON_HOME=$DAEMON_HOME" Environment="DAEMON_RESTART_AFTER_UPGRADE=true" Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true" // Recommend Environment="DAEMON_LOG_BUFFER_SIZE=512" Environment="UNSAFE_SKIP_BACKUP=true" User=$USER ExecStart=${HOME}/go/bin/cosmovisor start Restart=always RestartSec=3 LimitNOFILE=infinity LimitNPROC=infinity [Install] WantedBy=multi-user.target ``` {% hint style="info" %} A description of what the environment variables do can be found [here](https://docs.cosmos.network/main/run-node/cosmovisor.html). Change them depending on your setup. {% endhint %} ### Start Cosmovisor {% hint style="warning" %} If syncing from a snapshot, do not start Cosmovisor yet. Download the snapshot and extract it to `$HOME/.sunrise/data`. Finally, enable the service and start it. {% endhint %} ```bash sudo systemctl daemon-reload sudo systemctl restart systemd-journald sudo systemctl enable cosmovisor sudo systemctl start cosmovisor ``` Check it is running using: ```bash sudo systemctl status cosmovisor ``` If you need to monitor the service after launch, you can view the logs using: ```bash sudo journalctl -u cosmovisor -f -o cat ``` # IBC Relayers By setting up the IBC relayer, you can create new connections and channels of IBC between Sunrise and other blockchains. ## Setting up relayer with Go relayer (Deprecated) You can see details [here](https://github.com/cosmos/relayer). First, install [Go](https://go.dev/doc/install) ## Setting up relayer with Rust relayer Hermes (Recommended) You can see details [here](http://hermes.informal.systems). First, install [Rust](https://www.rust-lang.org/tools/install) Then, run the commands below: ```bash sudo apt update && sudo apt upgrade -y sudo apt install librust-openssl-dev build-essential git -y cargo install ibc-relayer-cli --bin hermes --locked hermes version echo word1 ... word12or24 > ~/mnemonic.txt ``` ### Setup accounts First, you need a wallet with enough funds on both chains. This tutorial assumes that you already have wallets created on the chains you want to relay on, and that these wallets have funds allocated to each of them. ```bash hermes keys add --key-name --chain --mnemonic-file mnemonic.txt hermes keys add --key-name --chain --mnemonic-file mnemonic.txt ``` ### Configuration file The command hermes config auto provides a way to automatically generate a configuration file for chains in the [chain-registry](https://github.com/cosmos/chain-registry): You must set each parameter yourself for the testnet. See the [documentation](https://hermes.informal.systems/documentation/configuration/index.html) for more details. ```bash hermes config auto --output $HOME/.hermes/config.toml --chain : : --chain ``` #### Add a new relay path The following settings are not required for mainnets that already have an established IBC channel. Follow only if you are starting a new connection. * Create a connection First, create a client on `ibc-1` tracking the state of `ibc-0`. It will be assigned 07-tendermint-0 as its identifier: ```bash hermes create client --host-chain --reference-chain ``` * Create a connection After creating clients on both chains, you have to establish a connection between them. Both chains will assign connection-0 as the identifier of their first connection: ```bash hermes create connection --a-chain --b-chain ``` If the command runs successfully, it should output the `connection ID`. * Channel identifiers Finally, after the connection has been established, you can now open a new channel on top of it. Both chains will assign channel-0 as the identifier of their first channel: ```bash hermes create channel --a-chain --a-connection --a-port transfer --b-port transfer ``` If the command runs successfully, it should output the channel IDs of both chains. Add these to `.hermes/config.toml` ```yml [chains.packet_filter] policy = "allow" list = [[ "transfer", "channel-0", ]] ``` Once the configuration is complete, you can start the relayer with the following command. ```bash hermes start ``` ### Setting up daemon Recommend setting SystemD to run automatically after reboot. ```bash sudo tee /etc/systemd/system/hermes.service > /dev/null < ## Mainnet When synchronizing chains from the genesis, follow this guide and use the binary version current at the time of the genesis. For the currently used binary version, please refer to the latest release on [GitHub](https://github.com/sunriselayer/sunrise/releases). # Environment This is development environment to run Sunrise software. This environment can be used for development, building binaries, and running nodes. ## Install Dependencies ### Ubuntu ```bash sudo apt update sudo apt install -y tar wget aria2 clang pkg-config libssl-dev jq build-essential git make ncdu ``` ### Install Golang Install Golang ```bash wget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz rm go1.24.2.linux-amd64.tar.gz echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.bashrc source $HOME/.bashrc ``` Check Go version ```bash go version ```