# What is Lumia Chain?

Lumia is the first next-gen, ultra capital efficient, hyper-liquid zkEVM utilizing cutting edge tech stack: PolygonCDK, AvailDA and (redundancy) private DAC, Polygon AggLayer, Gevolut, custom AVS', Chain Abstraction, Account Abstraction and more, thanks to co-development efforts between GatewayFM (RaaS) and Lumia's tech team.&#x20;

Lumia will boast its own custom redundancy Data Availability Committee (DAC), its own liquidity network via Lumia Stream, decentralised sequencers, decentralised zkProvers, fast finality and validity proofs for a secure and decentralised Web3 experience.&#x20;

This document will dive into each component on what makes up Lumia and how it enables it to be positioned uniquely while addressing some of the key friction points plaguing this space such as scalability, liquidity fragmentation, thin liquidity, lack of interoperability and sustainable tokenomics.


# CDK

Polygon Chain Development Kit (CDK) is a versatile, open-source software toolkit designed to empower blockchain developers with the ability to deploy and configure a wide range of chain architectures. With Polygon CDK, we are able to effortlessly launch Lumia L2 chain powered by Polygon zkEVM technology.

One of the key strengths of Polygon CDK lies in its flexibility. Thus, gives us the freedom to choose a chain architecture that aligns perfectly with our specific requirements from a curated set of supported, open-source components. Polygon CDK supports two primary configuration options: zkEVM rollups and validiums. zkEVM rollups seamlessly post transaction data from Polygon CDK i.e. Lumia L2 directly onto the Ethereum blockchain while validiums optimize storage by posting only transaction hashes and storing the actual transaction data off-chain. In Lumia L2 we swap out validium to EigenDA for a much more decentralised architecture in general.

Polygon CDK brings a host of features that will significantly benefit the development and scaling of Lumia L2:

1. **Modularity and sovereignty**: Polygon CDK provides a modular environment for designing ZK-powered L2 chains, empowering Lumia team to customize chain according to our specific needs.
2. **Scalability**: Lumia L2 chain developed using Polygon CDK offers enhanced transaction speed and can be multiplied to create an elastically scalable ecosystem.
3. **Independent data availability**: Polygon CDK features a dedicated data availability layer and a data availability committee, ensuring robust off-chain data access and reliability. This structure, operating independently of Ethereum, guarantees substantial data resilience and integrity. Although in Lumia L2 we will not leverage this feature as we will plug in and integrate EigenDA.
4. **Interoperability (forthcoming)**: Through an in-development interoperability layer, AggLayer, Lumia L2 will enable seamless atomic L2 <> L2 transactions. Lumia coupled with native Lumia Stream will tap into vast range of cross-chain options.
5. **Near-instant finality**: By relying on cryptographic security, Lumia L2 using Polygon CDK ensures transaction integrity without the need for full nodes. This approach guarantees near-instant finality and robust security.
6. **Extensive Web3 support**: Polygon CDK chains benefit from a comprehensive ecosystem with premium service providers offering essential tools for application integration, development, and deployment.

In summary, Polygon CDK is a game-changing toolkit that empowers developers to build and scale innovative L2 chains, such as Lumia L2, with unparalleled flexibility, scalability, and interoperability. By leveraging the power of Polygon zkEVM technology and the robust features of Polygon CDK, Lumia L2 is poised to revolutionize the blockchain landscape and unlock new possibilities for developers and users alike.


# AggLayer

Seamlessly connect any ZK-enabled L2 or L1 chain for near-instant cross-chain transactions, and shared state and liquidity across chains.

Addressing the scalability challenge in blockchains goes beyond individual chain performance; it necessitates scaling access to shared state and liquidity across multiple chains. This calls for a groundbreaking approach to blockchain architecture known as aggregated blockchains. The visionary team at Polygon Labs has developed an ingenious solution – the **aggregation layer**, or **AggLayer** – which is set to revolutionize the way ZK-enabled L2 or L1 chains interact. By seamlessly connecting these chains, AggLayer enables near-instant cross-chain transactions, allowing for the effortless sharing of state and liquidity across multiple chains. This transformative technology promises to unlock unprecedented scalability, interoperability, and liquidity, ushering in a new era of blockchain innovation and empowering developers to build the decentralized applications of the future.


# Passport

Empowering Secure and Privacy-Centric Relationships between Apps and Users

Privado ID is a powerful suite of developer tools designed to facilitate trusted and secure relationships between applications and users. By leveraging Privado ID, developers can enable the exchange of verifiable credentials that are protected by robust cryptography and the blockchain. With a strong emphasis on privacy, decentralization, and user data self-sovereignty, Privado ID is poised to revolutionize the way digital identities are managed and utilized.

What Sets Privado ID Apart?

1. **Privacy by Default**: Privado ID employs a zero-knowledge native protocol, ensuring that privacy is inherently built into the solution.
2. **No Direct Issuer-Verifier Communication**: Privado ID eliminates the need for direct communication between issuers and verifiers, enhancing privacy and security.
3. **Scalable and Self-Sovereign**: Privado ID offers a scalable and self-sovereign digital identity solution, empowering users with control over their personal data.
4. **On-chain and Off-chain Verification**: Privado ID supports both on-chain and off-chain verification, enabling the deployment of a wide range of Web2 and Web3 use cases.
5. **Efficient Bulk Issuance**: With Privado ID, developers can issue claims in bulk, benefiting from highly efficient on-chain storage at minimal transactional costs.
6. **Transformative Use Cases**: Privado ID enables a wide array of transformative use cases, including protection against Sybil attacks while preserving privacy, non-reusable proofs, and safeguards against digital footprint tracking.

Harnessing the Power of Zero-Knowledge Technology. Privado ID leverages zero-knowledge technology in two key ways:

1. **Preserving Privacy**: With Privado ID, users (Identity Holders) can send proofs of information within a credential to the Verifier (dApp) without revealing the actual information. In Selective Disclosure mode, users can choose which specific information to share, along with a proof of its correctness, without disclosing the entire credential.
2. **Verifying Computations**: Zero-knowledge proofs enable Privado ID to prove that a computation has been performed correctly without requiring the Verifier to recompute it. This is particularly useful for verifying that an identity is executing a state transition correctly.

By combining the power of zero-knowledge technology with a developer-friendly ecosystem, Privado ID is set to redefine the landscape of digital identity management. With its focus on privacy, scalability, and user empowerment, Privado ID provides developers with the tools they need to build secure, trust-based relationships between applications and users, ushering in a new era of digital interactions.


# Architecture

Next-Generation Layer 2 Architecture

Lumia chain is a state-of-the-art roll-up blockchain platform that leverages the power of cutting-edge technologies to deliver a fast, secure, and highly scalable decentralized ecosystem. The architecture of Lumia is designed to maximize capital efficiency, liquidity, and interoperability while providing a seamless user experience.

At the core of Lumia's architecture lies the Polygon CDK (Chain Development Kit), which enables the creation of custom blockchain networks tailored to specific use cases. The Polygon CDK allows Lumia to incorporate various execution environments, such as Privado ID and Miden providing developers with the flexibility to build and deploy a wide range of decentralized applications (dApps).

One of the key components of Lumia is the Lumia Stream, a native liquidity module that aggregates liquidity from both centralized exchanges (CEXs) and decentralized exchanges (DEXs). This unified liquidity pool enables developers to focus on building innovative dApps without worrying about attracting sufficient liquidity. Lumia Stream ensures that users have access to deep liquidity across various assets, enhancing the overall trading experience and facilitating efficient market-making.

To further enhance scalability and interoperability, Lumia integrates with two cutting-edge solutions: AvailDA and Polygon AggLayer. AvailDA is a next-gen decentralized data availability solution that ensures the availability and integrity of transaction data off-chain, reducing the burden on the main Ethereum blockchain. By leveraging AvailDA, Lumia can achieve higher throughput and lower transaction costs while maintaining the security guarantees of the underlying blockchain.

Polygon AggLayer, on the other hand, is a groundbreaking interoperability protocol that enables seamless cross-chain communication and asset transfers. With Polygon AggLayer, Lumia can connect to other blockchains within the AggLayer ecosystem, allowing users to access a wide range of dApps and services across multiple chains. This integration unlocks new possibilities for developers and users alike, fostering a vibrant and interconnected decentralized ecosystem.

Lumia also incorporates advanced features such as Account Abstraction with Chain Abstraction, which simplifies the user experience by abstracting away the complexities of private key management. Chain abstraction coupled with account abstraction, users can interact with dApps using familiar authentication methods, such as email or social media accounts, without compromising the security of their assets.

To ensure the security and decentralization of the network, Lumia is currently in transition phase to decentralize its sequencers. Sequencers are responsible for ordering and processing transactions, and by distributing this role across multiple nodes, Lumia eliminates single points of failure and enhances the resilience of the network. The decentralized sequencer network also contributes to fast finality, allowing transactions to be confirmed quickly and irreversibly. Sequencer network is currently in development and will be readily available Q2-2025.

In addition to the core components, Lumia integrates with custom AVS (Actively Validated Services), which provide additional security and validation capabilities. First AVS service to go live on Lumia will be TheRadius. The AVS system will allow us to tap into blockspace network to protect Lumia users from MEV .

Overall, the architecture of Lumia represents a significant leap forward in the realm of roll-up blockchain platforms. By combining the power of Polygon CDK, Lumia Stream, AvailDA, Polygon AggLayer, Chain and Account Abstraction, decentralized sequencers, decentralized zkProvers and custom AVS', Lumia delivers a highly scalable, interoperable, and user-friendly ecosystem that empowers developers and users to unlock the full potential of decentralized technologies.

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


# Roadmap

**Lumia** is building the financial infrastructure of the future – where real-world assets, liquidity, and decentralized finance are seamlessly interconnected. Our roadmap reflects both near-term execution and long-term vision, and will continue to evolve as technology, regulation, and global markets progress.

We set the following goals for 2025–2026+.

### 2025

* **Q2 2025**
  * Launch of Lumia-powered dApps across real-world asset tokenization, DeFi liquidity, and digital identity solutions.
  * Rollout of Lumia Hub, the tokenization platform for real estate, commodities, and alternative assets.
  * Start of the Lumia Power Campaign, innovative elevated governance through LUMIA staking, long-term lock incentives, legacy migration recognition, and early access to new ecosystem launches and setting a new structural standard for decentralized real-world asset infrastructure.
  * Start of Ecodrops Campaign: ecosystem-driven airdrops tied to project launches, rewarding governance participants with real ownership opportunities across Lumia's expanding network.<br>

* **Q3 2025**
  * Initiation of Stage 2 rollup decentralization - DA layer integration with AvailDA and ability to run lightnodes by staking node sale NFTs.
  * Integration and go-live of zkProver Network to decentralise provers.
  * Deployment of upgraded liquidity aggregation engine on Lumia Stream to optimize cross-market trading.
  * Expansion of RWA developer ecosystem through Lumia Academy programs and global hackathons.
  * Code contribution to CDK stack and integration SP1 proofs.

* **Q4 2025**
  * Lumia Stream upgraded to provide liquidity to RWAs tokenised on Lumia and beyond.
  * Expanded integrations with major centralized and decentralized liquidity venues.
  * Launch of AI Yield Engine leveraging zkML for intelligent yield strategies on real-world assets.
  * Release of Lumia Tokenization SDK for external builders to integrate compliant asset tokenization solutions.
  * Strengthened global presence through major industry events and strategic partnerships

### 2026+ (Forward-looking Developments)&#x20;

* **Early 2026**
  * Introduction of Lumia Chain abstraction layer to simplify user experience across multiple networks.
  * Expansion of fiat on/off ramp infrastructure with integrated verifiable digital identity.
  * Entry into BitcoinFi markets through partnerships with liquidity providers and cross-ecosystem Introduction of Lumia Chain abstraction layer to simplify user experience across multiple networks.
  * Expansion of fiat on/off ramp infrastructure with integrated verifiable digital identity.
  * Entry into BitcoinFi markets through partnerships with liquidity providers and cross-ecosystem aggregators.
  * Ongoing enhancement of decentralized MEV protection through peer-to-peer execution frameworks.

* **Late 2026**
  * Deployment of privacy-preserving transaction capabilities leveraging technologies like Miden.
  * Broadened interoperability across major non-EVM ecosystems to facilitate global RWA markets.
  * Continued growth of Node Owned Liquidity models and ecosystem-driven Hyperstaking initiatives.
  * Further decentralization of core infrastructure with zkProvers and sequencer operations reaching full Stage 2 status.

    <br>


# LUMIA Token

## Introduction

As Lumia evolves to become a leading chain for Real World Assets (RWA) and decentralized finance (DeFi), we are introducing a new native token: LUMIA.&#x20;

### Token Swap

This section outlines the token swap process from the existing Orion Protocol token (ORN) to LUMIA and explains the crucial role LUMIA will play in the Lumia L2 ecosystem.

**Swap Ratio:** 1:1 (1 ORN = 1 LUMIA)

**Process:** For each ORN token burned, holders will receive 1 LUMIA token

**Eligibility:** All current ORN token holders

### Why We're Transitioning to LUMIA

The transition from ORN to LUMIA represents more than just a name change. It signifies the evolution of our project and the expansion of our ecosystem. LUMIA is designed to be the cornerstone of the Lumia network, offering enhanced utility and aligning with our vision for a comprehensive RWA and DeFi platform which will leverage its unique technology to create the ultimate home for open finance.

## LUMIA Token Utility

LUMIA will serve multiple critical functions within the Lumia ecosystem:

**Native Gas Token:** LUMIA will be used to pay for transaction fees on the Lumia L2 network, ensuring efficient and cost-effective operations. The chain itself inherits EIP

**Governance:** LUMIA token holders will have the power to participate in certain decision-making processes for the Lumia software platform only, voting on key protocol upgrades and parameter changes. By locking up LUMIA tokens, users can obtain veLUMIA (vote-escrowed LUMIA), which allows expanded participation and can award potential reward boosters.

**Node Staking:** LUMIA will be used for staking in network nodes, allowing token holders to contribute to network security and earn rewards.

**Liquidity Provision:** LUMIA tokens can of course be used in liquidity pools across the Lumia ecosystem, allowing active participation in the network's overall liquidity provision mechanisms which may incur in extra pool rewards and further advantages.

**Access to Premium Features:** Holding LUMIA may grant access to premium features or reduced fees on the Lumia network as well future partners and ecosystem airdrops.

## Importance of LUMIA in the Lumia Ecosystem

**Aligned Incentives:** By serving as both the gas token and as a general utility token with platform governance elements, LUMIA aligns the interests of users, developers, and network participants.

**Economic Security:** LUMIA's role in node staking enhances the economic security of the Lumia network.

**Ecosystem Growth:** The multi-faceted utility of LUMIA encourages long-term holding and active participation in the ecosystem.

**RWA Integration:** LUMIA will indirectly play a crucial role in the future integration and trading of tokenized Real-World Assets on the platform, as a potential unit of exchange within it.

**Interoperability:** As the native token of Lumia, LUMIA will be at the center of cross-chain operations and liquidity provision.

## Tokenomics

**Current ORN token supply:** 92,631,255&#x20;

**New LUMIA token supply:** 238,888,888&#x20;

**Token supply increase:** 146,257,633

### Supply Increase Explained

The original ORN tokenomics were designed in 2018 to tailor the needs of the original scope of Orion, the first and only trading platform aggregating both centralized and decentralized liquidity in a decentralized manner. This was achieved successfully by the 2020 main net launch of Orion Terminal. Since then, the landscape has significantly changed in terms of how tokens are allocated and the necessary initiatives that are required to allow a healthy token economy to thrive.&#x20;

With our shift in scope that is now Lumia - the first ever hyper-liquid Layer 2 rollup designed to provide deep-liquidity to Real-World Assets (RWAs), we face the need to develop sufficient tokenomics that will assure the longevity and stability of our vision. There are several reasons that the changes in tokenomics are essential to the short and long term growth of the Lumia ecosystem.&#x20;

Firstly, the node operators that are essential for decentralizing Lumia L2 that also bolster the liquidity network of Lumia Stream receive daily rewards for their efforts. The tokens that are eligible for being distributed are factored into this number.&#x20;

Secondly, we’ll be conducting several community initiatives such as airdrops, grants, and other methods that are common for L2s to attract and acquire builders/users. Without such initiatives, we put ourselves at a major disadvantage compared to other successful L2s in the industry, many of which have entirely new token supply - making it impossible for Lumia to compete and thrive long term.

As we keep the community and our token holders first, it is important to transparently and responsibly allocate the added supply - therefore we take pride in ensuring that **100% of the new supply is allocated to node rewards, community rewards, airdrops, and other community building incentives. 0% is allocated to the team.**

{% hint style="info" %}
**This new token supply is vested over 20 years**
{% endhint %}

### Fundamental Necessities for the Change in Tokenomics

#### 1. Building the Ecosystem:

As Lumia evolves from a trading terminal to a comprehensive Layer 2 solution with our liquidity protocol, increasing the token supply is key to kickstarting our ecosystem. Layer 2 networks need strong incentives to draw in users, developers, and liquidity providers. More tokens will help:

* Provide airdrops to early users and those on integrated chains
* Fund grants for developers working on Lumia L2
* Set up liquidity mining programs to boost liquidity in DeFi protocols
* Reward node operators, validators, and sequencers for decentralizing our layer 2

These steps are essential for creating a thriving L2 ecosystem, which is vital for our long-term success and widespread adoption.

#### 2. Liquidity Node Operations:

The Lumia Stream feature, which consolidates liquidity from both CEX and DEX sources, requires more tokens to:

* Reward Liquidity Node operators
* Offer incentives for LUMIA holders who delegate to these nodes
* Build deep liquidity pools within Lumia L2 to enhance capital efficiency

The increased supply will reward those that help Lumia to achieve deep liquidity across various chains and trading pairs.

#### 3. Sustainable Gas Fees:

LUMIA tokens will be used for transaction fees and gas costs on L2. An increase in supply will:

* Allow for more flexible fee structures, including micro-transactions
* Support sustainable fee models that can handle increased network usage without driving up costs too quickly
* Implement a token burning mechanism to gradually reduce the total supply over time as activity on our L2 grows and gas fees accumulate

#### 4. Governance and Staking:

The expanded tokenomics will strengthen our governance model by:

* Creating larger staking pools for governance
* Rewarding active voters to keep the community engaged
* Distributing tokens more widely for more decentralized decision-making

#### 5. Cross-Chain Interoperability:

Lumia L2's commitment to cross-chain integration with our partners Polygon AggLayer, Hyperlane, and Connext requires additional tokens for:

* Providing liquidity for cross-chain bridges
* Incentivizing relayers and bridge operators

#### 6. Long-Term Sustainability:

The new tokens will be released for as long as a 20-year period, ensuring:

* A gradual introduction to avoid flooding the market, ensuring a healthy environment for our token holders and community
* Alignment of incentives for long-term participants to properly scale our L2 to be in business for decades to come
* Flexibility to adapt to market changes and technological advances

#### 7. DA Lightclient Node Operations and Delegators:

Data Availability is crucial for Lumia. The increased token supply supports this by:

* Offering rewards to Lightclient DA node operators who ensure data availability and network security
* Enabling a robust delegation system where LUMIA holders can delegate tokens to DA nodes and earn rewards.&#x20;
* This creates a two-tiered model:&#x20;
  * Full node operators
  * Node Sale License holders to run their own own lightclients

In summary, increasing the token supply to 238,888,888 LUMIA is a strategic move to secure the resources needed for developing and expanding a competitive ecosystem. This boost will support advanced features, integrate with innovative protocols, and foster a sustainable economic model to support Lumia’s long-term growth and success with incentives strictly for community.

### Supply Breakdown

The Newly Minted Token Supply (NTS) consists of two allocations. Node Rewards and Ecosystem Rewards. **None of the NTS is allocated to the team.**&#x20;

The two allocations will be entirely distributed to ecosystem contributors as such:

* **73,439,930 LUMIA (50.21%):** Rewards for node operators, validators, sequencers, delegators, and more. Vested over 20 years.&#x20;
* **72,817,703 LUMIA (49.79%):** Community initiatives including airdrops, grants, liquidity mining, and more. Democratic approach to many initiatives via a governance vote by LUMIA token holders. Vested over 10 years.&#x20;

### On Chain Transparency

The LUMIA token supply are held in secure multi-sig vaults:

#### Vault 1 - ORN to LUMIA Swap

0x424Db71F0Ee69137c850A639ce9bfe6c18a8150A

#### Vault 2 - Node Rewards

0x0Ee999247f3e33406131bC6AA896192Bd40cd6b7

#### Vault 3 - Ecosystem Rewards

0xb10B260fBf5F33CC5Ff81761e090aeCDffcb1fd5

### Emissions

**Current ORN circulating supply pre token swap:** 92,631,255&#x20;

**Post token swap circulating supply:** 104,541,919

Post token swap, Lumia will unlock the first quarter of rewards - accounting for the increase of 11,910,664 tokens in circulation immediately following the token swap. The new token supply will be vested quarterly over 20 years:

<figure><img src="/files/fqMpfOje3vN6TWagUAe2" alt=""><figcaption><p>Quarters 1 through 40</p></figcaption></figure>

<figure><img src="/files/iPIOwAZq631aMc1HiiJw" alt=""><figcaption><p>Quarters 40 through 80</p></figcaption></figure>

<table><thead><tr><th width="117" align="center">Quarter</th><th width="177">Node Emissions</th><th width="203">Community Emissions</th><th>Total Emissions</th></tr></thead><tbody><tr><td align="center">1</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">2</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">3</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">4</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">5</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">6</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">7</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">8</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">9</td><td>2,295,000.00</td><td>1,819,000.00</td><td>4,114,000.00</td></tr><tr><td align="center">10</td><td>2,295,000.00</td><td>1,819,000.00</td><td>4,114,000.00</td></tr><tr><td align="center">11</td><td>2,295,000.00</td><td>1,819,000.00</td><td>4,114,000.00</td></tr><tr><td align="center">12</td><td>2,295,000.00</td><td>1,818,995.00</td><td>4,113,995.00</td></tr><tr><td align="center">13</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">14</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">15</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">16</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">17</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">18</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">19</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">20</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">21</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">22</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">23</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">24</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">25</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">26</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">27</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">28</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">29</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">30</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">31</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">32</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">33</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">34</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">35</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">36</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">37</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">38</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">39</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">40</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">41</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">42</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">43</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">44</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">45</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">46</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">47</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">48</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">49</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">50</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">51</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">52</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">53</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">54</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">55</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">56</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">57</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">58</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">59</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">60</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">61</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">62</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">63</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">64</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">65</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">66</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">67</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">68</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">69</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">70</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">71</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">72</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">73</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">74</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">75</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">76</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">77</td><td>17.51</td><td>0</td><td>17.51</td></tr><tr><td align="center">78</td><td>17.51</td><td>0</td><td>17.51</td></tr><tr><td align="center">79</td><td>17.51</td><td>0</td><td>17.51</td></tr><tr><td align="center">80</td><td>17.56</td><td>0</td><td>17.56</td></tr></tbody></table>

*Emission schedule reflects the amount of tokens that are available for utilization, however this does not mean tokens will enter circulation.  Actual circulating supply consists of node rewards that are not locked for 12-24 months, as well as airdrops/initiatives that are approved by community DAO votes. Circulating supply will be clearly visible on-chain once tokens are distributed from their respective vault, and constantly updated on tracking tools such as CMC amongst others.*

## Conclusion

The transition from ORN to LUMIA marks a significant milestone in our project's journey. LUMIA is not just a token; it's the fuel that will power the next generation of RWA tokenization and DeFi innovation on Lumia chain. We encourage all ORN holders to participate in this token swap and join us in building a more inclusive and efficient financial ecosystem.

Stay tuned for further announcements and updates regarding the token swap process. Together, we're stepping into a new era of decentralized finance with Lumia chain and LUMIA.

<br>


# Token Swap Guide (UI)

## [How to do a token swap from our current token ORN to LUMIA.](https://app.guidde.com/playbooks/s6Ev1SU1s9kZ4fCcKraDMq)

{% embed url="<https://app.guidde.com/share/playbooks/vvHd6b1eTpsG6gZpT7Yihz?origin=RkZxgxrMG7bcO7gzgRcUuF6hMyI3>" %}

This guide will walk you through the process of performing a token swap from ORN to LUMIA using your non-custodial wallet.

#### 1. Go to [token.lumia.org](https://token.lumia.org)

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2FeDzhtSZ82yCpLpBSgMdk5J_doc.png?alt=media&#x26;token=4b61c495-10ec-4a5c-9e53-b976745bbfe0&#x26;time=Fri%20Oct%2018%202024%2013:17:18%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

2. **Click "Connect wallet"**

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2FuDQqqx9nvdHesDZ3nt2PPp_doc.png?alt=media&#x26;token=11fb3ca7-78e0-4353-8ba3-aed0228c132f&#x26;time=Fri%20Oct%2018%202024%2013:17:18%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

3. **Click "BNB Chain" or "Ethereum"**

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2FbKEEqhe4zsFvRBDigAmkSv_doc.png?alt=media&#x26;token=61b8cffb-7f79-43d5-9ec3-21e7a10008f9&#x26;time=Fri%20Oct%2018%202024%2013:17:16%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

4. **Click "MetaMask"**

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2F5TgHCHhMouRuhXEZm7qMHc_doc.png?alt=media&#x26;token=5b91d4dd-5584-4c69-81ef-aa9b0d6de1cc&#x26;time=Fri%20Oct%2018%202024%2013:17:16%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

5. **Click "Max" to take your entire wallet balance**

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2FgiG2GTu4Q8JbLRgxa56FJu_doc.png?alt=media&#x26;token=8383ac94-e837-4d64-836e-06c2b799efc2&#x26;time=Fri%20Oct%2018%202024%2013:17:16%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

6. **Click "Allow to use ORN" to approve contract usage**

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2FgFKMF1aQMEkescBofoaUz8_doc.png?alt=media&#x26;token=53d71f54-72a0-4a22-9946-1cffe4be2aff&#x26;time=Fri%20Oct%2018%202024%2013:17:16%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

7. **Click "Swap"**

<img src="https://storage.app.guidde.com/v0/b/guidde-production.appspot.com/o/quickguiddeScreenshots%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2FvvHd6b1eTpsG6gZpT7Yihz%2Fertchnr3oDrC83k5Ns2uN6_doc.png?alt=media&#x26;token=6065362c-1c27-4021-9677-575683fef527&#x26;time=Fri%20Oct%2018%202024%2013:17:16%20GMT+0100%20(British%20Summer%20Time)" alt="" width="100%">

The guide covered the necessary steps to swap ORN to LUMIA on the Lumia platform, including connecting your wallet, selecting the BNB Chain, confirming the amount, authorizing the use of ORN, and executing the swap

The guide covered how to swap tokens from ORN to LUMIA using Blockchain via ETH and BSC networks. For a technical flow, see below.


# Token Swap Guide (SmartContract)

## [Token swap via SmartContract (Explorer).](https://app.guidde.com/playbooks/qm2NW6TA2HffSa2a79iHE9)

{% embed url="<https://app.guidde.com/share/playbooks/qm2NW6TA2HffSa2a79iHE9>" %}

This guide will walk you through the process of performing a token swap via SmartContract Explorer.

#### Go to [etherscan.io](https://etherscan.io) or [bscscan.io](https://bscscan.com/address/0x7c2eb61ca9fb89844b10f62df23490e43fffe913)

#### 1. Introduction

![Introduction](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2Fva2hgHYwcG2uhVdhek6KG4_doc.png?alt=media\&token=c3aec125-dac9-4efb-b320-c40582980630)

#### 2. Click "Search by Address / Txn Hash / Block / Token / Domain Name"

Begin by searching for the specific address or transaction hash.

![Click 'Search by Address / Txn Hash / Block / Token / Domain Name'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FmssBJCJ4fxshUfqHU4iJhr_doc.png?alt=media\&token=8231cd01-ad43-4371-b51e-4abcb54b59e1)

#### 3. Fill address bar with "0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135"

Fill in contract address provided.

![Fill address bar with  '0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FcTVPWy6bGa7jwoY3PBUCUV_doc.png?alt=media\&token=20030e4c-e29f-4eb8-b1f1-bee4c8e8f132)

#### 4. Click "0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135"

Locate and click on the provided address.

![Click '0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2Ftb9zHaAQGC4SsRKCzbbrpY_doc.png?alt=media\&token=195ea0b5-b5a5-41e7-9ae9-f309b0752073)

#### 5. Click here

Proceed by clicking on the designated link.

![Click here](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F5FYhf3MUsDQdn8925FmXkd_doc.png?alt=media\&token=14c45835-f938-4cfc-9636-b75bf6a18504)

#### 6. Click "Contract"

Navigate to the 'Contract' section.

![Click 'Contract'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FkkcCAwE5obPbXxkBuNwmNS_doc.png?alt=media\&token=e552a677-fd87-4fe6-88fa-60eb93717f75)

#### 7. Click "Write Contract"

Select 'Write Contract' to initiate the contract interaction.

![Click 'Write Contract'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2Fk1ZC3vbfr5jVxTYwzk8fcM_doc.png?alt=media\&token=ec6453df-bdce-42c5-bdf0-ffdbddf17537)

#### 8. Click "Connect to Web3"

Establish a connection to Web3 for further actions.

![Click 'Connect to Web3'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FhJTAGWadYkJxBzD9vMug8j_doc.png?alt=media\&token=81f15918-f339-4b9e-9b82-4a26f67fcd19)

#### 9. Click "MetaMask Popular"

Choose 'MetaMask' from the options available.

![Click 'MetaMask Popular'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F7PfK3gKpAAexRBdK1zYDma_doc.png?alt=media\&token=93327632-2b3b-4ae2-b78c-e1a04c733610)

#### 10. Click "convert"

Click on function named "Convert".

![Click 'convert'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F2DnbhvCaLfXBFjnJ4AXfE8_doc.png?alt=media\&token=944c4c1c-e844-4d2f-85a3-5e69a0fe6d94)

#### 11. Click "ornAmount"

Input ORN token without its decimals i.e. for 1000 ORN just input 1000.

![Click 'ornAmount'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FotqyEZQSJ1og6R5RudEapR_doc.png?alt=media\&token=85ef778f-2e8d-4291-b6b7-112c19b7ea64)

#### 12. Fill in amount.

Enter token amount in the provided field.

![Fill in amount.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F2cmEn56qvUXo2U3i4HQhLA_doc.png?alt=media\&token=1a8b6a29-30ae-4089-b759-a69448e078e4)

#### 13. Click here

Proceed by clicking on the + icon to handle decimals.

![Click here](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FkMwS8KTEK5eEx7UiTRpXnd_doc.png?alt=media\&token=53e4bfcf-5513-4788-b861-af7c1071adec)

#### 14. Adjust decimal placement

![Click '10¹⁸'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F8X7FMYLEKxeeH2nR3KtYf2_doc.png?alt=media\&token=97d69f49-b585-465b-b975-6efad4f54281)

#### 15. Select 18 decimals.

Fill in the text box with "Select 10¹⁸"

![Select 18 decimals.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FhArUSNCVhXefuMnPhZxJ1H_doc.png?alt=media\&token=94700a9a-81bd-4135-9b59-5f4751883121)

#### 16. Click "Add"

![Click 'Add'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F6Jb8kgewT4nvw4K5aP6C5j_doc.png?alt=media\&token=64a5ff4f-669e-4672-9db1-f2c1b9ffd412)

#### 17. Click "Write"

Finalize the token swap by clicking on 'Write'.

![Click 'Write'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FbhEiGPfXtuzhNsqEG2sgwR_doc.png?alt=media\&token=ce72c124-114c-4dbf-9431-5da82c1ac067)

This guide covered the steps involved in conducting a token swap through the SmartContract Explorer on Etherscan (and BSCScan), including connecting to Web3, selecting tokens, and finalizing the swap.

For further information on how to troubleshoot common issues or to learn more about using the SmartContract Explorer, refer to the [Etherscan documentation](https://etherscan.io/docs). If you encounter any specific problems, consulting the FAQ section or reaching out to their support team can provide additional assistance.

### Token Swap using Contracts

For those looking to conduct a token swap through direct SmartContract integration, you can use the provided Ethereum and BNB Chain SmartContract addresses. By interacting directly with these contracts, you can execute token swaps without relying on third-party interfaces, providing a more granular level of control over your transactions.&#x20;

### **Ethereum SmartContract ABI:**

```json
[{"inputs":[{"internalType":"address","name":"_owner","type":"address"},{"internalType":"contract IERC20","name":"_orion","type":"address"},{"internalType":"contract IERC20","name":"_lumia","type":"address"},{"internalType":"uint256","name":"_conversionScaleFactor","type":"uint256"}],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[],"name":"ConversionDisabled","type":"error"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"address","name":"account","type":"address"},{"indexed":false,"internalType":"uint256","name":"ornAmount","type":"uint256"},{"indexed":false,"internalType":"uint256","name":"lumiaAmount","type":"uint256"}],"name":"Convert","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"inputs":[{"internalType":"address","name":"token","type":"address"},{"internalType":"address","name":"burnAddress","type":"address"},{"internalType":"uint256","name":"amount","type":"uint256"}],"name":"burn","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"conversionScaleFactor","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"ornAmount","type":"uint256"}],"name":"convert","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"isConversionEnabled","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lumia","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lumiaDecimals","outputs":[{"internalType":"uint8","name":"","type":"uint8"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"orion","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"orionDecimals","outputs":[{"internalType":"uint8","name":"","type":"uint8"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"renounceOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"toggleIsConversionEnabled","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"newOwner","type":"address"}],"name":"transferOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"}]
```

**BNB Chain SmartContract ABI:**

```json
[{"inputs":[{"internalType":"address","name":"_owner","type":"address"},{"internalType":"contract IERC20","name":"_orion","type":"address"},{"internalType":"contract IERC20","name":"_lumia","type":"address"},{"internalType":"uint256","name":"_conversionScaleFactor","type":"uint256"}],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[],"name":"ConversionDisabled","type":"error"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"address","name":"account","type":"address"},{"indexed":false,"internalType":"uint256","name":"ornAmount","type":"uint256"},{"indexed":false,"internalType":"uint256","name":"lumiaAmount","type":"uint256"}],"name":"Convert","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"inputs":[{"internalType":"address","name":"token","type":"address"},{"internalType":"address","name":"burnAddress","type":"address"},{"internalType":"uint256","name":"amount","type":"uint256"}],"name":"burn","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"conversionScaleFactor","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"ornAmount","type":"uint256"}],"name":"convert","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"isConversionEnabled","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lumia","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"orion","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"renounceOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"toggleIsConversionEnabled","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"newOwner","type":"address"}],"name":"transferOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"}]
```

{% hint style="success" %}
Ethereum SmartContract: <https://etherscan.io/address/0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135>
{% endhint %}

{% hint style="success" %}
BNB Chain SmartContract:&#x20;

[https://bscscan.com/address/0x7c2eb61ca9fb89844b10f62df23490e43fffe913](https://bscscan.com/address/0x7c2eb61ca9fb89844b10f62df23490e43fffe913#tokentxns)
{% endhint %}


# Lumia Power & EcoDrops

## What is Lumia Power?

Lumia Power (LUMIAp) is the token that represents locked-up governance tokens and grants voting power withine the Lumia Ecosystem. A more traditional term is vote-escrowed derivative.

By locking LUMIA for a fixed duration of time, users receive LUMIAp, which grants governance weight and access to exclusive incentives, including EcoDrops.

To dive deeper into the financial side, read [Lumia Power](https://medium.com/%40Lumia.org/what-is-lumiap-5300509bb054) on Medium.

### How it Works

* **Lock Mechanism**: You commit an amount of LUMIA to be locked, choosing a lock duration. \
  3 *months minimum to participate in EcoDops.*
* **LUMIAp Issuance**: In return, the system emits you LUMIAp, which grants governance participation and access to ecosystem incentives—but no ongoing LUMIA interest emissions like in traditional staking/restaking. The emitted amount depends on lock duration and amount—rewarding longer and larger commitments.
* **Utility**: LUMIAp grants governance rights and eligibility for ecosystem rewards (EcoDrops), without accumulating users interest in LUMIA/LUMIAp like in a traditional staked/restaked system.

### User Benefits

The primary benefit and incentive for users is LUMIAp enables participation in exclusive ecosystem incentives like EcoDrops.

From the system point of view, LUMIAp:

* Aligns long-term commitment with governance influence.
* Reduces token dilution, enhancing economic sustainability.

That overall results in a more stable and sustainable system, aimed at benefiting the users.

### How to Obtain Lumia Power?

1. **Acquire $LUMIA**\
   Purchase LUMIA tokens on exchanges such as Binance, Bybit, Bitget, Bitmart, or others.
2. **Lock Your LUMIA**\
   Lock your LUMIA from the [Lumia Power page](https://power.lumia.org/staking). The longer lock period you choose, the more LUMIAp you'll receive.&#x20;
3. **Receive LUMIAp**\
   Based on the locked amount and duration, you'll be allocated LUMIAp. Check your wallet to see it.

### What Are EcoDrops?

**EcoDrops** are incentives for Lumia Ecosystem users, similar to token airdrops, from new projects launching on the Lumia ecosystem.&#x20;

These drops are distributed **exclusively** to LUMIAp holders—rather than through LUMIA inflation—providing direct exposure to emerging projects without diluting LUMIA value. You can learn more from the [Lumia EcoDrops](https://www.binance.com/en-IN/square/post/23042101964682) article on Binance.&#x20;

#### How to Participate in EcoDrops?

* **Mechanics**:
  * To participate, lock LUMIA for at least 3 months to generate LUMIAp.
  * Share in each EcoDrop is proportional to your LUMIAp holdings. Distribution is typically linear over time to encourage sustained participation.
* **Legacy Recognition**:\
  Early contributors who migrated from veORN and still maintain a 3-month lock were given priority in the first EcoDrop—an intentional nod to community founders.
* **Additional Benefits**:\
  Future utilities planned for LUMIAp holders may include:
  * Access to NFTs, events, partner dApp betas or discounts.
  * Participation in treasury or grant decisions — reinforcing broader governance involvement.

### Architecture Overview

Lumia Power is implemented as a set of smart contracts:

* LUMIAp Lumia Power ([0xAE01a2eb6cfDb2daBB1D99c689f2F94D51FFf197](https://explorer.lumia.org/address/0xAE01a2eb6cfDb2daBB1D99c689f2F94D51FFf197?tab=contract)) — LUMIA staking implementation.
* EcoDrops aka Lumia Vesting ([0x95109AdEd0d7b534733AEBE9B2aDAdf2cc0bbAad](https://explorer.lumia.org/address/0x95109AdEd0d7b534733AEBE9B2aDAdf2cc0bbAad?tab=contract)) — drop release logic (vesting), drop allocation logic (acc. to remaining power of winner's LUMIAp).

#### Workflow

Consider this high-level worfklow overview to understand how the product works.

1. The user stakes their LUMIA.
2. The user is minted LUMIAp. It holds the highest power  the time of minting, and **the power gradually decreases** the closer their LUMIAp is to the end of the staking period (lock period).
3. An new EcoDrop campaign is formed. Its details are propagated to the backend of the system:
   1. Program of the campaign: specific steps the user needs to complete.
   2. Deadline to finish all the steps by.
   3. The minimum lock period required to receive a portion of the drop.
4. The user completes all steps before the deadline.
5. Upon the deadline, the backend forms a list of winning participants with the conditions that they have completed the steps.
6. The backend sends the list of winners to the EcoDrops smart contract, which checks if the user's LUMIAp lock period is longer than a certain number of days since the beginning of the campaign.
7. For every user that meets the condition from #6, the smart contact checks the remaining power of their LUMIAp (see #2) and stores the power value.&#x20;
8. The EcoDrops smart contract allocates the drop (100%) for the winners, were each winner gets a % of the drop defined by the remaining power of their LUMIAp (see #2).
9. The user claims their portion of the drop. The portion is released linearly within the 3 months vesting period, i.e. each second a % of that portion becomes available for claiming.

To better understand the logic in #7–8, consider the following two examples.

**Example #1:**

* &#x20;The campaign started on 10.29.2025.
* The campaign stated that to receive a portion of the drop, the LUMIA lock date needs to be 11.11.2025 or earlier.
* The steps completion deadline ended on 11.15.2025.
* The user managed to complete all steps on 11.14.2025.
* The user staked their LUMIA (obtained LUMIAp) on 11.13.2025
* Result: the user is not eligible to receive their drop, since their locked period started much later, than required by the campaign.

**Example #2:**

* &#x20;The campaign started on 10.29.2025.
* The campaign stated that to receive a portion of the drop, the LUMIA lock date needs to be 11.11.2025 or earlier.
* The steps completion deadline ended on 11.15.2025.
* The user managed to complete all steps on 11.14.2025.
* The user staked their LUMIA (obtained LUMIAp) on 10.15.2025
* Result: the user gets their portions of the drop. Since they locked their LUMIA on 10.29.2025, the remaining power of their lock is lower than if they had locked it on 11.11.2025 — they receive a smaller  portion of the drop compared to a scenario where they locked their LUMIA on 11.10.2025.


# LUMIA Migration Sepolia–Beam

## **Overview**

Lumia is transitioning its **LUMIA testnet token** from the **Sepolia Ethereum testnet** to the **Beam Network**. This includes deploying bridging infrastructure and token contracts on Beam to support testnet users and developers in the new environment.

## **Bridging LUMIA Tokens from Sepolia to Beam**

To bridge your testnet LUMIA tokens:

1. Visit the official [**Lumia Beam Bridge**](https://beam-bridge.lumia.org/).&#x20;
2. Click **Connect using web wallet** and proceed to connect your wallet on the **Sepolia network**.<br>

   <div align="left"><figure><img src="/files/OBzLNk1WDDnm8MKyUgNG" alt="" width="375"><figcaption></figcaption></figure></div>
3. Select Sepolia Testnet as **From**, select **LUMIA** as the token and enter a desired amount. Then click **Continue**.<br>

   <div align="left"><figure><img src="/files/lSb2GNRtRDppZzMiM7Dh" alt="" width="375"><figcaption></figcaption></figure></div>
4. Click **Allow Bridge to spend my LUMIA** to approve the Bridge access to the amount you chose at #3. <br>

   <div align="left"><figure><img src="/files/zttP1QsMypYkZNG4QfST" alt="" width="375"><figcaption></figcaption></figure></div>
5. Confirm approval in your wallet.\
   ![](/files/8F1aOHDCqwYgeg6cQDF7)
6. Click **Bridge** and proceed to bridge your LUMIA to Beam.<br>

   <div align="left"><figure><img src="/files/9vhXYefis5YOlLzgd9EM" alt="" width="375"><figcaption></figcaption></figure></div>
7. Confirm the sending trasaction in your wallet.\
   ![](/files/8J5PvWMJMQoYJE7stMxu)
8. Wait a few minutes for the bridging to finalize.
9. At the [**Lumia Beam Bridge**](https://beam-bridge.lumia.org/) click **Add a network** and confirm adding Beam network to your wallet.<br>

   <div align="left"><figure><img src="/files/BU7zVMIPxm5sbllwjiP9" alt="" width="375"><figcaption></figcaption></figure></div>
10. At the [**Activity**](https://beam-bridge.lumia.org/activity) tab, click your bridging and check its status. Once it is **Completed**, switch to the Beam network in your wallet to see the bridged LUMIA.<br>

    <div align="left"><figure><img src="/files/UisObzpirKS5HzpEEzcz" alt="" width="375"><figcaption></figcaption></figure></div>

## **URLs**

Blockscout: <https://beam-explorer.lumia.org\\>
RPC: <https://beam-rpc.lumia.org\\>
Faucet: <https://beam-faucet.lumia.org\\>
Bridge: <https://beam-bridge.lumia.org>

## **Contract Addresses & Roles**

| Contract                                                                                                                             | Address                                      | Purpose                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
| [**Bridge Contract**](https://beam-explorer.lumia.org/address/0x528e26b25a34a4A5d0dbDa1d57D318153d2ED582?tab=contract) **(on Beam)** | `0x528e26b25a34a4A5d0dbDa1d57D318153d2ED582` | Handles bridging of LUMIA                                        |
| [**Bridge Contract**](https://sepolia.etherscan.io/address/0x528e26b25a34a4a5d0dbda1d57d318153d2ed582#code) **(on Sepolia)**         | `0x528e26b25a34a4a5d0dbda1d57d318153d2ed582` | Handles bridging of LUMIA                                        |
| [**Sequencer**](https://beam-explorer.lumia.org/address/0x660100aA52d5A2B1dF9b57680CeCaE15EBD5d413)                                  | `0x660100aA52d5A2B1dF9b57680CeCaE15EBD5d413` | Address responsible for ordering transactions in the Beam rollup |
| [**ClaimTxManager**](https://beam-explorer.lumia.org/address/0x1f4081a1b03472bcEC12aa15deEa2Edd117D4CE1) **(Layer 2)**               | `0x1f4081a1b03472bcEC12aa15deEa2Edd117D4CE1` | Address that submits claim transactions                          |
| [**CoinBase**](https://beam-explorer.lumia.org/address/0x6089EA70f401Df85Aa3fCE90CE3ffbA6C4206eE8) **(Fee Collector)**               | `0x6089EA70f401Df85Aa3fCE90CE3ffbA6C4206eE8` | Address that accumulates gas fees collected on Beam              |
| [**BurnerSmartContract**](https://beam-explorer.lumia.org/address/0x078413b8b5a2614081813619c594fE84Ef839535?tab=contract)           | `0x078413b8b5a2614081813619c594fE84Ef839535` | Handles LUMIA token burning logic                                |
| [**LUMIA**](https://sepolia.etherscan.io/address/0x5787a0c1ccf0c94d99fe5725120ab1f7482ed9e8#code)                                    | `0x5787a0c1ccf0c94d99fe5725120ab1f7482ed9e8` | LUMIA token on Sepolia                                           |

***

## **Interacting with the Contracts**

Developers and Advanced Users can interact directly with the contracts.

The main flow is as such:

1. Call [approve](https://sepolia.etherscan.io/address/0x5787a0c1ccf0c94d99fe5725120ab1f7482ed9e8#writeContract#F1) to approve the bridge access to LUMIA.
2. Call [bridgeAsset](https://sepolia.etherscan.io/address/0x528e26b25a34a4a5d0dbda1d57d318153d2ed582#writeProxyContract#F3) to transfer the approved LUMIA from Sepolia to Beam.
3. Wait for the sequences address to pick up the event and react (order and sumbit the tx). It may take up to 45 mins (around 15 in reality). \
   Claiming is automated, you don't need to take any additional action to see the bridged LUMIA tokens in your wallet on Beam.

### Code examples

Code examples for interaction:

**Solidity**

```
// SPDX-License-Identifier: MIT pragma solidity ^0.8.19;

import "forge-std/Script.sol";

interface ILumiaBridge { 
    function sendToBeam(address recipient, uint256 amount) external; 
}

contract BridgeLumia is Script { 
    address constant BRIDGE = 0x528e26b25a34a4A5d0dbDa1d57D318153d2ED582; 
    address constant TOKEN = /* Sepolia token contract address, if needed for approve */;

    function run() external {
        address user = vm.envAddress("USER_ADDRESS");
        uint256 amount = 1e18; // 1 LUMIA

        vm.startBroadcast();

        ILumiaBridge(BRIDGE).sendToBeam(user, amount);

        vm.stopBroadcast();
    }
}
```

**ethers.js**

```
const { ethers } = require("ethers");

const BRIDGE_ADDRESS = "0x528e26b25a34a4A5d0dbDa1d57D318153d2ED582";
const BRIDGE_ABI = [
  "function sendToBeam(address recipient, uint256 amount) external"
];

async function main() {
  const provider = new ethers.JsonRpcProvider("https://rpc.sepolia.org");
  const wallet = new ethers.Wallet("YOUR_PRIVATE_KEY", provider);

  const bridge = new ethers.Contract(BRIDGE_ADDRESS, BRIDGE_ABI, wallet);

  const recipient = "0xYourBeamWalletAddress";
  const amount = ethers.parseUnits("1", 18); // 1 LUMIA

  const tx = await bridge.sendToBeam(recipient, amount);
  console.log("Tx sent:", tx.hash);

  await tx.wait();
  console.log("Bridged successfully");
}

main().catch(console.error);

```

## **Recommendations**

* **If needed, add Beam Testnet to MetaMask** using provided RPC/ChainID:

  ```
  RPC URL: https://beam-rpc.lumia.org
  Chain ID: 2030232745
  Explorer: https://beam-explorer.lumia.org
  ```
* **Bridge only small amounts of test tokens first** to validate the process.
* Monitor transactions on the explorer: <https://beam-explorer.lumia.org>.
* If you're building on top of Lumia/Beam, consider:
  * **Verifying custom contracts** on the Beam Blockscout.
  * **Registering your Chain ID** in global registries to ensure broader tool compatibility.
* **Token Faucet**: Use <https://beam-faucet.lumia.org> for testnet tokens to cover gas fees.
* **Security**: Ensure you verify contract interactions and ABIs before executing write functions directly.


# 普通话 - LUMIA 代币

## 导言

随着 Lumia 逐渐发展成为真实世界资产（RWA）和去中心化金融（DeFi）的领先链，我们将推出一种新的原生代币： LUMIA。

### 代币交换

本节概述了从现有Orion协议代币 (ORN) 到 LUMIA 的代币交换过程，并解释了 LUMIA 将在 Lumia L2 生态系统中发挥的关键作用。

**交换比率**：1:1（1 ORN = 1 LUMIA）

**过程**： 每烧毁一个 ORN 代币，持有者将获得 1 个 LUMIA 代币

**资格**： 所有当前 ORN 代币持有者

### 我们为何向 LUMIA 过渡

从 ORN 到 LUMIA 的过渡不仅仅是名称的改变。它标志着我们项目的演变和生态系统的扩展。LUMIA 旨在成为 Lumia 网络的基石，提供更强的实用性，并符合我们对融合RWA 和 DeFi 平台的愿景，该平台将利用其独特的技术，打造开放式金融的终极平台。

## LUMIA 代币用途

LUMIA 将在 Lumia 生态系统中发挥多种重要功能：

**原生gas代币：** LUMIA 将用于支付 Lumia L2 网络上的交易费用，确保高效、具有成本效益的运营。该链本身继承了 EIP。

**治理：** LUMIA 代币持有者将有权参与 Lumia 平台的决策过程，对关键协议升级和参数更改进行投票。通过质押 LUMIA 代币，用户可以获得 veLUMIA（投票退出的 LUMIA），从而获得更强的治理权和潜在的奖励提升。

**节点质押：** LUMIA 将用于在网络节点中进行质押，允许代币持有者为网络安全做出贡献并获得奖励。

**提供流动性：** LUMIA 代币可用于整个 Lumia 生态系统的流动性池，使持有者能够赚取费用并参与网络的流动性提供机制等。

**获取高级功能：** 持有LUMIA可在Lumia网络上访问高级功能或享受手续费折扣，以及获得未来合作伙伴和生态系统的空投。

## LUMIA 在 Lumia 生态系统中的重要性

**激励对齐：** LUMIA 既是gas代币，也是治理代币，它将用户、开发者和网络参与者的利益结合在一起。

**经济安全：** LUMIA 在节点质押方面的作用增强了 Lumia 网络的经济安全性。

**生态系统增长：** LUMIA 的多方面功能鼓励用户长期持有并积极参与生态系统。

**RWA 集成：** LUMIA 将在促进平台上代币化真实世界资产的整合与交易方面发挥重要作用。

**可操作性：** 作为 Lumia 的原生代币，LUMIA 将成为跨链操作和流动性供给的中心。

## 代币经济学

**当前 ORN 代币供应量：** 92,631,255

**新的 LUMIA 代币供应量：** 238,888,888

**代币供应增加：** 146,257,633

### 供应增加的解释

最初的ORN代币经济学是在 2018 年根据Orion最初范围的需求而设计的，Orion是第一个也是唯一一个以去中心化方式聚合中心化和去中心化流动性的交易平台。2020年主网推出的Orion终端成功实现了这一目标。自那时起，代币分配方式以及维持健康代币经济所需的必要举措都发生了重大变化。

随着我们的项目重心转向现在的Lumia——这是首个专为真实世界资产（RWAs）提供深度流动性而设计的超高流动性二层扩容解决方案，我们需要制定完善的代币经济模型，以确保我们愿景的长期可持续性和稳定性。代币经济模型的变更对Lumia生态系统的短期和长期发展至关重要，原因有以下几点。

首先，对Lumia二层网络去中心化起关键作用的节点运营商，同时也增强了Lumia Stream的流动性网络。为激励他们的贡献，我们设立了每日代币奖励机制。这些奖励所需的代币数量已纳入可分配的新增代币供应中。

其次，我们将开展一些社区活动，如空投、赠款和其他 L2 常用的吸引和获取建设者/用户的方法。如果不采取这些措施，与业内其他成功的 L2 相比，我们就会处于非常不利的地位，因为其中许多 L2 都拥有全新的代币供应，这使得 Lumia 无法长期竞争和发展。

由于我们将社区和代币持有者放在首位，因此必须透明、负责任地分配新增供应量--因此，我们以确保 100% 的新增供应量分配给节点奖励、社区奖励、空投和其他社区建设奖励为荣。0% 分配给团队。新供应的代币归属期长达 20 年。

### 代币经济变革的根本必要性

1. **建立生态系统：**

随着 Lumia 从一个交易终端发展成为具有流动性协议的全面二层解决方案，增加代币供应是启动我们生态系统的关键。二层网络需要强大的激励机制来吸引用户、开发者和流动性提供商。更多代币将有助于：

* 向早期用户和集成链上的用户提供空投
* 为 Lumia L2 的开发人员提供基金资助
* 制定流动性挖矿计划，提高 DeFi 协议的流动性
* 奖励节点运营商、验证者和排序者，以实现我们二层的去中心化&#x20;

这些步骤对创建繁荣的L2生态系统至关重要，这也是我们长期成功和广泛采用的关键。

2. **流动性节点运营：**

Lumia Stream 功能整合了 CEX 和 DEX 来源的流动性，需要更多代币才能进行：

* 奖励流动性节点运营商
* 为委托给这些节点的 LUMIA 持有者提供激励措施
* 在 Lumia L2 内建立深度流动性池，提高资本效率

增加的供应量将奖励那些帮助Lumia在各个链和交易对中实现深度流动性的参与者。

3. **可持续的gas费：**

LUMIA 代币将用于支付 L2 上的交易费用和gas成本。供应量的增加将

* 允许更灵活的收费结构，包括小额交易
* 支持可持续的收费模式，既能应对网络使用量的增加，且不会导致成本过快上升
* 实施代币燃烧机制，随着 L2 上活动的增加和手续费的累积，逐步减少总供应量

4. **治理和质押：**

升级后的代币经济学将通过以下方式加强我们的治理模式：

* 为治理创建更大的质押池
* 奖励活跃投票者以保持社区参与度
* 更广泛地分配代币以实现更去中心化的决策

5. **跨链互操作性：**

Lumia L2 致力于与合作伙伴 Polygon AggLayer、Hyperlane 和 Connext 进行跨链整合，因此需要额外的代币：

* 为跨链桥梁提供流动性
* 激励中继器和桥接运营商

6. **长期可持续性：**

新代币的发行期将长达 20 年之久，以确保：

* 逐步引入，避免市场泛滥，确保代币持有者和社区有一个健康的环境
* 调整对长期参与者的激励措施，以适当扩大 L2 的规模，使其在未来数十年内继续开展业务
* 灵活适应市场变化和技术进步

7. **DAC 节点操作和代表：**

数据可用性委员会（DAC）对 Lumia L2 至关重要，尤其是对其 Validium 设置而言。增加代币供应有助于实现这一目标：

为确保数据可用性和网络安全的DAC节点运营商提供可观的奖励

实现强大的委托系统，LUMIA持有者可以将代币委托给DAC节点并获得奖励。这创建了一个两层模型：

* 管理基础设施的节点运营商
* 通过委托支持节点的代币持有者

总之，将代币供应量增加到238,888,888 LUMIA是一项战略性举措，旨在确保发展和扩展有竞争力的二层生态系统所需的资源。这一提升将支持先进功能，集成创新协议，并培育可持续的经济模型，通过严格面向社区的激励来支持Lumia的长期增长和成功。

### 供应明细

新铸代币供应（NTS）包括两种分配--节点奖励和生态系统奖励。所有 NTS 都不会分配给团队。这两种分配将全部分配给生态系统贡献者：

**73,439,930LUMIA（50.21%）：** 奖励节点运营商、验证者、排序者、委托人等。归属期超过 20 年。

**72,817,703LUMIA（49.79%）：** 社区活动，包括空投、赠款、流动性挖矿等。通过 LUMIA 代币持有者的治理投票，以民主方式实施多项举措。归属期超过 10 年。

### 链上透明度

LUMIA 代币保存在安全的多重签名保险库中：

#### 存储库 1 - ORN 交换至 LUMIA

0x424Db71F0Ee69137c850A639ce9bfe6c18a8150A

#### 存储库 2 - 节点奖励

0x0Ee999247f3e33406131bC6AA896192Bd40cd6b7

#### 存储库 3 - 生态系统奖励

0xb10B260fBf5F33CC5Ff81761e090aeCDffcb1fd5

### 释放量

**当前 ORN代币流通供应量：**&#x39;2,631,255

**代币交换后的流通供应量：** 104,541,919

代币交换后，Lumia 将解锁第一季度的奖励--即代币交换后流通的代币增加了 11,910,664 枚。新的代币供应将在 10-20 年内按季度归属：

<figure><img src="/files/fqMpfOje3vN6TWagUAe2" alt=""><figcaption><p>第 1 至第 40 季度</p></figcaption></figure>

<figure><img src="/files/iPIOwAZq631aMc1HiiJw" alt=""><figcaption><p>第 40 至 80 季度</p></figcaption></figure>

<table><thead><tr><th width="117" align="center">季度</th><th width="177">节点释放</th><th width="203">社区释放</th><th>总释放量</th></tr></thead><tbody><tr><td align="center">1</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">2</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">3</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">4</td><td>9,180,000.00</td><td>2,730,664.00</td><td>11,910,664.00</td></tr><tr><td align="center">5</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">6</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">7</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">8</td><td>4,590,000.00</td><td>1,820,443.00</td><td>6,410,443.00</td></tr><tr><td align="center">9</td><td>2,295,000.00</td><td>1,819,000.00</td><td>4,114,000.00</td></tr><tr><td align="center">10</td><td>2,295,000.00</td><td>1,819,000.00</td><td>4,114,000.00</td></tr><tr><td align="center">11</td><td>2,295,000.00</td><td>1,819,000.00</td><td>4,114,000.00</td></tr><tr><td align="center">12</td><td>2,295,000.00</td><td>1,818,995.00</td><td>4,113,995.00</td></tr><tr><td align="center">13</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">14</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">15</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">16</td><td>1,147,500.00</td><td>1,786,904.00</td><td>2,934,404.00</td></tr><tr><td align="center">17</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">18</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">19</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">20</td><td>573,750.00</td><td>1,754,809.00</td><td>2,328,559.00</td></tr><tr><td align="center">21</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">22</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">23</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">24</td><td>286,875.00</td><td>1,722,713.00</td><td>2,009,588.00</td></tr><tr><td align="center">25</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">26</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">27</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">28</td><td>143,437.50</td><td>1,690,617.00</td><td>1,834,054.50</td></tr><tr><td align="center">29</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">30</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">31</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">32</td><td>71,718.75</td><td>1,658,521.00</td><td>1,730,239.75</td></tr><tr><td align="center">33</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">34</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">35</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">36</td><td>35,859.38</td><td>1,626,426.00</td><td>1,662,285.38</td></tr><tr><td align="center">37</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">38</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">39</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">40</td><td>17,929.68</td><td>1,594,330.00</td><td>1,612,259.68</td></tr><tr><td align="center">41</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">42</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">43</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">44</td><td>8,964.84</td><td>0</td><td>8,964.84</td></tr><tr><td align="center">45</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">46</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">47</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">48</td><td>4,482.42</td><td>0</td><td>4,482.42</td></tr><tr><td align="center">49</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">50</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">51</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">52</td><td>2,241.21</td><td>0</td><td>2,241.21</td></tr><tr><td align="center">53</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">54</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">55</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">56</td><td>1,120.61</td><td>0</td><td>1,120.61</td></tr><tr><td align="center">57</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">58</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">59</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">60</td><td>560.30</td><td>0</td><td>560.30</td></tr><tr><td align="center">61</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">62</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">63</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">64</td><td>280.15</td><td>0</td><td>280.15</td></tr><tr><td align="center">65</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">66</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">67</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">68</td><td>140.07</td><td>0</td><td>140.07</td></tr><tr><td align="center">69</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">70</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">71</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">72</td><td>70.04</td><td>0</td><td>70.04</td></tr><tr><td align="center">73</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">74</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">75</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">76</td><td>35.02</td><td>0</td><td>35.02</td></tr><tr><td align="center">77</td><td>17.51</td><td>0</td><td>17.51</td></tr><tr><td align="center">78</td><td>17.51</td><td>0</td><td>17.51</td></tr><tr><td align="center">79</td><td>17.51</td><td>0</td><td>17.51</td></tr><tr><td align="center">80</td><td>17.56</td><td>0</td><td>17.56</td></tr></tbody></table>

*释放计划反映了可供使用的代币数量，但这并不意味着代币将进入流通。 实际流通供应包括 12-24 个月内不锁定的节点奖励，以及社区 DAO 投票批准的空投/倡议。一旦代币从各自的存储库中分发，流通供应量将在链上清晰可见，并在 CMC 等跟踪工具上不断更新。*

## 结论

*从 ORN 到 LUMIA 的过渡标志着我们项目历程中的一个重要里程碑。LUMIA 不仅仅是一种代币，它还是 Lumia L2 下一代 RWA 代币化和 DeFi 创新的动力。我们鼓励所有 ORN 持有者参与此次代币交换，与我们一起打造一个更加包容、高效的金融生态系统。*

*敬请关注有关代币交换流程的进一步公告和更新。通过 Lumia L2 和 LUMIA，我们将携手迈入去中心化金融的新时代。*


# Token Swap Guide (UI)

## [How to do a token swap from our current token ORN to LUMIA.](https://app.guidde.com/playbooks/s6Ev1SU1s9kZ4fCcKraDMq)

{% embed url="<https://app.guidde.com/share/playbooks/s6Ev1SU1s9kZ4fCcKraDMq>" %}

This guide will walk you through the process of performing a token swap from ORN to LUMIA using your non-custodial wallet.

#### Go to [token-swap.lumia.org](https://token-swap.lumia.org)

#### 1. Introduction

![Introduction](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fs6Ev1SU1s9kZ4fCcKraDMq%2FgrPUzgQVtxCEXo6TNB1cgR_doc.png?alt=media\&token=f83e7aa3-f6ad-4166-b861-84f018069946)

#### 2. Click "Connect wallet"

Connect your wallet to proceed.

![Click 'Connect wallet'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fs6Ev1SU1s9kZ4fCcKraDMq%2FftRqZZHy1Rhc7GMzAtpNJi_doc.png?alt=media\&token=584bdf21-69b0-4fb3-9e3e-45e5447a8a7b)

#### 3. Click "Ethereum" or" BSC" depending on which network your ORN tokens are currently on.

Select the Ethereum network.

![Click 'Ethereum' or' BSC' depending on which network your ORN tokens are currently on.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fs6Ev1SU1s9kZ4fCcKraDMq%2FgGmRD8FABNF268dTELbNYu_doc.png?alt=media\&token=fea6dd14-d316-4588-a714-00410fe12055)

#### 4. Click "MetaMask" or another wallet provider that is supported.

Open MetaMask for the transaction.

![Click 'MetaMask' or another wallet provider that is supported.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fs6Ev1SU1s9kZ4fCcKraDMq%2F9Fm1MWnCA6ofcvXqDh2Mqo_doc.png?alt=media\&token=e72e04b7-91b2-4e2e-9efb-c4840fd33a7b)

#### 5. Input amount of ORN you want to convert.

![Input amount of ORN you want to convert.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fs6Ev1SU1s9kZ4fCcKraDMq%2FkY4asECGGEDxNU26dZ5cKQ_doc.png?alt=media\&token=c8c1192a-f0f9-498a-a33c-79a7ecb0c00e)

#### 6. Click "Proceed"

![Click 'Proceed'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fs6Ev1SU1s9kZ4fCcKraDMq%2Fsw4W5Rs6CtG4dU5CQbZSy2_doc.png?alt=media\&token=da4dfddd-8588-42fe-961f-02780c677b11)

The guide covered how to swap tokens from ORN to LUMIA using Blockchain via ETH and BSC networks. For a technical flow, see below.


# Token Swap Guide (SmartContract)

## [Token swap via SmartContract (Explorer).](https://app.guidde.com/playbooks/qm2NW6TA2HffSa2a79iHE9)

{% embed url="<https://app.guidde.com/share/playbooks/qm2NW6TA2HffSa2a79iHE9>" %}

This guide will walk you through the process of performing a token swap via SmartContract Explorer.

#### Go to [etherscan.io](https://etherscan.io)

#### 1. Introduction

![Introduction](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2Fva2hgHYwcG2uhVdhek6KG4_doc.png?alt=media\&token=c3aec125-dac9-4efb-b320-c40582980630)

#### 2. Click "Search by Address / Txn Hash / Block / Token / Domain Name"

Begin by searching for the specific address or transaction hash.

![Click 'Search by Address / Txn Hash / Block / Token / Domain Name'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FmssBJCJ4fxshUfqHU4iJhr_doc.png?alt=media\&token=8231cd01-ad43-4371-b51e-4abcb54b59e1)

#### 3. Fill address bar with "0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135"

Fill in contract address provided.

![Fill address bar with  '0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FcTVPWy6bGa7jwoY3PBUCUV_doc.png?alt=media\&token=20030e4c-e29f-4eb8-b1f1-bee4c8e8f132)

#### 4. Click "0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135"

Locate and click on the provided address.

![Click '0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2Ftb9zHaAQGC4SsRKCzbbrpY_doc.png?alt=media\&token=195ea0b5-b5a5-41e7-9ae9-f309b0752073)

#### 5. Click here

Proceed by clicking on the designated link.

![Click here](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F5FYhf3MUsDQdn8925FmXkd_doc.png?alt=media\&token=14c45835-f938-4cfc-9636-b75bf6a18504)

#### 6. Click "Contract"

Navigate to the 'Contract' section.

![Click 'Contract'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FkkcCAwE5obPbXxkBuNwmNS_doc.png?alt=media\&token=e552a677-fd87-4fe6-88fa-60eb93717f75)

#### 7. Click "Write Contract"

Select 'Write Contract' to initiate the contract interaction.

![Click 'Write Contract'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2Fk1ZC3vbfr5jVxTYwzk8fcM_doc.png?alt=media\&token=ec6453df-bdce-42c5-bdf0-ffdbddf17537)

#### 8. Click "Connect to Web3"

Establish a connection to Web3 for further actions.

![Click 'Connect to Web3'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FhJTAGWadYkJxBzD9vMug8j_doc.png?alt=media\&token=81f15918-f339-4b9e-9b82-4a26f67fcd19)

#### 9. Click "MetaMask Popular"

Choose 'MetaMask' from the options available.

![Click 'MetaMask Popular'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F7PfK3gKpAAexRBdK1zYDma_doc.png?alt=media\&token=93327632-2b3b-4ae2-b78c-e1a04c733610)

#### 10. Click "convert"

Click on function named "Convert".

![Click 'convert'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F2DnbhvCaLfXBFjnJ4AXfE8_doc.png?alt=media\&token=944c4c1c-e844-4d2f-85a3-5e69a0fe6d94)

#### 11. Click "ornAmount"

Input ORN token without its decimals i.e. for 1000 ORN just input 1000.

![Click 'ornAmount'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FotqyEZQSJ1og6R5RudEapR_doc.png?alt=media\&token=85ef778f-2e8d-4291-b6b7-112c19b7ea64)

#### 12. Fill in amount.

Enter token amount in the provided field.

![Fill in amount.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F2cmEn56qvUXo2U3i4HQhLA_doc.png?alt=media\&token=1a8b6a29-30ae-4089-b759-a69448e078e4)

#### 13. Click here

Proceed by clicking on the + icon to handle decimals.

![Click here](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FkMwS8KTEK5eEx7UiTRpXnd_doc.png?alt=media\&token=53e4bfcf-5513-4788-b861-af7c1071adec)

#### 14. Adjust decimal placement

![Click '10¹⁸'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F8X7FMYLEKxeeH2nR3KtYf2_doc.png?alt=media\&token=97d69f49-b585-465b-b975-6efad4f54281)

#### 15. Select 18 decimals.

Fill in the text box with "Select 10¹⁸"

![Select 18 decimals.](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FhArUSNCVhXefuMnPhZxJ1H_doc.png?alt=media\&token=94700a9a-81bd-4135-9b59-5f4751883121)

#### 16. Click "Add"

![Click 'Add'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2F6Jb8kgewT4nvw4K5aP6C5j_doc.png?alt=media\&token=64a5ff4f-669e-4672-9db1-f2c1b9ffd412)

#### 17. Click "Write"

Finalize the token swap by clicking on 'Write'.

![Click 'Write'](https://static.guidde.com/v0/qg%2FRkZxgxrMG7bcO7gzgRcUuF6hMyI3%2Fqm2NW6TA2HffSa2a79iHE9%2FbhEiGPfXtuzhNsqEG2sgwR_doc.png?alt=media\&token=ce72c124-114c-4dbf-9431-5da82c1ac067)

This guide covered the steps involved in conducting a token swap through the SmartContract Explorer on Etherscan (and BSCScan), including connecting to Web3, selecting tokens, and finalizing the swap.

For further information on how to troubleshoot common issues or to learn more about using the SmartContract Explorer, refer to the [Etherscan documentation](https://etherscan.io/docs). If you encounter any specific problems, consulting the FAQ section or reaching out to their support team can provide additional assistance.

### Token Swap using Contracts

For those looking to conduct a token swap through direct SmartContract integration, you can use the provided Ethereum and BNB Chain SmartContract addresses. By interacting directly with these contracts, you can execute token swaps without relying on third-party interfaces, providing a more granular level of control over your transactions.&#x20;

### **Ethereum SmartContract ABI:**

```json
[{"inputs":[{"internalType":"address","name":"_owner","type":"address"},{"internalType":"contract IERC20","name":"_orion","type":"address"},{"internalType":"contract IERC20","name":"_lumia","type":"address"},{"internalType":"uint256","name":"_conversionScaleFactor","type":"uint256"}],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[],"name":"ConversionDisabled","type":"error"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"address","name":"account","type":"address"},{"indexed":false,"internalType":"uint256","name":"ornAmount","type":"uint256"},{"indexed":false,"internalType":"uint256","name":"lumiaAmount","type":"uint256"}],"name":"Convert","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"inputs":[{"internalType":"address","name":"token","type":"address"},{"internalType":"address","name":"burnAddress","type":"address"},{"internalType":"uint256","name":"amount","type":"uint256"}],"name":"burn","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"conversionScaleFactor","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"ornAmount","type":"uint256"}],"name":"convert","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"isConversionEnabled","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lumia","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lumiaDecimals","outputs":[{"internalType":"uint8","name":"","type":"uint8"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"orion","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"orionDecimals","outputs":[{"internalType":"uint8","name":"","type":"uint8"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"renounceOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"toggleIsConversionEnabled","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"newOwner","type":"address"}],"name":"transferOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"}]
```

**BNB Chain SmartContract ABI:**

```json
[{"inputs":[{"internalType":"address","name":"_owner","type":"address"},{"internalType":"contract IERC20","name":"_orion","type":"address"},{"internalType":"contract IERC20","name":"_lumia","type":"address"},{"internalType":"uint256","name":"_conversionScaleFactor","type":"uint256"}],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[],"name":"ConversionDisabled","type":"error"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"address","name":"account","type":"address"},{"indexed":false,"internalType":"uint256","name":"ornAmount","type":"uint256"},{"indexed":false,"internalType":"uint256","name":"lumiaAmount","type":"uint256"}],"name":"Convert","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"inputs":[{"internalType":"address","name":"token","type":"address"},{"internalType":"address","name":"burnAddress","type":"address"},{"internalType":"uint256","name":"amount","type":"uint256"}],"name":"burn","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"conversionScaleFactor","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"ornAmount","type":"uint256"}],"name":"convert","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"isConversionEnabled","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"lumia","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"orion","outputs":[{"internalType":"contract IERC20","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"renounceOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"toggleIsConversionEnabled","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"newOwner","type":"address"}],"name":"transferOwnership","outputs":[],"stateMutability":"nonpayable","type":"function"}]
```

{% hint style="success" %}
Ethereum SmartContract: <https://etherscan.io/address/0xFBaa4E673D0cD1159beD704Fdc0e4379a41c2135>
{% endhint %}

{% hint style="success" %}
BNB Chain SmartContract: <https://bscscan.com/address/0x5cCdC72a72780B1b5EDD513BebB9fEF88DeA329b>
{% endhint %}


# zkProvers

zkProvers: Powering Scalability and Security in Lumia L2

### Introduction to zkProvers

zkProvers are a critical component of zero-knowledge (ZK) rollups, playing a vital role in enabling scalability and security in blockchain networks. In the context of Lumia chain, which is built on the Polygon Chain Development Kit (CDK), zkProvers are responsible for generating zero-knowledge proofs that validate the correctness of transactions executed on the Layer 2 network.

A zkProver is a specialized software component that performs complex mathematical computations to create succinct and verifiable proofs of the validity of state transitions in a ZK rollup. These proofs allow the Layer 1 to verify the integrity of the rollup's state without the need to re-execute all transactions, thereby enabling scalability while maintaining security.

### How zkProvers Work with zkEVMs

zkEVMs, such as the one provided by the Polygon CDK, are virtual machines that emulate the functionality of the Ethereum Virtual Machine (EVM) while leveraging zero-knowledge proofs for scalability. The zkProver plays a crucial role in this architecture by generating proofs that attest to the correctness of the zkEVM's execution.

Here's how the zkProver interacts with the zkEVM:

1. **Transaction Execution:** Transactions are executed on the zkEVM, which interprets EVM bytecode and updates the state of the Layer 2 network accordingly.
2. **State Transitions:** The zkProver captures the state transitions resulting from the transaction execution, including changes to account balances, smart contract storage, and other relevant data.
3. **Proof Generation:** The zkProver performs complex mathematical computations to generate a zero-knowledge proof that verifies the validity of the state transitions. This proof is constructed using advanced cryptographic techniques, such as zk-SNARKs or zk-STARKs, which allow for succinct and verifiable proofs.
4. **Proof Submission:** The generated proof is then submitted to the Layer 1 along with a compressed representation of the state transitions. This allows the L1 to efficiently verify the correctness of the Layer 2 state without the need to re-execute all transactions.

By leveraging zkProvers, zkEVMs like the Polygon CDK can achieve significant scalability improvements while maintaining the security guarantees of the underlying blockchain network. The zkProver ensures that the state transitions are valid and consistent, enabling trustless and efficient verification of Layer 2 transactions.

### zkProver Nodes: Decentralizing Proof Generation

Lumia chain aims to further enhance the decentralization and scalability of its zkProver infrastructure through our partner [Gevolut](https://gevulot.com/). These specialized nodes will be responsible for generating zero-knowledge proofs on behalf of the network, distributing the computational load and ensuring a more resilient and efficient proof generation process.

Flwo of data for zkProver Nodes:

1. **Proof Generation Requests:** When transactions are executed on the Lumia network, proof generation requests will be broadcasted to the network of Gevoluts zkProver Nodes.
2. **Proof Generation:** zkProver Nodes will receive these requests and perform the necessary computations to generate the zero-knowledge proofs. Each node will have specialized hardware and software optimized for efficient proof generation.
3. **Proof Submission:** Once a zkProver Node generates a valid proof, it will submit the proof to ETH L1 as Lumia's "settlement" layer.
4. **Incentivization:** To incentivize participation and ensure a robust network of zkProver Nodes, Lumia will reward nodes with LUMIA tokens for their proof generation efforts. This creates an economic incentive for node operators to contribute their computational resources to the network.
5. **Decentralization and Scalability:** By distributing the proof generation process across a network of zkProver Nodes, Lumia chain achieves greater decentralization and scalability. The computational load is shared among multiple nodes, reducing the burden on any single entity and enabling faster proof generation times.

The zkProver Nodes concept aligns with Lumia chains vision of creating a highly scalable and decentralized blockchain infrastructure. By incentivizing a distributed network of specialized proof generators, Lumia network can achieve faster transaction throughput, lower latency, and enhanced security, while maintaining the trustless nature of the network.

### Conclusion

zkProvers are a fundamental component of ZK rollups, enabling scalable and secure transaction processing in Layer 2 networks like Lumia chain. By working in conjunction with zkEVMs, such as the Polygon CDK, zkProvers generate succinct and verifiable proofs that attest to the correctness of state transitions, allowing for efficient verification on L1.

Looking ahead, Lumia chains vision of zkProver Nodes represents a significant step forward in decentralizing and scaling the proof generation process. By distributing the computational load across a network of specialized nodes and incentivizing participation with LUMIA tokens, Lumia chain aims to create a more resilient, efficient, and decentralized infrastructure for zero-knowledge proof generation.

As the blockchain ecosystem continues to evolve, the development of advanced zkProver technologies and architectures, such as those being pioneered by Lumia chain will play a crucial role in unlocking the full potential of scalable and secure decentralized applications.


# Sequencer

The Backbone of Layer 2 Performance

#### Understanding Layer 2 Sequencers

In the realm of Layer 2 scaling solutions, sequencers play a crucial role in ensuring the smooth operation and high performance of the network. A Layer 2 sequencer is a specialized node responsible for ordering and processing transactions within a Layer 2 system, such as a rollup or a sidechain.

#### The Role of Sequencers

Sequencers perform several key functions that are essential to the functioning of a Layer 2 network:

1. **Transaction Ordering**: Sequencers collect transactions submitted by users and arrange them in a specific order to be processed and included in the next batch or block. This ordering process is critical for maintaining the consistency and determinism of the Layer 2 state.
2. **Transaction Execution**: Once the transactions are ordered, the sequencer executes them according to the rules and logic of the Layer 2 system. This involves updating the state of the network, modifying account balances, and executing smart contract code.
3. **Batch Submission**: After executing the transactions, the sequencer packages them into a batch or a block and submits it to the Layer 1 blockchain. This submission process typically involves creating a cryptographic commitment or a hash of the batch, which is then recorded on the L1.
4. **Data Availability**: Sequencers are often responsible for ensuring the availability of the transaction data. They may store the full data of the transactions on the Layer 1 blockchain or use alternative data availability solutions to guarantee that the data can be accessed and verified by other participants in the network.

#### The Need for Sequencers

Sequencers are essential for the efficient operation of Layer 2 networks due to several reasons:

1. **Scalability**: By offloading the transaction processing and execution from the Layer 1 blockchain to a dedicated sequencer, Layer 2 solutions can achieve significantly higher transaction throughput and lower latency compared to respective L1.
2. **Cost Reduction**: Sequencers help reduce the gas costs associated with executing transactions on the Layer 1 blockchain. By bundling multiple transactions into a single batch or block, sequencers minimize the number of L1 transactions required, resulting in lower overall costs for users.
3. **Deterministic Execution**: Sequencers ensure that transactions are executed in a deterministic manner, following a predefined set of rules and logic. This determinism is crucial for maintaining the consistency and integrity of the Layer 2 state across all participants in the network.

### Conclusion

Sequencers are the backbone of Layer 2 performance, enabling high transaction throughput, lower costs, and deterministic execution. By co-developing its own subnet of sequencers and implementing a reward mechanism, Lumia chain is taking a proactive approach to ensure optimal performance, decentralization, and ecosystem growth.

As Lumia chain continues to innovate and push the boundaries of Layer 2 scaling, its dedicated sequencer subnet will play a vital role in delivering a seamless and efficient user experience, while maintaining the security and integrity of the network.


# Data Availability

## What is DA?

In the realm of blockchain technology, data availability is a critical component that ensures the integrity, security, and trustworthiness of the network. It refers to the guarantee that all the necessary data required to validate transactions and reconstruct the state of the blockchain is readily accessible to all participants in the network. Without data availability, the decentralized nature of the blockchain would be compromised, and the system would be vulnerable to various attacks and manipulations.

### The Importance of Data Availability

Data availability plays a crucial role in maintaining the core principles of blockchain technology:

1. **Decentralization**: By ensuring that all participants have equal access to the transaction data, data availability prevents any single entity from having control over the network or censoring transactions.
2. **Transparency**: With data availability, anyone can independently verify the state of the blockchain and the validity of transactions, promoting transparency and trust in the network.
3. **Security**: Data availability is essential for detecting and preventing malicious activities, such as double-spending attacks or the creation of invalid blocks.
4. **Scalability**: As blockchain networks grow in size and complexity, data availability becomes a key factor in ensuring that the network can scale efficiently without compromising its security or decentralization.

### Current Solutions for Data Availability

Several solutions have emerged to address the challenge of data availability in blockchain networks:

1. **NearDA**: NearDA is a decentralized data availability solution that leverages erasure coding and a network of nodes to store and retrieve data. It provides a scalable and resilient infrastructure for ensuring data availability.
2. **EigenDA**: EigenDA is a data availability solution built on top of the EigenLayer protocol. It utilizes a decentralized network of nodes to store and serve data, while also incorporating cryptographic techniques to ensure data integrity and retrievability.
3. **Celestia**: Celestia is a modular blockchain architecture that separates the consensus and data availability layers. It provides a decentralized data availability layer that can be used by other blockchains to ensure the availability of their transaction data.
4. **Avail**: Avail is a data availability layer that utilizes a novel data sampling technique called "data availability sampling" to reduce the storage requirements for nodes while maintaining high levels of data availability and security.

### Conclusion

Data availability is a critical component of blockchain technology, ensuring the integrity, security, and trustworthiness of the network. Without data availability, the decentralized nature of the blockchain would be compromised, and the system would be vulnerable to various attacks and manipulations. As blockchain networks continue to grow and evolve, innovative solutions like Avail, NearDA, EigenDA, and Celestia are paving the way for scalable and resilient data availability infrastructures. By addressing the challenges of data availability, these solutions contribute to the long-term sustainability and adoption of blockchain technology across various industries and use cases.


# Validium

Lumia chain, built using the Polygon Chain Development Kit (CDK), offers two configuration options: the Polygon zkEVM rollup and the Polygon CDK validium. This section focuses on the Polygon CDK validium configuration and its advantages for the Lumia network.

### What is Validium?&#x20;

Validium is a scaling solution that leverages validity proofs to ensure the integrity of state transitions while storing transaction data off-chain. Unlike rollups, validium does not store transaction data on the Ethereum network, leading to reduced gas fees and improved scalability.

Lumia chain is a zero-knowledge validium (zkValidium) that utilizes the Polygon zkEVM's off-chain prover to generate zero-knowledge proofs. These proofs are then published as validity proofs, adding a layer of trustlessness to the validium configuration.

The validium mode in Lumia chain inherits all the components and functionalities of the Polygon zkEVM, except for the on-chain storage of transaction data. By storing only, a hash of the transaction data on the Ethereum network, and relying on AvailDA (and our redundancy system; DAC) Lumia chain's validium configuration offers significantly reduced gas fees compared to the zkEVM rollup option.

### Data Availability Committee (DAC)  - Disaster Recovery

To manage the off-chain storage of transaction data, Lumia chains Polygon CDK validium introduces the concept of a Data Availability Committee (DAC). The DAC is a set of trusted actors responsible for monitoring and authenticating the hash values proposed by the sequencer for publication on the Ethereum network.

The process works as follows:

1. The trusted sequencer collects transactions from the pool DB, organizes them into batches, and computes the hash of the transaction data.
2. The sequencer forwards the batch data and corresponding hash values to the DAC for authentication.
3. DAC members independently verify the batch data against the received hash values and sign them upon validation.
4. The sequencer collects the signatures from the DAC members and uses a multi-sig contract on the Ethereum network to attach the required signatures to the transaction data hash.

In essence, Lumia can be seen as a combination of the Polygon zkEVM, AvailDA and DAC :

Polygon CDK "***volition***" = Polygon zkEVM +  AvailDA + (DAC)

#### Validium Data Flow&#x20;

The DAC and the sequencer work together to control the flow of data and state changes in Lumia chains validium configuration. The process can be broken down into the following steps:

1. **Batch Formation**: The sequencer collects user transactions, adds them to blocks, and organizes the blocks into batches while recursively computing their hash values.
2. **Batch Authentication**: Once the batches are assembled and hash values computed, the sequencer forwards the batch data and corresponding hash values to the DAC for authentication.
3. **Data Validation and Storage**: DAC nodes independently validate the batch data against the received hash values and store the validated hash values in their local databases for future reference.
4. **Signature Generation**: Each DAC node generates a signature for each batch hash, endorsing the batch's integrity and authenticity.
5. **Communication with Ethereum**: The sequencer collects the DAC members' signatures and the original batch hash, and submits them to the Ethereum network for verification.
6. **Verification on Ethereum**: A designated multi-sig smart contract on Ethereum verifies the submitted signatures against each DAC member's known signatures and confirms that sufficient approval has been provided for the batch hash.
7. **Final Settlement with Zero-Knowledge Proof**: The aggregator prepares a proof for the batch using the prover and submits it to the Ethereum network. This proof confirms the validity of the transactions in the batch without revealing transaction details, and the chain's state is updated on Ethereum.

By leveraging the Polygon CDK validium configuration, Lumia achieves enhanced scalability, reduced gas fees, and a trustless environment for processing transactions while maintaining the security and integrity of the network.


# Volition (Enhanced Validium)

Incentivizing DA Node Runners

Lumia chain is introducing an innovative approach to its Polygon CDK validium configuration by incentivizing Data Availability (DA) lightclients through a reward distribution mechanism. This enhancement aims to encourage participation, as well as improve decentralization and the overall health of the Lumia L2 network.

### Reasoning behind the Enhancements&#x20;

The primary reasons for introducing incentives for DA nodes are:

1. **Encouraging Participation:** By offering LUMIA token rewards, Lumia chain incentivizes more individuals and entities to run DA nodes and participate in the network's data availability and validation processes.
2. **Promoting Decentralization:** Allowing node sale participants to earn helps distribute the network's responsibilities and rewards a wide group of stakeholders, promoting decentralization.
3. **Ensuring Network Health:** Incentivizing DA nodes based on factors such as uptime and fees encourages reliable and consistent performance, contributing to the overall health and stability of the Lumia network.

### Enhanced Validium Data Flow&#x20;

The enhanced validium data flow in Lumia chain builds upon the existing process, with the addition of  lightclient DA nodes, reward distribution and calculation steps:

1. **Batch Formation:** The sequencer collects user transactions, adds them to blocks, and organizes the blocks into batches while recursively computing their hash values.
2. **Batch Authentication:** Once the batches are assembled and hash values computed, the sequencer forwards the batch data and corresponding hash values to AvailDA and DAC for authentication.
3. **Data Validation and Storage:** DAC nodes and AvailDA independently validate the batch data against the received hash values and store the validated hash values in their local networks and databases for future reference.
4. **Signature Generation:** Lightclients will split data as per Avail algorithms and "data sampling" technique and make it available for querying. On the flip side, each DAC node generates a signature for each batch hash, endorsing the batch's integrity and authenticity.
5. ***Communication with Ethereum and Reward Distribution***: The sequencer collects the DAC members' signatures and the original batch hash and submits them to the Ethereum network for verification. Meanwhile, lightclients continue to serve data requests. Rewards are calculated on the fly for lightclients based on multiple metrics and requests served while DAC quitely stores same data in a centralised DB for redundancy.
6. **Verification on Ethereum:** A designated multi-sig smart contract on Ethereum verifies the submitted data.
7. ***Final Settlement with Zero-Knowledge Proof and Reward Calculation:*** The aggregator prepares a proof for the batch using the prover and submits it to the Ethereum network. This proof confirms the validity of the transactions in the batch without revealing transaction details, and the chain's state is updated on Ethereum. After successful settlement, the reward distribution smart contract calculates the rewards for each participating node based on factors such as the number of delegated NFTs, uptime, and fees. The contract then distributes the LUMIA token rewards to the DAC nodes and their delegators according to the calculated amounts.

<figure><img src="/files/mDpzKwoR5I9VnfM6ICQS" alt=""><figcaption><p>High level data flow in enhanced DAC</p></figcaption></figure>

### Reward Distribution Smart Contract&#x20;

To facilitate the reward distribution process, Lumia chain will develop adjust Avails lightclients so that it can:

1. Keep track of the nodes and their delegators (via NFT delegation).
2. Receive information about participating nodes.
3. Calculate rewards based on the chosen criteria (e.g., round-robin, delegated NFTs, uptime, fees).
4. Distribute LUMIA tokens to the nodes.

The reward calculation and distribution will be triggered after the successful settlement of each batch on Ethereum (step 7), ensuring that rewards are only given for properly validated and settled batches.

By implementing this enhanced validium configuration, Lumia L2 not only maintains the benefits of reduced gas fees and improved scalability but also fosters a more decentralized, participatory, and robust network. The incentivization of DA nodes through LUMIA token rewards encourages active involvement, ultimately contributing to the long-term success and stability of the Lumia ecosystem.


# What is Avail DA?

| Hi**gh Level** | Avail DA is a modular blockchain focused on data availability that provides core infrastructure allowing networks of blockchains built on top to scale efficiently.                                                                                                                                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Normie**     | Avail is a modular data availability solution that ensures a blockchain’s data is published and can be efficiently verified.                                                                                                                                                                                                                                                                          |
| **Retail**     | Avail is a ZK optimized data availability base layer that enables higher throughput for rollups, lower transaction fees for end-users, and scalable blockspace for blockchains built on top.                                                                                                                                                                                                          |
| **Rollups**    | Avail is a modular data availability base layer that helps modular chains scale blockspace while remaining technically and economically sustainable for network participants. With Avail DA, blockchains can enjoy features and benefits similar to those offered by Ethereum’s danksharding roadmap.                                                                                                 |
| **Technical**  | Avail DA is modular base layer providing robust and verifiable data availability. It integrates KZG commitments, light clients, and data availability sampling to ensure resilience. This unique design allows light clients to replicate the Avail blockchain, enabling them to verify validity proofs from either network copy, ensuring that Avail DA remains operational even without full nodes. |


# How does AvailDA Scale?

| [Erasure Coding](https://docs.availproject.org/docs/introduction-to-avail/avail-da#enhancing-data-reliability-through-erasure-coding) | Erasure coding is the process of creating redundancy in data so that the original data is easily recoverable even if parts of it is missing. In Avail, we use erasure coding to make it very hard for malicious data publishers to hide parts of data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [KZG Commitments](https://docs.availproject.org/docs/glossary#kzg-commitments)                                                        | <p>High Level: A type of validity proof that makes it simple for even a light client to independently generate their own mathematically verified data availability guarantees.</p><p><br><br></p><p>Analogy: A KZG commitment scheme is essentially a cryptographic envelope. When a sheet full of data is inserted into the envelope and sealed, a unique serial number is created and placed on top—we call this committing to the value. Once sealed, the data cannot be changed or tampered with but anyone can verify its existence by scanning the signature. If the data is changed, the digital signature changes and the previous signature is no longer valid.</p>                                                                                                                                                 |
| [Data Availability Sampling](https://docs.availproject.org/docs/faqs#what-is-data-availability-sampling-das)                          | Data availability sampling is a method used by light clients to confirm the availability of data without downloading complete blocks, allowing them to verify with 99.99% certainty that all data in a block is available by sampling just \~1% of it. Through this method, light clients engage in several rounds of random sampling for small chunks of block data. With each successful round, confidence that the data is available grows. When the light client achieves a set confidence threshold, they recognize the block data as accessible.                                                                                                                                                                                                                                                                       |
| [Light Client](https://docs.availproject.org/docs/operate-a-node/run-a-light-client/Overview)                                         | The Avail light client is a node that lets users access blockchains by downloading the bare minimum amount of data required to verify its existence. It plays a vital role in ensuring the availability and correctness of data within the Avail network. Avail LCs are suitable for low-resource environments like phones and smartwatches and offer roughly comparable security to full nodes. As the number of light clients grows and more data availability sampling (DAS) occurs, the coverage offered by the light client network expands, eventually becoming large enough to collectively sample larger blocks. Unlike monolithic blockchain designs which reduce the amount of blockspace available as demand increases, Avail’s LCs can help scale blockspace with demand, future-proofing appchains and rollups. |
| [Consensus Mechanism](https://docs.availproject.org/docs/learn-about-avail/consensus)                                                 | Avail uses a hybrid consensus model based on Polkadot’s BABE and GRANDPA that produces high finality and liveness. This model equips Avail with network resilience and enables it to withstand temporary network partitions and a substantial number of node failures.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [GRANDPA](https://docs.availproject.org/docs/learn-about-avail/consensus/grandpa)                                                     | GRANDPA functions as the finality gadget, ensuring transaction accuracy and security, and enables the simultaneous finalization of multiple blocks. GRANDPA validators vote on a block that they consider best and their votes are applied transitively to all previous blocks. After two-thirds of the GRANDPA authorities have voted for a particular block, it is considered final, greatly speeding up the finalization process, even after long-term network partitioning or other networking failures. As soon as more than 2/3 of validators attest to a chain containing a certain block, all blocks leading up to that one are finalized at once.                                                                                                                                                                   |
| [BABE](https://docs.availproject.org/docs/learn-about-avail/consensus/babe#introduction)                                              | BABE serves as the block production engine, prioritizing quick transaction processing (liveness) by coordinating with validator nodes to identify new block producers. BABE assigns block production slots to validators according to stake and using a randomness cycle. BABE execution happens in sequential non-overlapping phases known as epochs. Each epoch is divided into a predefined number of slots. During each slot, only some of the validators can produce a block. Validators are selected based on a verifiable random function (VRF).                                                                                                                                                                                                                                                                      |


# Benefits of AvailDA

| **Cost Efficient** | Securely transition data availability off-chain, significantly cutting costs, and boosting L2 scalability and efficiency.                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Improved UX**    | Shifting data availability off-chain alleviates the burden on the Ethereum mainnet, leading to expedited transaction confirmation and reduced gas fees for users.                                                        |
| **Scalability**    | Designed to scale as user activity increases, allowing higher throughput without sacrificing performance or reliability.                                                                                                 |
| **Reliable**       | Cutting-edge solution for encoding, committing to, and verifying the availability of data, ensuring that it remains accessible and reliable even in the face of node failures, network disruptions, or malicious actors. |
| **Versatility**    | Turn-key data availability base layer equipped with SDKs, an attestation bridge, and data availability guarantees from peer-to-peer light clients designed for ZK and Optimistic rollups, all built by a proven team.    |


# Lumia DA - Lightclient Nodes

Lumia Chains Approach to Data Availability: DA Lightclients

Lumia chain, being a state-of-the-art Layer 2 scaling solution, recognizes the importance of data availability and has developed its own approach to ensure the integrity and accessibility of transaction data while maintaining high level of decentralization. Lumia chain builds on the concept of lightclients introduced by the AvailDA team and brings forth innovation by allowing Node Sale Participants to stake their NFT licenses to run, verify and earn LUMIA via its bespoke Lightclient implementation. Lumia currently is actively developing the lightclient solution and development discussions as well as PRs can be viewed [here](https://github.com/availproject/avail-light/pull/764).

### DA Nodes and Node Licenses

To become a DA (lightclient) node operator, participants must acquire a "node license" in the form of a non-fungible token (NFT). These node licenses grant the holders the right to operate a DA node and earn rewards in the form of LUMIA tokens for their services.

Lumia chain with its goal to reach "***stage 2***" in mind will promote decentralization and community participation. Lumia chain allows "node sale" participants who have purchased a node license NFT to run their own lightclient nodes. By running their node, participants can earn a portion of the LUMIA rewards allocated to the DA nodes cluster.

### Technical Details of DA Nodes

The DA nodes in Lumia operates as follows:

1. **Data Storage**: When a transaction is processed on the Lumia network, the transaction data is distributed across the DA nodes on AvailDA. Each DA node stores a portion of the data, ensuring that the data is replicated and readily available.
2. **Data Retrieval**: When a participant needs to access the transaction data for validation or other purposes, they can request the data from the DA nodes. The DA nodes work together to serve the requested data promptly.
3. **Data Integrity**: To ensure the integrity of the stored data, Lumia chain employs cryptographic techniques such as erasure coding and Merkle proofs. These techniques allow for the detection of any data corruption or tampering attempts.
4. **Reward Distribution**: The LUMIA rewards allocated to the DA nodes are distributed among the node operators based on their contribution and uptime.
5. **Scalability and Resilience**: The DA nodes is designed to scale horizontally, allowing for the addition of more nodes as the network grows. This scalability ensures that the data availability remains high even as the transaction volume increases. Additionally, the distributed nature of the cluster provides resilience against node failures or malicious actors.

### Pros and Cons of Lumia chains DA Approach vs. EigenDA

When compared to other data availability solutions like EigenDA, Lumia chains DA approach has its own set of advantages and disadvantages:

#### Pros:

* **Community Participation**: Lumia chains DA approach allows for greater community participation through the node license NFT system. This promotes decentralization and incentivizes participants to actively contribute to the network's security and performance.
* **Trusted Partners**: By partnering with trusted entities to serve as the initial DA nodes, Lumia chain ensures a high level of reliability and stability in the early stages of the network's development.
* **Reward Distribution**: The DA approach enables a fair distribution of rewards among node operators and node license NFT holders, creating a more inclusive and attractive ecosystem for participants.
* **Redundancy and Disaster Recovery:** Lumia chain will operate both AvailDA as decentralized DA layer but at the same time it will operate centralize DAC. In the event of recovery or disaster chain will switchover from one or the other to serve data and assure chain is operational at all times.

#### Cons:

* **Complexity**: Lumia chains DA approach introduces additional complexity compared to solutions like EigenDA. Managing the DA nodes cluster, node licenses, and reward distribution requires careful design and implementation. Lumia collaborates with Polygon and GatewayFM to streamline DAC implementation and management.

### Conclusion

Lumia chains approach to data availability represents a unique and innovative solution that prioritizes community participation, decentralization, and reward distribution. While it may introduce some complexities compared to other solutions like EigenDA, the approach offers distinct advantages in terms of inclusivity and incentivization as well as promotion of true decentralization.

As Lumia chain continues to refine and optimize its DA nodes, it has the potential to establish itself as a leading example of how data availability can be achieved in a decentralized and community-driven manner. Lumia is currently working on lightclients adjustments to ensure we can run on smartphones as we aim to optimize and decentralize every aspect of the chain.


# Lumia Stream

## Welcome to Lumia Stream: Powering the Future of DeFi

#### The Challenge of Spread-Out Liquidity

In the world of blockchain, we're moving fast into a future with many chains - like L1 and L2 technologies. This is great for growth, but it makes liquidity spread thin across different chains and exchanges. Often, projects struggle to keep or attract this essential liquidity, making it hard for good ideas to take off because they can't get the financial backing they need.

### How Lumia Changes the Game

Lumia Stream steps in as a game-changer. It’s natively built on Lumia L2 and on the main EVM blockchains, it's easy to integrate via guided SDKs to help developers focus on making their projects unique and engaging without worrying about attracting liquidity. Here's how:

**Easy Access to Liquidity**

Lumia Stream aggregate both centralized (CEXs) and decentralized exchanges (DEXs) to bring together the liquidity of the entire crypto market. This means developers can start their projects with the liquidity resources they need right from the start, whether they need Spot or Perpetuals liquidity.

**MEV Protection**

All trades using decentralized CEX liquidity will be protected from MEV and frontrunning, being decentralized p2p agreements between the trader and Lumia Stream's Liquidity Nodes.

**Atomic Swap Bridge**

Lumia Stream has built a bridge with Atomic Swaps with Hashed Time Lock Contracts (HTLCs), to allow trustless cross chain bridging of native assets. The cryptographic technology behind this bridge allow Lumia Stream to perform permissionless cross chain swaps without the risks of mint and burn mechanisms and without the need to rely on a multisig.

**Transmuted AMM Price Curves and Virtual Order Books** &#x20;

Lumia Stream has included in its SDK the possibility for developers to create a virtual order book showing paths between multiple exchanges (DEXs and CEXs)  and Transmuted AMM Price Curves, which allows the Virtual Order Book to show pools from AMMs of any kind as quotes on an order book.&#x20;

To learn more, read the Lumia Stream documentation at this link

{% content-ref url="/spaces/23sOcZDOT0EJuHpwQzoU" %}
[Lumia Stream](https://lumia.gitbook.io/lumia-stream/)
{% endcontent-ref %}

&#x20;

###


# Node Owned Liquidity

## Introduction

Node Owned Liquidity is a pivotal concept in the Lumia ecosystem, particularly for the Lumia L2 DAC (Data Availability Committee) nodes. Unlike regular validator nodes which receive their rewards gradually over time, DAC nodes are granted these rewards from the beginning. This strategic allocation allows for immediate liquidity, which is essential for facilitating large trades on Lumia Stream.

## How It Works

DAC nodes, which validate Lumia L2, receive their rewards in LUMIA tokens upfront. These rewards are subject to a vesting schedule, but the liquidity is available immediately for use on Lumia Stream. This system is designed to handle significant trade volumes efficiently. Here's a detailed explanation of the process:

1. **Trade Initiation**:
   * A trader on Lumia Stream intends to perform a trade to acquire XYZ tokens.
   * The available liquidity within the Liquidity Nodes on Lumia Stream is insufficient to facilitate the trade.
2. **Utilizing Node Owned Liquidity**:
   * In this scenario, the Liquidity Node will utilize the LUMIA tokens owned by DAC nodes.
   * These tokens are posted as collateral in a strongly overcollateralized position within the XYZ/LUMIA lending pool.
   * The Liquidity Node borrows XYZ tokens using the posted LUMIA tokens as collateral.
3. **Execution and Settlement**:
   * The borrowed XYZ tokens are sent to the Lumia Stream trader to complete the trade.
   * Subsequently, the Liquidity Node hedges the order, rebalances its portfolio, and repays the loan.
   * This entire process is carried out while maintaining a delta-neutral position for Liquidity Nodes and DAC Nodes.

#### Benefits

1. **Instant Liquidity**:
   * DAC node delegators provide LUMIA tokens that are otherwise idle, enabling immediate liquidity for large trades.
   * This ensures that even trades worth millions of dollars can be settled instantly on Lumia Stream, with 1:1 CEX pricing.
2. **Real Yield for DAC Nodes**:
   * By leveraging Node Owned Liquidity, DAC nodes generate real yield.
   * This adds a significant value proposition for delegators who stake their LUMIA tokens with DAC nodes.
3. **Increased Capital Efficiency**:

   * Using node rewards liquidity to facilitate trades takes validator node capital efficiency to unprecedented heights.
   * The entire amount of delegated LUMIA, which is in the tens of millions, counts towards the TVL of Lumia Stream.

#### Conclusion

Node Owned Liquidity is a sophisticated mechanism that enhances the liquidity, efficiency, and security of the Lumia ecosystem. By leveraging the immediate availability of LUMIA tokens from DAC nodes, Lumia Stream can facilitate large trades seamlessly, providing real yield to DAC Nodes and boosting the platform's TVL. This innovative approach underscores the strategic advantage of DAC nodes within the Lumia network and their critical role in driving the ecosystem's growth and stability.


# Liquidity Restaking

Lumia Stream is developing innovative forms of yields for Liquidity Nodes and Liquidity Restakers, increasing capital efficiency to a scale never seen before in DeFi.

More details TBA soon.


# Lumia Passport

### Introduction to Lumia Passport

Lumia Passport is your blockchain identity with infinite dencentralized possibilites.&#x20;

In essence, it is an Account Abstraction (AA) wallet that replaces traditional private key wallets with smart contracts. AA makes your crypto experience more secure, user-friendly and enabling features like social recovery, multi-factor authentication, bundled transactions, and spending limits. All of this is now handled by custom logic instead of just a single private key.

At the core of Lumia Passport are both decentralized identity and account abstraction solution. It is based on the ERC-4337 account abstraction and Sumsub KYC and identity verification. While ERC-4337 standardized AA on Ethereum, allowing wallets to act like bank accounts with flexible rules, Sumsub handles the core KYC/AML compliance and issues verifiable attestations on-chain.

Lumia Passport represents a paradigm shift in how users interact with blockchain applications, removing the complexity of traditional wallet management while maintaining the security and decentralization principles that define Web3.

### What is in Lumia Passport?

Lumia Passport is a multi-layered identity and account management system that combines:

1. **ERC-4337 Smart Accounts**: Programmable wallet accounts that enable gasless transactions, batch operations, and custom authorization logic
2. **Sumsub Integration**: A combination of ZKPs for secure verification, document checks, biometrics, and transaction monitoring, aiming to balance user privacy with strict regulatory needs.
3. **Reusable Identity**: A single, portable identity that works across all dApps and services within the Lumia ecosystem
4. **Selective Disclosure**: Users control exactly what information they share with different applications.

The Passport serves as both a Smart Account wallet and a verified credential container, allowing users to seamlessly interact with decentralized applications while maintaining complete control over their personal data.

### Core Components

#### ERC-4337 Smart Account Architecture

Lumia Passport leverages the ERC-4337 standard to transform traditional externally owned accounts (EOAs) into programmable smart contract accounts. This architecture provides several key advantages:

**UserOperation Objects**

Instead of traditional transactions signed by private keys, Lumia Passport uses UserOperations—pseudo-transaction objects that represent user intent. A UserOperation contains:

* **sender**: The smart account address initiating the operation
* **nonce**: Sequential number preventing replay attacks
* **initCode**: Bytecode for deploying the account if it doesn't exist
* **callData**: The actual function call and parameters to execute
* **callGasLimit**: Maximum gas for the main execution
* **verificationGasLimit**: Maximum gas for signature verification
* **preVerificationGas**: Gas compensation for bundler operations
* **maxFeePerGas**: Maximum total gas price willing to pay
* **maxPriorityFeePerGas**: Maximum priority fee for miners
* **paymasterAndData**: Information about third-party gas sponsorship
* **signature**: Cryptographic proof authorizing the operation

**Entry Point Contract**

The Entry Point contract is the singleton smart contract that orchestrates all ERC-4337 operations on Lumia chain. It:

* Validates UserOperations before execution
* Manages the execution flow and gas accounting
* Coordinates with Paymasters for gas sponsorship
* Ensures security through standardized validation
* Handles batch execution of multiple operations

Lumia chain utilizes a deployed Entry Point contract compatible with the ERC-4337 v0.6 specification, ensuring broad compatibility with the account abstraction ecosystem.

**Smart Account Contract**

Each Lumia Passport is implemented as an ERC-4337-compliant smart contract that:

* Stores all user assets (tokens, NFTs, etc.)
* Implements custom validation logic before transaction execution
* Supports multiple signers and authorization schemes
* Enables modular functionality through plugins
* Maintains upgrade paths while preserving security

The Smart Account is signer-agnostic, meaning users can authenticate using various methods including traditional private keys, multi-signature schemes, hardware wallets, biometrics, or passkeys.

#### Sumsub Integration

Comprehensive Identity Verification Lumia Passport leverages Sumsub, a full-cycle verification platform that orchestrates the entire user lifecycle. Sumsub enables secure and compliant identity verification, allowing users to meet regulatory standards while ensuring their digital identity remains portable and secure.

Advanced Verification & Fraud Prevention At the core of Sumsub is a robust compliance engine that validates user credentials with high accuracy and liveness detection. This technology allows for:

* Non-Doc Verification: Verify identity using banking or database records without uploading physical documents
* Liveness and Biometrics: Prove you are a real human presence to prevent bot attacks and fraud
* Behavioral Intelligence: Analyze user patterns to detect suspicious activity without compromising sensitive data

Lumia chain integrates Sumsub's verification orchestration to support this functionality, ensuring that sensitive user information is processed securely while meeting strict global compliance requirements.

Credential Issuance and On-Chain Attestations Lumia Passport credentials are issued through Sumsub's trusted verification flow. The integration supports:

* Global Coverage: Verification capabilities across 220+ countries and territories
* Multi-Level Checks: From basic liveness to advanced AML screening

These credentials support:

* Personal information verification (name, address, date of birth)
* Government-issued IDs and proof of address validation
* Accreditation status for qualified investors
* Continuous monitoring for AML risks

Once verified, the status can be anchored on-chain as a verifiable attestation or Soulbound Token (SBT), ensuring immutability and allowing dApps to check status without re-verifying data.

Reusable Identity Mechanism The Sumsub-integrated Passport implements a reusable identity protocol that allows users to verify once and share their status across multiple dApps. This is achieved through:

* Unified Profile: A single verification flow creates a portable identity
* Privacy-Preserving Checks: dApps verify the "Verified" status rather than raw data
* Cross-Service Portability: Seamless onboarding to new services within the ecosystem
* Fine-grained access control mechanisms

Users can choose when to present their verified status to each dApp, maintaining privacy while enabling necessary regulatory verifications.

### Key Features and Benefits

#### Simplified User Onboarding

Lumia Passport eliminates the complexity of traditional blockchain onboarding:

* **No Seed Phrases**: Users don't need to memorize or secure 12-24 word recovery phrases
* **Social Recovery**: Authorize trusted friends, family, or devices to help recover accounts
* **Web2-Style Login**: Authenticate using familiar methods like email, social accounts, or biometrics
* **Instant Account Creation**: Smart accounts are deployed on-demand when first needed

#### Gasless Transactions

Through Paymaster integration, Lumia Passport enables truly gasless experiences:

* **Sponsored Transactions**: Protocol or application pays gas fees on behalf of users
* **ERC-20 Gas Payment**: Pay transaction fees using any supported token (USDC, LUMIA, etc.)
* **Flexible Fee Models**: Developers can implement custom fee structures
* **No Native Token Required**: Users don't need to hold LUMIA tokens to interact with dApps

The Paymaster acts as a gas tank, covering transaction costs and enabling seamless onboarding for Web2 users unfamiliar with blockchain economics.

#### Enhanced Security Features

Lumia Passport provides multiple layers of security:

**Session Keys**

Create temporary authorization keys with limited permissions and time bounds. For example:

* Allow a gaming dApp to execute trades up to 100 LUMIA for 24 hours
* Grant a DeFi protocol permission to interact with specific smart contracts
* Revoke access instantly if a device is compromised

**Multi-Chain Validation**

Validate transactions across multiple blockchains before execution, enabling:

* Cross-chain transaction coordination
* Unified security policies across chains
* Protection against replay attacks on different networks

**Passkey Support**

Leverage device-native biometric authentication:

* Face ID or Touch ID on mobile devices
* Windows Hello on desktop
* Hardware security keys for maximum protection

**Transaction Limits**

Configure spending limits to prevent account drainage:

* Set maximum transferable value per transaction
* Define daily or weekly spending caps
* Implement time-locked large transactions

**Whitelists**

Create lists of trusted addresses:

* Only allow transfers to pre-approved addresses
* Prevent phishing attacks and malicious transactions
* Add friction to unusual transaction patterns

#### Flexible Authorization

Lumia Passport is completely signer-agnostic, supporting:

* **Traditional Private Keys**: Standard ECDSA signatures
* **Multi-Signature**: Require multiple approvals for transactions
* **Social Recovery**: Designated guardians can help restore access
* **Hardware Wallets**: Ledger, Trezor integration
* **Biometric Authentication**: Fingerprint, facial recognition
* **Passkeys**: WebAuthn-based authentication
* **Future Quantum-Proof**: Ready for post-quantum cryptography

Users can mix and match authentication methods and change them over time without affecting their account address or assets.

#### Cross-Chain Compatibility

Lumia Passport works seamlessly across multiple blockchains:

* Native support for all EVM-compatible chains
* Integration with Polygon AggLayer for unified liquidity
* Cross-chain account abstraction through Particle Network
* Atomic operations spanning multiple chains

Users maintain a single Passport identity while interacting with dApps deployed on different chains, with all bridging and interoperability handled automatically in the background.

### Compliance and Regulatory Features

#### KYC/AML Integration

Lumia Passport ensures regulatory compliance through:

**Global Regulatory Alignment**

The KYC process is designed to be flexible and adaptable to different jurisdictions:

* Country-specific KYC requirements
* Regional data protection compliance (GDPR, CCPA)
* Industry-specific regulations (MiFID II for financial services)
* Ongoing monitoring and reporting capabilities

**Institutional Requirements**

For institutional participants, Lumia Passport supports:

* Enhanced due diligence (EDD) procedures
* Accredited investor verification
* Corporate KYC for entities
* Beneficial ownership identification
* Source of funds verification

**Compliance Monitoring**

Ongoing compliance features include:

* **Transaction Monitoring**: Real-time analysis of transaction patterns
* **Risk Assessment**: Automated scoring based on behavior and associations
* **Reporting Tools**: Generate compliance reports for auditors and regulators
* **Alert Systems**: Flag suspicious activities for review
* **Audit Trail**: Immutable record of all KYC and compliance actions

#### Privacy-Preserving Compliance

Despite strict compliance requirements, Lumia Passport maintains user privacy:

* Credentials stored off-chain with only hashes on-chain
* Zero-knowledge proofs for verification without data exposure
* Selective disclosure of only necessary information
* Encrypted credential storage
* User-controlled data sharing

#### Real-World Asset (RWA) Enablement

Lumia Passport is essential for RWA applications:

**Asset Tokenization**

Enable compliant tokenization of real-world assets:

* Real estate properties
* Commodities (gold, diamonds, aluminum)
* Art and collectibles
* Intellectual property
* Securities and financial instruments

**Legal Framework Support**

Integration with legal and regulatory frameworks:

* Smart contract templates for compliant agreements
* Bailee agreements for asset custody
* Common law compliance structures
* Jurisdictional flexibility

**Fractional Ownership**

Enable compliant fractional ownership:

* Verify investor accreditation
* Enforce ownership transfer restrictions
* Maintain shareholder registries
* Distribute dividends or yields


# zkML

DeFi Models for Asset Management

Lumia L2 is at the forefront of integrating cutting-edge technologies to revolutionize the DeFi space. One of the key innovations we are introducing is the use of Zero-Knowledge Machine Learning (zkML) for asset management. By leveraging the power of off-chain AI models and bringing the data on-chain via zkML, we aim to provide our users with the best yield opportunities across the web3 ecosystem.

### Understanding zkML

Zero-Knowledge Machine Learning (zkML) is a groundbreaking approach that combines the principles of machine learning with zero-knowledge proofs (ZKPs). In the context of asset management, zkML allows us to train AI models on sensitive financial data without compromising privacy or security.

The core idea behind zkML is to enable the generation of outputs or predictions from an AI model without revealing the sensitive training data itself. This is achieved through the use of ZKPs, specifically zk-SNARKs (Zero-Knowledge Succinct Non-Interactive Argument of Knowledge).

zk-SNARKs provide a way to prove the integrity of the output generated by an AI model without disclosing the underlying model parameters or the training data. This ensures that the AI model's predictions are accurate and trustworthy, while maintaining the privacy and confidentiality of the data used to train the model.

### Building Off-Chain AI Models for Yield Optimization

At Lumia L2, we are developing sophisticated off-chain AI models that leverage the vast amount of data available across the web3 ecosystem. These models are designed to analyze various yield opportunities, both within Lumia L2 and on other platforms integrated into Lumia Steam.

Our AI models employ advanced machine learning techniques, such as deep learning and reinforcement learning, to identify the most promising yield opportunities. By considering factors such as market trends, historical performance, liquidity, and risk profiles, these models can provide data-driven insights and recommendations to optimize users' returns.

The off-chain nature of these AI models allows us to process large volumes of data efficiently and continuously update the models based on the latest market conditions. This ensures that the yield recommendations provided to our users are always up-to-date and reflect the current state of the web3 ecosystem.

### Bringing Data On-Chain via zkML

While the AI models operate off-chain, we utilize zkML to bring the relevant data and predictions on-chain in a secure and privacy-preserving manner. This is achieved through the use of zkML circuits built with Succint, a powerful zkML framework.

Succint enables us to convert the off-chain AI models into arithmetic circuits that can be executed on-chain. These circuits take the input data, perform the necessary computations, and generate zero-knowledge proofs that verify the integrity of the output without revealing the underlying data or model parameters.

The zkML circuits are designed to be highly efficient and scalable, allowing us to process large amounts of data and generate proofs quickly. This ensures that the yield recommendations provided to our users are not only accurate but also delivered in a timely manner.

### Custom EigenLayer AVS for Verification

To further enhance the security and trust in our zkML asset management system, we leverage a custom EigenLayer AVS (Actively Validated Services) for verification. EigenLayer is a cutting-edge framework that enables the creation of decentralized and trustless verification services.

Our custom EigenLayer AVS is specifically designed to verify the zero-knowledge proofs generated by the zkML circuits. It acts as an independent and decentralized verifier, ensuring that the proofs are valid and the output generated by the AI models is accurate.

The EigenLayer AVS operates on a decentralized network of nodes, each of which independently verifies the zkML proofs. This distributed verification process provides an additional layer of security and trust, as it eliminates the need for a single centralized verifier.

### Technical Breakdown

Here's a high-level technical breakdown of how zkML is integrated into Lumia L2 for asset management:

1. **Off-Chain AI Models**: We develop and train advanced AI models using state-of-the-art machine learning frameworks such as TensorFlow or PyTorch. These models are designed to analyze yield opportunities across the web3 ecosystem and provide data-driven recommendations.
2. **Data Preprocessing**: The input data for the AI models is preprocessed and normalized to ensure compatibility with the zkML circuits. This may involve techniques such as feature scaling, one-hot encoding, and data augmentation.
3. **zkML Circuit Compilation**: Using the Succint framework, we compile the off-chain AI models into zkML circuits. This process involves converting the model's computational graph into an arithmetic circuit representation that can be executed on-chain.
4. **Proof Generation**: The zkML circuits are executed off-chain using the preprocessed input data. During this process, the circuits generate zero-knowledge proofs that attest to the integrity of the output without revealing the underlying data or model parameters.
5. **On-Chain Verification**: The generated zkML proofs, along with the necessary public inputs, are submitted to the custom EigenLayer AVS for verification. The AVS nodes independently verify the proofs and reach a consensus on the validity of the output.
6. **Yield Recommendations**: Once the zkML proofs are verified, the yield recommendations generated by the AI models are made available to users on Lumia L2. These recommendations are presented in a user-friendly interface, allowing users to make informed decisions about their investments.
7. **Continuous Model Updates**: The off-chain AI models are periodically retrained and updated based on the latest market data and user feedback. This ensures that the yield recommendations remain accurate and relevant over time.

### Conclusion

By integrating zkML into our asset management system, Lumia L2 is revolutionizing the way users interact with DeFi platforms. Our off-chain AI models, powered by advanced machine learning techniques, provide data-driven yield recommendations that help users maximize their returns.

Through the use of zkML circuits built with Succint and verified by our custom EigenLayer AVS, we bring the power of AI on-chain in a secure, privacy-preserving, and trustless manner. This ensures that users can benefit from the insights generated by our AI models without compromising the confidentiality of their data.

As we continue to push the boundaries of zkML and AI in the DeFi space, Lumia L2 is well-positioned to become the go-to platform for users seeking the best yield opportunities across the web3 ecosystem. By combining cutting-edge technology with a user-centric approach, we are paving the way for a new era of intelligent and secure asset management in the decentralized world.


# Yield Optimiser Model

High level overview of Lumia's Off-Chain Model

### 1. Sentiment Analysis with Natural Language Processing (NLP)

To capture the social media presence and sentiment around DeFi platforms, particularly on Twitter, we will employ NLP techniques:

* Collect tweets related to DeFi platforms using relevant hashtags, token tickers, and keywords.
* Preprocess the tweet data by removing noise, handling abbreviations, and normalizing the text.
* Apply sentiment analysis models, such as VADER or BERT-based models, to quantify the sentiment associated with each platform.
* Incorporate the sentiment scores as features in the yield optimization model to capture the impact of social media sentiment on potential yields.

### 2. Time Series Forecasting with LSTM

To predict future APYs and capture the temporal dynamics of yield rates, we can use LSTM (Long Short-Term Memory) networks, a variant of recurrent neural networks (RNNs):

* Collect historical data on APYs, TVL growth, and other relevant time-dependent variables for each DeFi platform.
* Preprocess the time series data by normalizing, handling missing values, and creating appropriate time lags.
* Train an LSTM model to learn the temporal patterns and dependencies in the yield data.
* Use the trained LSTM model to forecast future APYs and capture potential APY drops based on TVL acquisition speed.

### 3. Ensemble Modelling

To incorporate multiple factors and improve the robustness of the yield optimization model, we will create an ensemble of different models:

* Build individual models for each factor, such as:
  * Regression models for the relationship between social media sentiment and yields.
  * Decision tree models for the impact of fees on yield optimization.
  * Gradient boosting models for the relationship between TVL growth and yields.
* Combine the predictions from these individual models using ensemble techniques like stacking or weighted averaging.
* The ensemble model will take into account the outputs from the sentiment analysis, time series forecasting, and other factor-specific models to provide a comprehensive yield recommendation.

### 4. Reinforcement Learning for Dynamic Optimization

To adapt to changing market conditions and optimize yields dynamically, we will employ reinforcement learning (RL) techniques:

* Formulate the yield optimization problem as a sequential decision-making task, where the RL agent (model) learns to make optimal decisions based on the current state of the DeFi ecosystem.
* Define the state space to include relevant factors such as social media sentiment, TVL growth, APYs, and fees.
* Define the action space as the selection of DeFi platforms or investment strategies.
* Design a reward function that incentivizes the RL agent to maximize yields while considering factors like APY drops and platform stability.
* Train the RL agent using algorithms like Q-learning or policy gradients to learn the optimal yield optimization strategy.

### 5. Continuous Learning and Adaptation

To ensure the model remains up-to-date and adapts to new trends and platforms, we will implement a continuous learning framework:

* Regularly collect new data on social media sentiment, APYs, TVL growth, and other relevant factors.
* Retrain the individual models (sentiment analysis, time series forecasting, factor-specific models) with the updated data.
* Fine-tune the ensemble model and the RL agent based on the latest data and user feedback.
* Monitor the performance of the yield optimization model and make adjustments as necessary.

<figure><img src="/files/PeL6G36hbzesfBaqnLnY" alt=""><figcaption><p>High Level Overview of Lumia's Off-Chain Yield Optimiser Model</p></figcaption></figure>

By combining these AI model methods - sentiment analysis with NLP, time series forecasting with LSTM, ensemble modelling, reinforcement learning, and continuous learning - Lumia L2 will create a robust and adaptive yield optimization model. This model will take into account various factors influencing DeFi yields, adapt to changing market conditions, and provide data-driven recommendations to maximize user returns.


# Interoperability

## Interoperability in Blockchain Networks

In the rapidly evolving landscape of blockchain technology, interoperability has emerged as a crucial aspect that enables seamless communication, data exchange, and value transfer between different blockchain networks. As the number of blockchain platforms continues to grow, each with its own unique features, consensus mechanisms, and token standards, the need for interoperability becomes increasingly evident.

### Understanding Interoperability

Interoperability refers to the ability of different blockchain networks to interact and communicate with each other, allowing for the exchange of information, assets, and value across different platforms. It enables users to transact across multiple blockchains without the need for intermediaries or centralized entities, thus preserving the decentralized nature of the blockchain ecosystem.

### The Importance of Interoperability

Interoperability is essential for several reasons:

1. **Scalability**: As the adoption of blockchain technology grows, the demand for scalable solutions becomes more pressing. Interoperability allows for the distribution of transactions and data across multiple networks, thereby reducing congestion and improving overall scalability.
2. **Liquidity**: Interoperability enables the seamless flow of assets and value across different blockchain networks, leading to increased liquidity. Users can access a wider range of assets and services, regardless of the specific blockchain they are using.
3. **Innovation**: Interoperability fosters innovation by allowing developers to build applications that can leverage the unique features and capabilities of different blockchain platforms. This opens up new possibilities for creating more sophisticated and feature-rich decentralized applications (dApps).
4. **User Experience**: With interoperability, users can enjoy a more seamless and convenient experience when interacting with different blockchain networks. They can use a single wallet or interface to access and manage their assets across multiple platforms, reducing friction and complexity.

### The Rise of Layer 2 Rollups and the Interoperability Challenge

The emergence of Layer 2 rollup solutions, such as Optimistic Rollups and Zero-Knowledge Rollups, has brought significant improvements in scalability and transaction throughput. These solutions aim to address the scalability limitations of Layer 1 blockchains by offloading computation and data storage to a secondary layer while still leveraging the security of the underlying blockchain.

However, the proliferation of Layer 2 solutions has also introduced new challenges in terms of interoperability. Each Layer 2 rollup may have its own specific implementation, token standards, and consensus mechanisms, making it difficult for them to interact and communicate with each other seamlessly.

Similarly, the rise of alternative Layer 1 blockchains, such as Binance Smart Chain, Polkadot, and Cosmos, has further highlighted the need for interoperability. These networks offer unique features and advantages but may not be directly compatible with each other or with existing Layer 1 blockchains like Ethereum.

### Solving the Interoperability Problem

To address the interoperability challenge, various solutions and protocols have been developed:

1. **Cross-Chain Bridges**: Cross-chain bridges enable the transfer of assets and data between different blockchain networks. They act as a link between two or more blockchains, allowing users to move their assets from one network to another without the need for a centralized intermediary.
2. **Atomic Swaps**: Atomic swaps are a type of cross-chain transaction that enables the exchange of cryptocurrencies between different blockchain networks without the need for a trusted third party. They ensure that either both parties receive their respective assets, or neither does, eliminating the risk of one party defaulting on the transaction.
3. **Interoperability Protocols**: Several interoperability protocols have been developed to facilitate communication and interaction between different blockchain networks. These protocols, such as Polkadot, Cosmos, and Interledger, provide a framework for cross-chain communication, allowing different blockchains to exchange information and value seamlessly.
4. **Standardization Efforts**: Efforts are being made to establish common standards and protocols that can be adopted by different blockchain networks to enhance interoperability. Initiatives like the InterWork Alliance and the Blockchain Interoperability Alliance aim to create a unified framework for blockchain interoperability.

### Conclusion

Interoperability is a critical component of the blockchain ecosystem, enabling seamless communication, data exchange, and value transfer between different networks. As the adoption of blockchain technology continues to grow, with the rise of Layer 2 rollups and alternative Layer 1 blockchains, the need for effective interoperability solutions becomes even more pressing.

By developing cross-chain bridges, atomic swaps, interoperability protocols, and promoting standardization efforts, the blockchain community is actively working towards overcoming the interoperability challenge. Enabling seamless interaction between different blockchain networks will unlock new opportunities for scalability, liquidity, innovation, and improved user experiences, ultimately driving the mass adoption of blockchain technology.


# Polygon AggLayer

Unlocking Seamless Interoperability for Lumia chain

As a PolygonCDK-based Layer 2 solution, Lumia  is poised to benefit greatly from the advent of Polygon's AggLayer. This groundbreaking innovation aims to address the challenges of interoperability and fragmented liquidity in the blockchain ecosystem, providing a unified and seamless experience for users and developers alike.

### Understanding Polygon AggLayer

Polygon AggLayer is a decentralized aggregation protocol designed to enable secure and low-latency cross-chain transactions. It serves as an interconnected network of ZK-powered Layer 2 (L2) chains, allowing for the free flow of data and assets across the Polygon ecosystem.

The AggLayer utilizes a process called "proof aggregation" to verify the validity of transactions across multiple chains in a single step. Individual chains submit proofs of their transactions and state updates to the AggLayer, which then combines these proofs into a single "aggregated proof." This aggregated proof is submitted to the Ethereum mainnet for verification, ensuring the validity of all transactions across the ecosystem.

### Benefits of AggLayer for Lumia

The integration of Polygon AggLayer brings numerous benefits to Lumia chain and its users:

1. **Low-Latency Cross-Chain Transactions**: AggLayer enables faster interaction between Lumia chain and other chains within the Polygon ecosystem compared to traditional bridging methods. This means that Lumia chain users can enjoy near-instantaneous cross-chain transactions, enhancing the overall user experience.
2. **Shared Liquidity**: With AggLayer, assets and data can flow freely across the Polygon ecosystem, including Lumia chain. This shared liquidity pool allows Lumia chain to access a wider range of assets and enables improved capital efficiency for its users.
3. **Scalability**: AggLayer is designed to handle a growing number of interconnected chains, providing a scalable infrastructure for Lumia chain to operate within. As the Polygon ecosystem expands, Lumia chain can seamlessly integrate with new chains and leverage their functionalities.
4. **Security**: AggLayer utilizes ZK proofs and advanced cryptographic mechanisms to ensure the safety and integrity of cross-chain transactions. This provides an additional layer of security for Lumia chain and its users, reducing the risk of fraudulent activities and enhancing overall trust in the system.
5. **Flexibility**: Despite being part of the interconnected Polygon ecosystem, Lumia chain maintains its sovereignty over its execution environment and sequencer. This flexibility allows Lumia chain to customize its operations and cater to the specific needs of its users while still benefiting from the interoperability provided by AggLayer.

### The Future of Interoperability with AggLayer

Polygon AggLayer represents a significant step forward in the pursuit of seamless interoperability within the blockchain ecosystem. It enables chains like Lumia chain to operate independently while providing a unified user experience for cross-chain interactions.

With the integration of AggLayer, Lumia chain can participate in two types of interoperability scenarios:

1. **Type 1: Asynchronous Interoperability**: In this scenario, Lumia chain can rely on temporary state assumptions for faster processing of cross-chain transactions. While this approach prioritizes speed, it also includes safety mechanisms to ensure the integrity of the transactions.
2. **Type 2: Atomic Interoperability**: AggLayer enables Lumia chain to engage in seamless cross-chain bundle execution. This means that transactions involving multiple chains can be executed atomically, ensuring that they either succeed or fail across all involved chains. This type of interoperability provides a higher level of consistency and reliability for complex cross-chain operations.

As the Polygon ecosystem continues to grow and evolve, Lumia chains integration with AggLayer positions it at the forefront of interoperability innovation. By leveraging the power of ZK proofs and the aggregation capabilities of AggLayer, Lumia chain can offer its users a seamless and efficient cross-chain experience, unlocking new possibilities for decentralized applications and use cases.

### Conclusion

Polygon AggLayer is a game-changer for interoperability in the blockchain space, and Lumia chain is well-positioned to capitalize on its benefits. By integrating with AggLayer, Lumia L2 can provide its users with low-latency cross-chain transactions, shared liquidity, scalability, enhanced security, and flexibility.

As the future of interoperability unfolds, Lumia chains participation in both asynchronous and atomic interoperability scenarios through AggLayer will enable it to stay at the cutting edge of blockchain innovation. With AggLayer, Lumia chain can contribute to the vision of a unified Polygon ecosystem, where chains operate seamlessly together, mirroring the scalability, permissionless nature, and interconnectedness of the internet.


# HyperLane

Expanding Lumia Chains Interoperability Horizons

Lumia chain, being a PolygonCDK-based Layer 2 solution, is committed to providing its users with the best possible interoperability experience. In addition to leveraging Polygon's AggLayer for seamless cross-chain interactions, Lumia chain has integrated Hyperlane, a universal and permissionless interoperability layer designed for the modular blockchain stack.

{% hint style="success" %}
HyperLane Mainnet bridge between **Lumia <> Ethereum <> BSC** is now live!

<https://hyper.lumia.org>

[https://www.usenexus.org](https://www.usenexus.org/)
{% endhint %}

### What is Hyperlane?

Hyperlane is a groundbreaking interoperability solution that allows smart contract developers to send arbitrary data between blockchains. It is the first permissionless interoperability layer that can be deployed to any blockchain environment, including Layer 1 chains, rollups, and app-chains.

With Hyperlane, developers can build Interchain Applications - apps that span multiple blockchains, enabling users to access them from any supported chain. Hyperlane offers implementations for various execution environments and is compatible with all leading rollup frameworks.

### Key Features of Hyperlane

1. **Modular Design**: Hyperlane is built with modularity in mind, providing developers with control over their security model through Interchain Security Modules (ISMs). This allows developers to configure, compose, and customize security according to the specific needs of their application.
2. **Pre-built Examples**: Hyperlane offers several pre-built examples that can be deployed out of the box, such as Warp Routes for seamless cross-chain token transfers, Interchain Accounts for cross-chain smart contract interactions, and Interchain Queries for cross-chain view calls.
3. **Permissionless Deployment**: Anyone can permissionlessly deploy Hyperlane to any supported blockchain environment, enabling seamless communication between chains without the need for centralized authorities or permissions.

### Key Components

The Hyperlane protocol decouples the transport layer from the security layer of cross-chain message passing. To run a deployment, it relies on offchain agents that observe onchain activity and carry out either the transport or security aspects of the protocol.

These agents are implemented in Rust and distributed as Docker images and binaries.

* [Relayers](https://docs.hyperlane.xyz/docs/protocol/agents/relayer) fulfill the message transport requirement of the protocol. They aggregate off-chain security metadata for the [`IInterchainSecurityModule` interface](https://docs.hyperlane.xyz/docs/reference/ISM/specify-your-ISM) and deliver messages to their recipients.
* [Validators](https://docs.hyperlane.xyz/docs/protocol/agents/validators) fulfill the security requirement of the protocol, as part of the [Multisig ISM](https://docs.hyperlane.xyz/docs/protocol/ISM/multisig-ISM) or the [Hyperlane AVS](https://docs.hyperlane.xyz/docs/protocol/economic-security/hyperlane-avs), by attesting to the validity of [Mailbox](https://docs.hyperlane.xyz/docs/protocol/mailbox) messages and making their signatures available to a relayer.

### Benefits of Hyperlane Integration for Lumia Chain

By integrating Hyperlane alongside AggLayer, Lumia chain gains several significant advantages:

1. **Enhanced Interoperability**: Hyperlane's permissionless and modular design allows Lumia chain to communicate seamlessly with any other chain that has Hyperlane deployed, expanding its interoperability reach beyond the Polygon ecosystem.
2. **Customizable Security**: Hyperlane's Interchain Security Modules (ISMs) empower Lumia chain to tailor its security model based on the specific requirements of its applications, ensuring a robust and secure interoperability experience.
3. **Increased Liquidity**: With Hyperlane's Warp Routes, Lumia chain can facilitate the seamless transfer of ERC20 and ERC721-like assets across chains, enabling users to access and trade assets from various blockchain ecosystems, ultimately increasing liquidity and user engagement.
4. **Expanded Functionality**: Hyperlane's Interchain Accounts and Interchain Queries allow Lumia chain to offer advanced cross-chain functionalities, such as executing smart contract calls and making view calls on remote chains, further enriching the capabilities of its interchain applications.

### Conclusion

The integration of Hyperlane alongside AggLayer positions Lumia chain at the forefront of interoperability innovation. By leveraging the strengths of both solutions, Lumia chain can provide its users with an unparalleled cross-chain experience, enabling seamless communication, asset transfers, and advanced interchain functionalities.

As Lumia chain continues to evolve and expand its interoperability horizons, the combination of AggLayer and Hyperlane will serve as a powerful foundation for building the next generation of interchain applications. This dual integration approach ensures that Lumia chain remains at the cutting edge of blockchain technology, offering its users the best possible interoperability experience and unlocking new possibilities for decentralized applications and use cases.


# KYC

## KYC and Passport Integration on Lumia Chain

At Lumia chain, we understand the importance of compliance, user privacy, and the need for secure identity verification in the rapidly evolving DeFi landscape. To address these critical aspects, we have made the strategic decision to integrate KYC (Know Your Customer) and Passport into our Layer 2 solution. This integration not only ensures that we meet regulatory requirements but also opens up new possibilities for institutional onboarding and the development of RWA (Real-World Asset) dApps.&#x20;

### Decentralized Identity Verification with Passport

Lumia chain leverages the power of custom solution named Passport (see Lumia Passport), a decentralized identity solution built on zero-knowledge proofs and blockchain technology. Passport enables secure and private identity verification, allowing users to selectively disclose their personal information without compromising their privacy.

By integrating Passport, Lumia chain offers a seamless and user-friendly KYC process. Users can easily create their digital identities, known as Lumia Passports, which securely store their verified credentials. These credentials can include personal information, such as name, address, and date of birth, as well as additional KYC-related documents like government-issued IDs and proof of address.

The Passport serves as a reusable identity across various dApps and services within the Lumia chain ecosystem. Users can choose to share specific credentials with dApps that require KYC, without exposing their entire identity. This selective disclosure mechanism empowers users to maintain control over their personal data while facilitating secure and compliant interactions.

### Compliance with Global Regulations

One of the primary reasons for integrating KYC and Passport into Lumia chain is to ensure compliance with global regulations. As the DeFi space matures, regulatory bodies are increasingly focusing on the need for AML (Anti-Money Laundering) and CFT (Combating the Financing of Terrorism) measures.

By implementing KYC, Lumia chain aligns itself with these regulatory requirements, demonstrating our commitment to operating within legal frameworks. This compliance not only mitigates the risk of illicit activities but also enhances the overall trust and credibility of our platform.

Lumia chains KYC integration is designed to be flexible and adaptable to different jurisdictions. We understand that regulatory landscapes vary across countries, and our KYC process can be customized to meet the specific requirements of each region. This adaptability ensures that Lumia chain can operate globally while remaining compliant with local regulations.

### Enabling Institutional Onboarding

The integration of KYC and Passport on Lumia chain plays a crucial role in facilitating institutional onboarding. Traditional financial institutions, such as banks, hedge funds, and asset managers, are increasingly interested in participating in the DeFi ecosystem. However, these institutions have stringent KYC/AML requirements that must be met before they can engage with any platform.

By offering a robust and compliant KYC solution, Lumia chain becomes an attractive option for institutional investors. Our KYC process, powered by Lumia Passport, provides the necessary assurances that these institutions require, enabling them to confidently participate in the Lumia L2 ecosystem.

Institutional onboarding brings several benefits to Lumia chain. It attracts significant liquidity, which can fuel the growth and development of the platform. Moreover, the involvement of institutional players adds credibility and stability to the ecosystem, as these entities often have a long-term investment perspective and are less prone to short-term speculation.

### Enabling RWA dApps

Another compelling reason for integrating KYC and Passport into Lumia chain is to enable the development of RWA (Real-World Asset) dApps. RWA dApps bridge the gap between traditional assets and the DeFi ecosystem, allowing users to tokenize and trade real-world assets such as real estate, commodities, and intellectual property.

KYC is a critical component for RWA dApps, as these applications often involve the transfer of ownership and the establishment of legal contracts. By providing a secure and compliant KYC process, Lumia L2 creates a foundation for RWA dApps to thrive.

Developers building RWA dApps on Lumia chain can leverage the Passport to streamline user onboarding and ensure that all participants are properly verified. This not only enhances the security and legitimacy of RWA transactions but also opens up new opportunities for asset tokenization and fractional ownership.

### Technical Implementation

Integrating KYC and Passport into Lumia chain involves several technical components. Let's explore some of the key aspects:

1. **Passport SDK**: Lumia chain utilizes the Passport SDK, which provides a set of tools and libraries for integrating Passport into our platform. The SDK includes functionalities for identity creation, credential issuance, and verification.
2. **Zero-Knowledge Proofs**: Passport leverages zero-knowledge proofs (ZKPs) to enable secure and privacy-preserving identity verification. ZKPs allow users to prove the validity of their credentials without revealing the actual data. Lumia chains integrates the necessary ZKP circuits and libraries to support this functionality.
3. **Credential Issuance**: Lumia chain partners with trusted identity providers and KYC/AML service providers to issue verified credentials to users. These credentials are cryptographically signed and stored on the blockchain, ensuring their immutability and authenticity. Current partner Sumsub.
4. **Passport Smart Contract**: Passport is implemented as a smart contract on the Lumia L2 blockchain. This smart contract manages the storage and verification of user credentials, as well as the access control mechanisms for dApps requesting KYC information.
5. **Selective Disclosure**: Lumia chain implements selective disclosure protocols that allow users to share specific credentials with dApps without revealing their entire identity. This is achieved through the use of zero-knowledge proofs and cryptographic techniques like Merkle trees and commitment schemes.
6. **Compliance Monitoring**: Lumia chain incorporates compliance monitoring tools and processes to ensure ongoing adherence to regulatory requirements. This includes transaction monitoring, risk assessment, and reporting functionalities.
7. **Developer SDKs and APIs**: Lumia chain provides developer SDKs and APIs that make it easy for dApp developers to integrate KYC and Passport into their applications. These tools abstract away the complexities of identity verification and provide a seamless user experience.

### Conclusion

The integration of KYC and Passport into Lumia chain represents a significant step forward in terms of compliance, user privacy, and enabling institutional participation in the DeFi ecosystem. By leveraging the power of decentralized identity and zero-knowledge proofs, Lumia chain provides a secure and user-friendly KYC solution that meets the evolving needs of the DeFi landscape.

Compliance with global regulations, the ability to onboard institutional investors, and the enablement of RWA dApps are just a few of the compelling reasons behind this integration. As Lumia chain continues to grow and evolve, we remain committed to providing a platform that prioritizes user privacy, security, and compliance, while unlocking new opportunities for innovation and growth in the DeFi space.


# Chain & Account Abstraction with Intents

Lumia chain is committed to revolutionizing the user experience in the DeFi space by integrating cutting-edge technologies like Chain Abstraction (CA) with Account Abstraction (AA) and Intents.  Lumia chain aims to create a seamless, user-friendly, and secure trading environment for both seasoned DeFi users and newcomers from the Web2 world.

### Chain Abstraction with Particle Network

The Web3 experience is far from feeling intuitive or universal. Different chains incentivize users to exclusively utilize their network and require different wallets to interact with them. Meanwhile, protocols decide which chain to deploy on by prioritizing co-marketing activities, TVL, and market sentiment, not technology or innovation. This creates siloed and incompatible ecosystems, stunting Web3’s growth and limiting it to technically aware users.

The solution to this problem is **chain abstraction**: the simplification of users’ interactions with blockchains, allowing them to use any product and asset without worrying about managing multiple wallets, bridging, underlying blockchains, etc.&#x20;

By integrating Particle Network, Lumia chain is working towards creating a unified and seamless user experience across different chains, fostering broader adoption and facilitating easier interaction for users, regardless of their technical background.

### Typical Flow in Chain Abstraction

A fully chain-abstracted experience leveraging zkEVM L2 technology could unfold as follows:

1. Alice discovers a Play-to-Earn dApp deployed on Arbitrum, an Optimistic Rollup L2 solution.
2. Alice initiates interaction with the dApp using her Universal Account, which is compatible with multiple chains including Lumia. The account abstraction layer, implemented using EIP-4337, manages the complexities of cross-chain interactions.
3. As Alice starts using the dApp, her assets (native to our Lumia chain) are utilized for basic dApp interactions. The bridging process is abstracted away from the user:&#x20;
   1. A cross-chain interoperability protocol (e.g., LayerZero or Hyperlane) facilitates the asset transfer.&#x20;
   2. Lumia L2's built-in bridge smart contract locks the assets on our chain.&#x20;
   3. A corresponding amount is minted on Arbitrum through its bridge contract.&#x20;
   4. This process is executed atomically as part of her transaction, leveraging zk-proofs for rapid finality.
4. After engaging with the dApp, Alice earns tokens native to Arbitrum. She decides to purchase an NFT for her friend Bob's birthday. Unknown to Alice, this NFT is minted on Optimism, another L2 solution.
5. The purchase and transfer process are seamlessly handled:&#x20;
   1. The interoperability protocol initiates a cross-chain swap from Arbitrum to Optimism.&#x20;
   2. The NFT is transferred to Bob's Universal Account, which is compatible across multiple chains.&#x20;
   3. Throughout this process, Alice only uses a single gas token i.e. LUMIA, with gas fees for other chains being abstracted and handled in the background.
6. Bob, upon receiving the NFT, decides to take a loan against it on Solana. The process unfolds as follows:&#x20;
   1. The Universal Account, leveraging a cross-chain oracle network, verifies the NFT's ownership and value across chains.&#x20;
   2. A smart contract on Solana creates a wrapped representation of the Optimism-based NFT.&#x20;
   3. This wrapped NFT is used as collateral for the loan, with the loan amount being disbursed in Solana's native token.
7. Bob then uses the loan proceeds to purchase a Bitcoin Ordinal
   1. An atomic swap is executed between Solana and Bitcoin networks.&#x20;
   2. The Ordinal is transferred to a Bitcoin address associated with Bob's Universal Account.

This entire process, from Alice's initial interaction to Bob's final purchase, is executed within minutes through a unified interface. The underlying complexity of cross-chain interactions, bridging, and asset transfers is entirely abstracted away, providing a seamless user experience while leveraging the strengths of various blockchain networks.

Account Abstraction is a game-changing concept that enhances user experience by making user accounts more flexible and functional. Instead of using an Externally Owned Account (EOA), a Smart Contract can act as the user's account, powered by code instead of the Elliptic Curve Digital Signature Algorithm (ECDSA).

Lumia L2 integrates ERC 4337-compliant Smart Account solution, which works with any Paymaster and Bundler service. This integration brings several benefits to the Lumia chain ecosystem:

1. **Simplified User Onboarding**: With AA, users no longer need to worry about creating and managing traditional EOAs. Lumia chains Smart Account creation process is streamlined, making it easier for Web2 users to enter the DeFi space without the complexities associated with traditional wallets.
2. **Gasless Transactions**: Paymaster service enables Lumia chain to sponsor transactions or accept ERC-20 tokens as payment for gas. This eliminates the need for users to hold native tokens to cover gas fees, providing a frictionless trading experience.
3. **Enhanced Security**: Smart Accounts are enhanced by different modules that allow the execution of arbitrary logic before validating a userOp. This enables Lumia chain to implement advanced security features like session keys, multi-chain validation, and passkeys, ensuring the safety of user funds.
4. **Flexible Authorization**: Lumia chains Smart Accounts are signer agnostic, meaning users can utilize any authorization package as long as a signer is passed to the SDK during Smart Account creation. This flexibility allows users to choose their preferred authentication method, enhancing user experience and adoption.

### Intents with Lumia Stream

Lumia chain integrates Lumia Stream's Intents to provide a superior trading experience for its users. Intents are a novel approach to order fulfilment that offers several advantages over traditional on-chain trading:

1. **MEV Protection**: Lumia Stream provides protection against Maximal Extractable Value (MEV) or front-running attacks. This ensures fair trade execution and prevents potential financial loss, instilling confidence in Lumia chain users.
2. **Optimal Price Efficiency**: Lumia Stream's Resolvers source liquidity from across the entire DeFi market, providing Lumia chain users with optimal order matching and minimizing potential losses from negative price impact.
3. **Intent-based Order Fulfilment**: Unlike classic swaps, Lumia chains integration of Lumia Stream allows for intent-based order fulfilment. Liquidity Nodes compete to fill orders and provide the best price, following a probabilistic order assignment mechanism. This ensures that users receive the best possible price for their trades.

### Conclusion

By integrating Chain and Account Abstraction with Intents into its ecosystem, Lumia chain is set to redefine the DeFi user experience. Particle Network's Chain Abstraction with Lumia's own Passport solution and Lumia Stream's Intents creates a powerful platform that offers simplicity, security, and cost-effectiveness.

With gasless transactions, MEV protection, optimal price efficiency, and intent-based order fulfilment, Lumia chain removes the barriers to entry for Web2 users and provides a seamless trading experience for all.


# Particle Connect on Lumia

Particle Network provides Wallet Abstraction services with an Account Abstraction stack, simplifying user onboarding with options like social logins and Web3 wallets.

The Particle Connect SDK supports multiple EVM-compatible chains, including Lumia, enabling easy 2-click integration into EOAs (Externally Owned Accounts) and smart contract-based accounts.

### Objectives

By the end of this tutorial, you’ll be able to set up a Particle Connect project to create an Externally-Owned Account (EOA) using social login, link a SIMPLE instance of a smart account to the generated EOA, enable streamlined 2-click login processes, and build and perform a gasless transaction.

### Prerequisites

#### Wallet Funds

To follow along with this guide, you’ll need Lumia testnet tokens to demonstrate the gasless transaction process. You can fund your wallet using the faucet on the Lumia Docs page.

### Understanding Particle Network

#### Wallet Abstraction

Particle Network offers SDKs designed to reduce account-based friction for Web3 users as they onboard and manage wallets within applications. In this guide, friction mainly refers to login complexity: consumer-facing dApps often need login flows that avoid requiring users to download or manage traditional wallets, which can be a barrier.

Particle Connect is one of Particle's flagship onboarding SDKs, offering a unified modal for both social logins and Web3 wallet connections.

#### Account Abstraction

Particle Network also addresses account flexibility through Account Abstraction, moving from standard EOAs to smart accounts. Smart accounts, as programmable smart contracts, offer the flexibility of EOAs while allowing customized functionality.

Particle Network provides a `SimpleAccount` implementation on **Lumia**, allowing users easy access to smart accounts.

### Integrating Particle Connect

The Particle Connect SDK streamlines wallet creation, user login, and blockchain interactions. It offers a unified interface for social logins and traditional Web3 wallets, providing an accessible experience for all users, regardless of their familiarity with Web3.

#### Set Up a New Next.js Project

To start, create a new [Next.js](https://nextjs.org/) project using the Next.js CLI. Follow the prompts to set up the project with TypeScript and Tailwind CSS enabled.

```sh
$ npx create-next-app@latest

# Select the following options:
What is your project named? particle-connect-app
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the import alias (`@/*` by default)? No
```

#### Install Required Dependencies

Next, install the necessary dependencies:

```sh
# Using Yarn
yarn add @particle-network/connectkit viem@^2

# OR with npm
npm install @particle-network/connectkit viem@^2
```

This command installs the latest version of the Particle Connect SDK along with Viem v2, the default library Particle Connect uses for blockchain interactions and transactions. :::info The Particle Connect SDK includes built-in Account Abstraction, so it’s the only Particle package you need. If you prefer to use other EIP-1193 providers (like ethers), you’ll need the [Particle AA SDK](https://docs.particle.network/). For more information, see the [Particle Documentation](https://docs.particle.network/). :::

#### Configure Particle Connect

After installing dependencies, set up a project and application in the Particle Dashboard to obtain the `projectId`, `clientKey`, and `appId` needed for Particle Connect.

Here’s how:

1. Log in to the [Particle Dashboard](https://dashboard.particle.network) using your email.
2. Select **Add New Project** and enter a project name.
3. Copy the **Project ID** and **Client Key** provided.
4. Add a new application by selecting **Web** as the platform.
5. Name the application and specify its domain. Any placeholder (e.g., 'test.com') will work if you don't have a domain yet.
6. Copy the **App ID** once the application is created.

Store these API keys in a `.env` file in the root of your project, following this structure:

```plaintext
NEXT_PUBLIC_PROJECT_ID='PROJECT_ID'
NEXT_PUBLIC_CLIENT_KEY='CLIENT_KEY'
NEXT_PUBLIC_APP_ID='APP_ID'
```

Now, you’re ready to configure Particle Connect. Start by creating a `Connectkit.tsx` file in the `src` directory with the following code:

```ts
'use client';

import React from 'react';
import { ConnectKitProvider, createConfig } from '@particle-network/connectkit';
import { authWalletConnectors } from '@particle-network/connectkit/auth';
import { defineChain } from '@particle-network/connectkit/chains';

// Define the Lumia testnet
const lumiaTestnet = defineChain({
  id: 2030232745,
  name: "Lumia Beam Testnet",
  nativeCurrency: {
    decimals: 18,
    name: "LUMIA",
    symbol: "LUMIA",
  },
  rpcUrls: {
    default: {
      http: ["https://beam-rpc.lumia.org/"],
    },
  },
  blockExplorers: {
    default: { name: "Explorer", url: "https://beam-explorer.lumia.org/" },
  },
  testnet: true,
});

const config = createConfig({
  projectId: process.env.NEXT_PUBLIC_PROJECT_ID!,
  clientKey: process.env.NEXT_PUBLIC_CLIENT_KEY!,
  appId: process.env.NEXT_PUBLIC_APP_ID!,
  walletConnectors: [authWalletConnectors({})],

  plugins: [
    aa({
      name: 'SIMPLE',
      version: '2.0.0',
    }),
  ],

  chains: [lumiaTestnet],
});

export const ParticleConnectkit = ({ children }: React.PropsWithChildren) => {
  return <ConnectKitProvider config={config}>{children}</ConnectKitProvider>;
};
```

This file exports the `ParticleConnectKit` component, where you input project keys and configure SDK settings.

In this example, API keys are loaded from `.env`, social logins are enabled via `authWalletConnectors`, a `SIMPLE` smart account is set up, and supported chains are limited to the Lumia Testnet.

> **Note**: This example provides a basic `ConnectKit.tsx` setup. For detailed configurations, see the [Particle Connect documentation](https://developers.particle.network/api-reference/connect/desktop/web#configuration).

#### Integrate the `ParticleConnectKit` Component in Your App

With the configuration ready, wrap your application with the `ParticleConnectKit` component to enable global access to the Particle Connect SDK. Here’s an example setup in your `layout.tsx` file within `src`:

```ts
import { ParticleConnectkit } from '@/connectkit';
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Particle Connectkit App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <ParticleConnectkit>{children}</ParticleConnectkit>
      </body>
    </html>
  );
}
```

#### Enabling Login and Wallet Connection

With Particle Connect set up, you can enable your app's social logins and wallet connections using the `ConnectButton` component from the Particle ConnectKit library. Here’s a basic implementation that you can add to the `page.tsx` file in the `src` directory:

```ts
import { ConnectButton, useAccount } from '@particle-network/connectkit';

export const App = () => {
  const { address, isConnected, chainId } = useAccount();

  return (
    <div>
      <ConnectButton />
      {isConnected && (
        <>
          <h2>Address: {address}</h2>
          <h2>Chain ID: {chainId}</h2>
        </>
      )}
    </div>
  );
};
```

This code snippet provides a straightforward interface for logging in and connecting users to your app, displaying their wallet address and the connected blockchain’s chain ID upon authentication.

> For more application-level hooks, see the [Particle Connect SDK documentation](https://developers.particle.network/api-reference/connect/desktop/web#key-react-hooks-for-particle-connect).

### Sending a Gasless Transaction

Particle Connect provides all the infrastructure needed to send gasless transactions easily. A gasless transaction allows users to interact with the blockchain without needing to cover gas fees. Instead, fees can be sponsored, improving user experience.

Unlike standard transactions, gasless transactions sent through ERC-4337 account abstraction use a structure called `UserOperations` (or `UserOps`).

This section will guide you through building a `UserOp`.

#### Step 1: Create a Smart Account Instance

Start by creating an instance of `smartAccount`, which enables you to sign transactions and use Particle Connect’s infrastructure for gasless operations.

```ts
import { useSmartAccount } from '@particle-network/connectkit';
import { parseEther } from 'viem'; // To be used in the transaction function

// Inside your component or app
const smartAccount = useSmartAccount();
```

This code initializes `smartAccount` as the primary signer, allowing transaction execution through Particle Connect.

#### Step 2: Execute a Gasless Transaction

With the `smartAccount` instance ready, you can perform a gasless transaction by creating a `UserOperation` (`userOp`). Here’s an example that transfers 0.01 LUMIA without requiring the user to pay gas fees.

```ts
const executeTxNative = async () => {
  const tx = {
    to: recipientAddress, // Recipient's address
    value: parseEther('0.01').toString(), // Amount to send (in ETH)
  };

  // Fetch fee quotes and set up the transaction for gasless execution
  const feeQuotesResult = await smartAccount?.getFeeQuotes(tx);
  const { userOp, userOpHash } = feeQuotesResult?.verifyingPaymasterGasless || {};

  if (userOp && userOpHash) {
    const txHash = await smartAccount?.sendUserOperation({ userOp, userOpHash });
    console.log('Transaction sent:', txHash);
  }
};
```

This code shows how to build a `UserOp` and execute a gasless transaction with `smartAccount` as the signer.

### Complete `page.tsx` File

Now that you have an understanding of each step, let’s bring everything together in the `page.tsx` file:

```ts
import React, { useState } from 'react';
import { ConnectButton, useAccount, useSmartAccount } from '@particle-network/connectkit';
import { parseEther } from 'viem'; // Used to handle ETH value parsing

export const App = () => {
  const { address, isConnected, chainId } = useAccount(); // Fetch user account information
  const smartAccount = useSmartAccount(); // Initialize smart account
  const [recipientAddress, setRecipientAddress] = useState(''); // State to store recipient address
  const [transactionHash, setTransactionHash] = useState(''); // State to store transaction hash

  // Function to execute gasless transaction
  const executeTxNative = async () => {
    if (!recipientAddress) {
      alert('Please enter a recipient address');
      return;
    }

    const tx = {
      to: recipientAddress, // Recipient's address
      value: parseEther('0.01').toString(), // Amount to send (in ETH)
      data: '0x', // No additional data for a basic transfer
    };

    // Fetch fee quotes and execute the gasless transaction
    const feeQuotesResult = await smartAccount?.getFeeQuotes(tx);
    const { userOp, userOpHash } = feeQuotesResult?.verifyingPaymasterGasless || {};

    if (userOp && userOpHash) {
      const txHash = await smartAccount?.sendUserOperation({ userOp, userOpHash });
      setTransactionHash(txHash); // Set the transaction hash state
      console.log('Transaction sent:', txHash);
    } else {
      console.error('Error fetching gasless transaction details');
    }
  };

  return (
    <div>
      <ConnectButton /> {/* Button to connect wallet */}
      {isConnected && (
        <>
          <h2>Address: {address}</h2>
          <h2>Chain ID: {chainId}</h2>

          <div>
            <label>Recipient Address: </label>
            <input
              type="text"
              value={recipientAddress}
              onChange={(e) => setRecipientAddress(e.target.value)}
              placeholder="Enter recipient address"
            />
          </div>

          <button onClick={executeTxNative}>Send 0.01 LUMIA Gasless</button>

          {transactionHash && (
            <div>
              <h3>Transaction Hash: {transactionHash}</h3>
            </div>
          )}
        </>
      )}
    </div>
  );
};
```

This code creates a simple interface for sending gasless transactions, with an input for the recipient’s address and a display for the transaction hash upon success.

#### Running the Application:

1. Navigate to your project’s root directory.
2. Start the server with `npm run dev` or `yarn dev`.
3. Log in with a social account.
4. Fund the displayed wallet address.
5. Enter the recipient’s address.
6. Click **Send 0.01 LUMIA Gasless** to complete the transaction.

#### Quickstart Guide

For a detailed, step-by-step setup of a new project with Particle Connect, refer to the [Particle Connect Quickstart](https://developers.particle.network/guides/wallet-as-a-service/waas/connect/web-quickstart) in the Particle Network documentation.

### Conclusion

You’ve successfully built an application from scratch, enabling user onboarding into smart accounts via social logins with Particle Connect.


# Real World Assets (RWA) on Lumia

Real World Assets (RWAs) represent tangible or intangible assets from the physical world that have been tokenized on the blockchain. Lumia chain focuses on bringing these assets on-chain, creating new opportunities for investment, liquidity, and financial innovation.

Specifically, Lumia chain specializes in tokenizing commodities such as diamonds, aluminium, copper, iron ore, silver, gold, and other precious metals.

### Regulatory Compliance

Lumia Foundation is taking significant steps to ensure regulatory compliance and legal accountability for RWA tokenization:

1. **Acquiring Licenses:** Lumia Foundation is in the process of obtaining necessary licensing from regulatory authorities in the UAE and Australia. These licenses will provide a solid legal framework for RWA tokenization operations.
2. **Legal Protection:** The licensing and regular audit reports of the commodities and their condition provides strong legal protection for asset owners and token holders, ensuring that the tokenized assets are backed by real, verifiable commodities.

### Tokenization Process on Lumia chain

Lumia chain provides a seamless and legally compliant process for RWA owners to tokenize their assets:

1. Asset owners provide proof of ownership, necessary documentation, and undergo required due diligence.
2. The asset is valued by approved third-party appraisers and tokenized on Lumia chain.
3. Tokens representing the RWA are created and can be fractionalized if desired.
4. These tokens are then made available for trading or used as collateral in DeFi applications.

### Bringing Liquidity to RWAs

One of the key challenges with RWAs in the blockchain space has been providing sufficient liquidity. Lumia chain addresses this challenge through its innovative Lumia Stream system, which bridges centralized exchange (CEX) and decentralized exchange (DEX) liquidity.

#### Lumia Stream: Bridging CEX and DEX Liquidity

Lumia Stream acts as a liquidity aggregator, pulling together liquidity from both centralized and decentralized sources. This creates a deep and diverse liquidity pool that can be accessed by RWA tokens, solving one of the primary obstacles to RWA adoption in DeFi.

#### Liquidity Provisioning for RWAs

1. RWA tokens are integrated into Lumia Pools, which use a constant product formula (e.g., 50% RWA, 50% Stablecoin).
2. Lumia Stream creates liquidity nodes for RWA tokens, allowing for efficient market-making.
3. The DNLP (Delta Neutral Liquidity Provision) Smart Contract locks assets and provides additional liquidity support.
4. Centralized exchanges can provide off-chain hedging opportunities, further enhancing liquidity.

#### Making RWAs DeFi Composable

By bringing significant liquidity to RWA tokens, Lumia chain enables these assets to become fully composable within the DeFi ecosystem:

1. Collateralization: RWA tokens can be used as collateral in lending protocols, allowing users to borrow against their real-world assets.
2. Yield Generation: Liquidity providers can earn yields by contributing RWA tokens to Lumia Pools.
3. Cross-Chain Availability: Through Lumia chains interoperability features, RWA tokens can be made available across multiple blockchain networks.
4. Derivative Products: The increased liquidity allows for the creation of derivative products based on RWAs, such as options or futures contracts.

#### Benefits and Use Cases

* Increased Access: Investors can gain exposure to real-world hard commodities that were previously difficult to access or illiquid.
* Fractional Ownership: Large assets can be fractionalized, allowing for smaller investment amounts and increased diversification.
* Efficient Trading: The deep liquidity provided by Lumia Stream enables efficient trading of RWA tokens with minimal slippage.
* New Financial Products: DeFi protocols can create innovative financial products using RWAs as building blocks.
* Regulatory Compliance: Lumia chains approach ensures that RWA tokenization adheres to regulatory requirements, providing confidence to institutional investors and regulatory bodies.

By leveraging the Lumia Stream system, its unique approach to liquidity provision, and its commitment to regulatory compliance through proper licensing, Lumia chain is positioned to become a leading platform for hard commodity tokenization and trading in the DeFi space. This approach not only opens up new investment opportunities but also ensures the legal and regulatory soundness of RWA tokenization.


# Bailee Agreements and Common Law

#### Understanding Bailee Agreements

Bailee Agreements are a crucial legal mechanism that Lumia chain employs to facilitate the tokenization of real-world assets, particularly hard commodities. These agreements are rooted in common law principles and provide a robust legal framework for the custody and management of physical assets in the context of blockchain tokenization.

#### Key Aspects of Bailee Law under Common Law

1. **Definition**: A bailment is a legal relationship where physical possession of personal property is transferred from the owner (bailor) to another party (bailee) for a specific purpose, without transferring ownership.
2. **Duty of Care**: The bailee has a duty to take reasonable care of the bailed property and return it to the bailor when the purpose of the bailment is complete.
3. **Types of Bailments**: Bailments can be for the benefit of the bailor, the bailee, or both parties. In Lumia's case, it's typically for mutual benefit.
4. **Liability**: The bailee is liable for any loss or damage to the property due to their negligence but is not an insurer of the property.
5. **Termination**: The bailment ends when its purpose is fulfilled, or the property is returned to the bailor.

#### How Bailee Agreements Empower Lumia's RWA Tokenization

1. **Legal Custody without Ownership Transfer**: Through Bailee Agreements, Lumia (and its custody partners) can take custody of physical assets (e.g., gold, diamonds) without requiring a transfer of ownership. This allows asset owners to retain their ownership rights while enabling tokenization.
2. **Clear Custody Chain**: Bailee Agreements establish a clear chain of custody, which is crucial for regulatory compliance and auditing purposes. This transparency enhances trust in the tokenization process.
3. **Risk Mitigation**: By clearly defining the responsibilities and liabilities of Lumia as the bailee, these agreements mitigate legal risks associated with asset custody and tokenization.
4. **Flexibility in Asset Management**: Bailee Agreements can be structured to allow Lumia to manage and potentially sub-custody assets, facilitating efficient storage and verification processes.
5. **Legal Recourse**: In the event of disputes, Bailee Agreements provide a clear legal framework for resolution, protecting both asset owners and token holders.
6. **Regulatory Alignment**: The use of Bailee Agreements aligns with existing legal frameworks, making it easier for regulators to understand and approve Lumia's tokenization process.

#### Lumia's Implementation of Bailee Agreements

1. **Customized Agreements**: Lumia develops tailored Bailee Agreements for different types of hard commodities, considering their unique characteristics and storage requirements.
2. **Third-Party Verification**: Lumia incorporates provisions for regular third-party audits and verifications of the bailed assets, ensuring ongoing compliance and transparency.
3. **Smart Contract Integration**: While the Bailee Agreement is a traditional legal document, Lumia integrates key aspects of these agreements into smart contracts, creating a bridge between the legal and blockchain worlds.
4. **Redemption Mechanisms**: The agreements include clear procedures for token holders to redeem their tokens for the underlying physical assets, if desired.
5. **Regulatory Compliance**: Lumia's Bailee Agreements are designed to comply with relevant regulations in key jurisdictions, particularly the UAE and Australia, where Lumia is seeking licensing.

#### Benefits for Lumia and Its Users

1. **Legal Certainty**: Bailee Agreements provide a solid legal foundation for Lumia's RWA tokenization, reducing legal ambiguities and risks.
2. **Enhanced Trust**: The clear legal structure increases trust among asset owners, token holders, and regulators.
3. **Scalability**: With a standardized legal framework, Lumia can more easily scale its RWA tokenization services across different asset types and jurisdictions.
4. **Institutional Appeal**: The use of familiar legal concepts makes Lumia's tokenization process more appealing to institutional investors and traditional finance entities.
5. **Regulatory Navigation**: By leveraging well-established legal principles, Lumia is better positioned to navigate complex regulatory landscapes in different countries.

By leveraging Bailee Agreements and the principles of bailment under common law, Lumia chain creates a robust, legally sound foundation for its RWA tokenization process. This approach not only ensures compliance with existing legal frameworks but also paves the way for the widespread adoption of tokenized real-world assets in the DeFi ecosystem.


# Historical page: the Real World Assets on Lumia page

*Don't delete, this is how a section on the page used to look like. We may need it for later; right now this historical page is hidden and kept to logging and text backup purposes.*\
\
\
Real World Assets (RWAs) represent tangible or intangible assets from the physical world that have been tokenized on the blockchain. Lumia chain focuses on bringing these assets on-chain, creating new opportunities for investment, liquidity, and financial innovation.

Specifically, Lumia chain specializes in tokenizing commodities such as diamonds, aluminium, copper, iron ore, silver, gold, and other precious metals.

### Regulatory Compliance and Bailee Agreements

Lumia Foundation is taking significant steps to ensure regulatory compliance and legal accountability for RWA tokenization:

1. **Acquiring Licenses:** Lumia Foundation is in the process of obtaining necessary licensing from regulatory authorities in the UAE and Australia. These licenses will provide a solid legal framework for RWA tokenization operations.
2. **Leveraging Bailment Agreements:** By utilizing Bailment Agreements, Lumia chain can legally tokenize various commodities. A Bailment Agreement allows possession of a physical asset to remain with a trusted custodian whilst ownership is represented by a token allowing seamless trading of the asset on the Blockchain 24 hours 7 days per week.
3. **Legal Protection:** The licensing and regular audit reports of the commodities and their condition provides strong legal protection for asset owners and token holders, ensuring that the tokenized assets are backed by real, verifiable commodities.

### Tokenization Process on Lumia chain

Lumia chain provides a seamless and legally compliant process for RWA owners to tokenize their assets:

1. Asset owners provide proof of ownership, necessary documentation, and undergo required due diligence.
2. A Bailment Agreement is established between the asset owner and Lumia Foundation.
3. The asset is valued by approved third-party appraisers and tokenized on Lumia chain.
4. Tokens representing the RWA are created and can be fractionalized if desired.
5. These tokens are then made available for trading or used as collateral in DeFi applications.

### Bringing Liquidity to RWAs

One of the key challenges with RWAs in the blockchain space has been providing sufficient liquidity. Lumia chain addresses this challenge through its innovative Lumia Stream system, which bridges centralized exchange (CEX) and decentralized exchange (DEX) liquidity.

#### Lumia Stream: Bridging CEX and DEX Liquidity

Lumia Stream acts as a liquidity aggregator, pulling together liquidity from both centralized and decentralized sources. This creates a deep and diverse liquidity pool that can be accessed by RWA tokens, solving one of the primary obstacles to RWA adoption in DeFi.

#### Liquidity Provisioning for RWAs

1. RWA tokens are integrated into Lumia Pools, which use a constant product formula (e.g., 50% RWA, 50% Stablecoin).
2. Lumia Stream creates liquidity nodes for RWA tokens, allowing for efficient market-making.
3. The DNLP (Delta Neutral Liquidity Provision) Smart Contract locks assets and provides additional liquidity support.
4. Centralized exchanges can provide off-chain hedging opportunities, further enhancing liquidity.

#### Making RWAs DeFi Composable

By bringing significant liquidity to RWA tokens, Lumia chain enables these assets to become fully composable within the DeFi ecosystem:

1. Collateralization: RWA tokens can be used as collateral in lending protocols, allowing users to borrow against their real-world assets.
2. Yield Generation: Liquidity providers can earn yields by contributing RWA tokens to Lumia Pools.
3. Cross-Chain Availability: Through Lumia chains interoperability features, RWA tokens can be made available across multiple blockchain networks.
4. Derivative Products: The increased liquidity allows for the creation of derivative products based on RWAs, such as options or futures contracts.

#### Benefits and Use Cases

* Increased Access: Investors can gain exposure to real-world hard commodities that were previously difficult to access or illiquid.
* Fractional Ownership: Large assets can be fractionalized, allowing for smaller investment amounts and increased diversification.
* Efficient Trading: The deep liquidity provided by Lumia Stream enables efficient trading of RWA tokens with minimal slippage.
* New Financial Products: DeFi protocols can create innovative financial products using RWAs as building blocks.
* Regulatory Compliance: Lumia chains approach ensures that RWA tokenization adheres to regulatory requirements, providing confidence to institutional investors and regulatory bodies.

By leveraging the Lumia Stream system, its unique approach to liquidity provision, and its commitment to regulatory compliance through proper licensing and Bailee Agreements, Lumia chain is positioned to become a leading platform for hard commodity tokenization and trading in the DeFi space. This approach not only opens up new investment opportunities but also ensures the legal and regulatory soundness of RWA tokenization.


# Introduction

To make the most of the information provided in this documentation, it's helpful to have a basic grasp of programming concepts. While we primarily use Solidity and JavaScript throughout the guides, prior experience with these languages is not strictly necessary but can certainly enhance your understanding of the content.

In addition to programming knowledge, familiarity with MetaMask, account and balance management, and interacting with the Ethereum Virtual Machine will prove valuable as you navigate through the material.

To supplement the information in these guides and deepen your comprehension of the subjects and practical code examples, we highly recommend exploring additional resources that focus on Solidity and JavaScript. This will not only reinforce the concepts covered here but also provide a more comprehensive understanding of the topics at hand.

#### Is Blockchain Expertise a Prerequisite?

While having a background in blockchain technology can certainly be advantageous, it is not a strict requirement. The fact that you are here, reading this documentation, demonstrates that you are already on the right path to learning and understanding the concepts presented.

#### Do I Need to be a Programmer to Understand the Introduction?​

The good news is that you don't need any programming skills to comprehend the content. The information provided here serves as a foundation for the more advanced topics that will be covered later in the documentation. Whether you are a seasoned developer or new to the world of programming, this introduction will help you establish a solid understanding of the basics before diving into the more complex aspects of the subject matter.


# Accounts and Wallets

To interact with Lumia chain and deploy SmartContracts you will need MetaMask. Watch this short video to learn how.

{% embed url="<https://www.youtube.com/watch?v=Jp6NHQM-4CQ>" %}


# Setup Metamask with Lumia Chain

Watch video below to setup your MetaMask wallet with custom network such as Lumia chain. Lumia chain network details can be found [here](/build/build-environment/rpc).

{% embed url="<https://www.youtube.com/watch?v=0auF8K5oXCQ>" %}


# Bridge to/ from Lumia L2

We offer two token bridges for convenience:

1. **Native zkEVM Bridge**: This bridge, accessible at [bridge.lumia.org](https://bridge.lumia.org), utilizes zero-knowledge proofs (ZKPs) which ensure high security and privacy. However, please note that this bridge has a longer exit time due to the generation and verification of ZKPs.
2. **Instant Bridge via Hyperlane**: For faster transfers, use the Hyperlane bridge available at [hyper.lumia.org](https://hyper.lumia.org) and [usenexus.org](https://www.usenexus.org). This bridge enables seamless transfers between Ethereum, BNB Chain, and Lumia chain, offering a nearly instantaneous transaction experience.

Note that on HyperLane you will have to pay Interchain Gas Payment (IGP) which is relative cheap to/from BNB Chain but depending on Ethereum congestion can be expensive.

{% hint style="danger" %}
IGP payments are taken from the asset you're sending i.e. if you bridge 10 LUMIA from Lumia chain to Ethereum it will deduct LUMIA as fee which can be in range of $5-15 depending on Ethereum network congestion.
{% endhint %}


# Setup FoxWallet with Lumia Chain

1. Download FoxWallet from the official website: <https://foxwallet.com/&#x20>;

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXd7hBGklbz4KEwmbRL2EpXVJdgoTUemVnCCuJqFoB25HBjWJPMxUC2YWEXgdN0bxKp4rqE3XiUgBvbDybm-FEnDDIORo-PwuKnR52pR3uZqlgkvzTwBx0OLw0zAZO_lUGHWGWiN36jet160U2-TRNzbK2g?key=PLt2B7D-kej3hAiU40_PKA" alt=""><figcaption></figcaption></figure>

2. Launch FoxWallet and follow the prompts to create a wallet account

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdVYNJarrVw8TRbzxhfAhdeTL1UZ2mMReX_e5nmLuH3YJC6lSq7hzfBjEi4VvDzIsgq2TzSBYZcO9nSm72yzxcQXSAOKk1vW6Lu7Yj37LmIHluG8bCsSqd9g-VuWgcMUFJsM_T1l0OLaoiyCkDWkkEzB2A?key=PLt2B7D-kej3hAiU40_PKA" alt=""><figcaption></figcaption></figure>

3. Click the button in the upper left corner to add or switch to Lumia Network

**Add Lumia Network**

**“All”——“Networks”——Search “lumia” in the blank —— Click to choose Lumia Network**

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXds4i-lrl37W2mDXpqhu0MCWQ1ZG__J_sRh7oRJQ1J2g7veL8pUqvxktYlG9M_kWQk2kyr37WJSkSvX0v1srTore2_MdZFaADDF-xzvn2KXodeaa9UpVqR-KyqmGU0wLLzKWrImFB8JuoE9CXBZ23EBlRN_?key=PLt2B7D-kej3hAiU40_PKA" alt=""><figcaption></figcaption></figure>

4. Switch to Lumia Network

**“All”——Search “Lumia” in the blank——Click to switch**


# Explorers

Lumia L2 provides two complementary block explorers that offer different approaches to blockchain data visualization and analysis:

### Blockscout Explorer

**URL**: [explorer.lumia.org](https://explorer.lumia.org) (Testnet: [https://beam-explorer.lumia.org](https://beam-explorer.lumia.org/))

The Lumia L2 explorer, powered by Blockscout, provides comprehensive blockchain data exploration with features specifically optimized for Lumia's zkEVM architecture:

* **Transaction Analysis**: Detailed view of transaction execution, including zkEVM-specific parameters and gas metrics
* **Smart Contract Verification**: Support for contract verification with zkEVM-compatible Solidity versions
* **Token Tracking**: Comprehensive tracking of ERC-20, ERC-721, and ERC-1155 tokens, including RWA tokens
* **Account Management**: Detailed wallet histories and token holdings
* **Advanced Features**:
  * Real-time transaction tracking
  * Source code verification and interaction
  * API access for developers
  * Gas price analytics
  * ERC token indexes


# Build Environment

Set up the Development Environment

While it's not mandatory to have prior knowledge about setting up different environments before you begin, taking the time to explore the upcoming sections can provide valuable insights into the role of each environment and its specific requirements. This understanding can help you navigate the setup process more effectively and make informed decisions along the way.

When you're prepared to take your smart contract live, the information provided in this section will guide you through the process of configuring an RPC endpoint. This crucial step ensures that your smart contract can interact seamlessly with the Ethereum network, enabling you to deploy and execute your code in a production environment.


# RPC

RPC (Remote Procedure Call) nodes serve as essential gateways, enabling decentralized applications and clients to interact seamlessly with a blockchain network. These nodes can be queried to retrieve vital information and are instrumental in initiating transactions, facilitating smooth communication between the application layer and the underlying blockchain.

The primary objective of RPC nodes is to act as intermediaries, listening attentively for incoming requests from decentralized applications. Upon receiving a request, these nodes spring into action, either providing the requested data or executing the specified transaction, ensuring that the application receives the necessary information or confirmation.

RPC nodes find extensive use in various scenarios, such as querying the blockchain for specific information, sending transactions to be recorded on the network, and executing functions defined within smart contracts. This versatility makes them indispensable for a wide range of decentralized applications.

The significance of RPC nodes cannot be overstated, as they form the backbone of decentralized application functionality. By enabling seamless interaction with the blockchain network, RPC nodes pave the way for decentralized exchanges, token transfers, and a myriad of other use cases, ultimately empowering the growth and adoption of decentralized technologies.

### Public Endpoints

{% hint style="info" %}
Info

The endpoints provided for free are intended for end users to engage with dApps or to deploy and interact with smart contracts. However, they have API call rate limits, making them unsuitable for high-demand applications, such as a dApp interface that continuously scrapes blockchain data or an indexing service.

**Lumia Testnet has migrated from Sepolia to Beam. Please use the new endpoints below!** \
For token migration and contract addresses, see the [LUMIA Migration Sepolia-Beam](/lumia/lumia-token/lumia-migration-sepolia-beam).
{% endhint %}

{% tabs %}
{% tab title="Mainnet" %}

|              |                                                                 |
| ------------ | --------------------------------------------------------------- |
| Network      | Lumia Prism (Mainnet)                                           |
| Symbol       | LUMIA                                                           |
| Settlement   | Ethereum L1 - Mainnet                                           |
| Chain ID     | 994873017                                                       |
| RPC HTTPS    | [https://mainnet-rpc.lumia.org](https://mainnet-rpc.lumia.org/) |
| WS           | wss\://mainnet-rpc.lumia.org/ws                                 |
| {% endtab %} |                                                                 |

{% tab title="Testnet" %}

|               |                               |
| ------------- | ----------------------------- |
| Network       | Lumia Beam Testnet            |
| Symbol        | LUMIA                         |
| Settlement    | Ethereum L1 - Beam            |
| Chain ID      | 2030232745                    |
| RPC HTTPS     | <https://beam-rpc.lumia.org/> |
| {% endtab %}  |                               |
| {% endtabs %} |                               |

### Premium Endpoints


# RPC Guide

### Getting Started

#### 1. Project Setup

First, create and initialize your project:

```bash
mkdir lumia-api-quickstart
cd lumia-api-quickstart
npm init --yes
```

#### 2. Install Dependencies

You can use any HTTP client or Web3 library. Here are a few options:

**Using Axios (HTTP Client)**

```bash
npm install axios
```

**Using Web3.js**

```bash
npm install web3
```

**Using Ethers.js**

```bash
npm install ethers
```

#### 3. Making RPC Requests

Here are examples using different libraries:

**Using Axios**

```javascript
const axios = require('axios');

const RPC_URL = 'https://RPC-URL.io';

async function getLatestBlock() {
    const response = await axios.post(RPC_URL, {
        jsonrpc: '2.0',
        id: 1,
        method: 'eth_blockNumber',
        params: []
    });
    
    console.log('Latest Block:', response.data.result);
}

getLatestBlock();
```

**Using Web3.js**

```javascript
const Web3 = require('web3');

const web3 = new Web3('https://RPC-URL.io');

async function getNetworkInfo() {
    const [blockNumber, gasPrice, chainId] = await Promise.all([
        web3.eth.getBlockNumber(),
        web3.eth.getGasPrice(),
        web3.eth.getChainId()
    ]);

    console.log({
        blockNumber,
        gasPrice: web3.utils.fromWei(gasPrice, 'gwei') + ' gwei',
        chainId
    });
}

getNetworkInfo();
```

**Using Ethers.js**

```javascript
const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider('https://RPC-URL.io');

async function getAccountBalance(address) {
    const balance = await provider.getBalance(address);
    
    console.log(
        'Balance:', 
        ethers.formatEther(balance), 
        'LUMIA'
    );
}

getAccountBalance('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
```

### Common RPC Methods

Here are some frequently used RPC methods:

```javascript
// Get latest block number
eth_blockNumber

// Get network version
net_version

// Get gas price
eth_gasPrice

// Get balance
eth_getBalance

// Get transaction count
eth_getTransactionCount

// Send raw transaction
eth_sendRawTransaction

// Get transaction by hash
eth_getTransactionByHash

// Get block by number
eth_getBlockByNumber

// Get logs
eth_getLogs
```

### Example: Complete Transaction Flow

Here's a complete example of sending a transaction using ethers.js:

```javascript
const { ethers } = require('ethers');

async function sendTransaction() {
    // Initialize provider
    const provider = new ethers.JsonRpcProvider('https://RPC-URL.io');
    
    // Create wallet from private key
    const privateKey = 'your-private-key';
    const wallet = new ethers.Wallet(privateKey, provider);
    
    // Transaction parameters
    const tx = {
        to: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        value: ethers.parseEther("0.1")
    };
    
    try {
        // Send transaction
        const transaction = await wallet.sendTransaction(tx);
        console.log('Transaction Hash:', transaction.hash);
        
        // Wait for confirmation
        const receipt = await transaction.wait();
        console.log('Transaction confirmed in block:', receipt.blockNumber);
    } catch (error) {
        console.error('Error:', error);
    }
}
```

### Best Practices

1. **Error Handling**
   * Always implement proper error handling for RPC requests
   * Consider implementing retry logic for failed requests
   * Handle rate limiting appropriately
2. **Performance Optimization**
   * Batch related calls when possible
   * Cache responses when appropriate
   * Use WebSocket connections for real-time updates
3. **Security**
   * Never expose private keys in your code
   * Use environment variables for sensitive data
   * Validate all input parameters


# Add Lumia Network to MetaMask

To add the Lumia Network to your MetaMask wallet, follow these steps:

1. **Open MetaMask Extension**: Ensure you are logged into your MetaMask wallet.
2. **Network Dropdown**:
   * Click on the network dropdown located at the top centre of the MetaMask interface.
3. **Add Network**:
   * Click on "Add Network" at the bottom of the dropdown.
4. **Network Details (Prism - Mainnet)**:
   * Fill in the following details in the provided form:
     * **Network Name**: `Lumia Prism`
     * **New RPC URL**: [`https://mainnet-rpc.lumia.org/`](https://mainnet-rpc.lumia.org/)
     * **Chain ID**: `994873017`&#x20;
     * **Currency Symbol**: `LUMIA`
     * **Block Explorer URL**: [`https://explorer.lumia.org/`](https://testnet-explorer.lumia.org/)
5. **Network Details (Testnet)**:
   * Fill in the following details in the provided form:
     * **Network Name**: `Lumia Beam Testnet`
     * **New RPC URL**: [`https://beam-rpc.lumia.org/`](https://beam-rpc.lumia.org/)
     * **Chain ID**: `2030232745`&#x20;
     * **Currency Symbol**: `LUMIA`
     * **Block Explorer URL**: [`https://beam-explorer.lumia.org/`](https://beam-explorer.lumia.org/)
6. **Save**: Click on the "Save" button to add the Lumia Network to your MetaMask wallet.

The **Lumia (Prism or Testnet)**  should now be available in your MetaMask network options!


# Testnet Tokens

A faucet is a resource where you can obtain test tokens. Faucets are accessible to all wallets such as MetaMask. Utilize these faucets to ensure your wallet has sufficient assets to cover deployment costs and transaction gas fees.

### Lumia Faucet Portal

Navigate to the Lumia Faucet Portal by visiting <https://beam-faucet.lumia.org/>. Follow these steps to connect your MetaMask wallet and claim Testnet tokens:

#### Step 1: Open MetaMask

Ensure that your MetaMask extension is installed in your web browser and that your wallet is open. If you do not have MetaMask installed, you can download it from the official [MetaMask website](https://metamask.io/).

#### Step 2: Switch to Testnet

Before connecting to the Lumia Faucet Portal, make sure MetaMask is set to the [Lumia Testnet](/build/build-environment/add-lumia-network-to-metamask) network. RPC details for Lumia Testnet can be found [here](/build/build-environment/rpc).&#x20;

#### Step 3: Connect Wallet

Visit the Lumia Faucet Portal at <https://beam-faucet.lumia.org/>.

On the homepage simply paste your wallet address and click "Request". You should receive 1 LUMIA Testnet token into the wallet address you provided.

{% hint style="info" %}
Currently limited to feeding 1 LUMIA token per 3 hours.
{% endhint %}

#### Step 4: Verify Tokens

After the transaction is successful, you can verify the receipt of testnet tokens by checking your MetaMask wallet balance. LUMIA token is the native gas token for Lumia thus balance should auto-appear.

By following these steps, you can easily connect your MetaMask wallet to the Lumia Faucet Portal and claim testnet tokens to use for deployment costs and transaction gas fees.


# SmartContracts

This chapter will guide you through deployment of your first Solidity based SmartContract on Lumia Chain (zkEVM). Feel free to skip to relevant parts based on your experience and comfort level.

In this tutorial, you'll learn to develop and deploy a smart contract on Lumia Chain zkEVM, tailored for those new to EVM and seeking a basic yet thorough understanding of the process. Expected to take about 30 minutes, completing this tutorial will mark your entry into dApp development!&#x20;

Requirements include:

* Basic knowledge of Solidity
* Familiarity with software development tools and CLIs
* Basic understanding of MetaMask
* Access to an IDE like; VSCode or Remix

**What you will accomplish in this tutorial:**

* Learn about Lumia Chain
* Configure MetaMask
* Deploy a smart contract onto Testnet
* Obtain some test tokens from the faucet
* Deploy a smart contract on Lumia Testnet


# Deployment

### Obtain LUMIA token from the Faucet[​](https://docs.astar.network/docs/build/EVM/first-contract/deploy-shibuya#obtain-sby-token-from-the-faucet) <a href="#obtain-sby-token-from-the-faucet" id="obtain-sby-token-from-the-faucet"></a>

To deploy a contract on Lumia chain, you will need to obtain some LUMIA tokens from the Faucet, which is explained [on the faucet page.](/build/build-environment/testnet-tokens)

Once successful, you will see some LUMIA tokens available within MetaMask, if not, double-check to ensure Lumia Testnet is selected as your current network.

### Deploy Contract on Lumia TestnNet <a href="#deploy-contract-on-shiden" id="deploy-contract-on-shiden"></a>

The last step will be to deploy a smart contract on Lumia TestNet.

### Token Contract

```solidity
// SPDX-License-Identifier: MIT
// Compatible with OpenZeppelin Contracts ^5.0.0
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";

contract Sportimex is ERC20, ERC20Permit {
    constructor() ERC20("Hello Lumia", "HelloLumia") ERC20Permit("HelloLumia") {
        _mint(msg.sender, 100000000 * 10 ** decimals());
    }
}

```

This contract will issue an `ERC20` token called `'Hello Lumia'`, with ticker `HelloLumia`, and a total supply of 100m using 18 decimals of precision with `ERC20Permits` implemented. You will be able to compile this contract using one of the deployment methods described in later sections.


# Hardhat

### Initialize Your Project

If you're starting your Hardhat project from scratch, we recommend you read the Hardhat Quick Start page.

### Setting up Your Account​

The quickest way to get Hardhat to deploy contracts to a non-local TestNet, is to export and use an existing MetaMask account.

To get an account's private key from MetaMask:

1. Open MetaMask.
2. Select the account you want to export.
3. Click the three dots on the right side.
4. Select "Account Details".
5. Select "Export Private Key".
6. Enter your password and select "Confirm".

You should see a 64-character hex string similar to the following:

`60ed0dd24087f00faea4e2b556c74ebfa2f0e705f8169733b01530ce4c619883`

Create a new file in your root folder called `private.json` with your private key in it:

```json
{
  "privateKey": "60ed0dd24087f00faea4e2b556c74ebfa2f0e705f8169733b01530ce4c619883"
}
```

Modify your `hardhat.config.js` file to include:

```javascript
// hardhat.config.js

// ...

const { privateKey } = require("./private.json");

// ...

module.exports = {
  // ...

  networks: {
    // Lumia faucet: https://testnet-faucet.lumia.org
    lumia-testnet: {
      url: "https://beam-rpc.lumia.org",
      chainId: 2030232745,
      accounts: [privateKey],
    },

    // ...
  },
};
```

Once your accounts are funded, you can deploy the sample contract to Lumia Testnet with `npx hardhat run --network lumia-testnet scripts/deploy.js`.


# Truffle

### Create an Ethereum Account​

We recommend using the `@truffle/hdwallet-provider` package for key management. Instructions can be found here.

### Add Networks to `truffle-config.js`

To deploy and interact with Astar, modify `networks` in `truffle-config.js` to include Astar's networks:​

```javascript
// truffle-config.js
module.exports = {
  networks: {
    // ... any existing networks (development, test, etc.)

    // Lumia faucet: https://testnet-faucet.lumia.org
    lumia-testnet: {
      url: "https://beam-rpc.lumia.org/",
      network_id: 2030232745,
    },
    // ...
  },

  // ...
};
```

Deploy/Migrate by running `truffle migrate --network lumia-testnet`, replacing `lumia` with your chosen network. If `--network` is not specified, the network values under`development` will be used.


# Verify

Once your SmartContract is deployed it is reccommended to verify your source code for full transparency. This next section will provide guide on verifying your SmartContract using two different tools.


# Hardhat

Verify your SmartContract using Hardhat

### Verifying Your Contracts on Lumia L2

After you've deployed your contract to the Lumia L2 network, the next crucial step is to verify its source code. Verifying a contract involves making its source code publicly available, along with the compiler settings used, allowing anyone to compile it and compare the generated bytecode with the deployed version on the blockchain. This transparency is essential in an open platform like Lumia L2.

In this guide, we'll walk you through the process of verifying your contract using the Lumia L2 Explorer.

### Installation

1. If starting from scratch, create a new npm project in an empty folder using `npm init` (npm 7 or higher recommended).
2. Install Hardhat by running `npm install --save-dev hardhat` or `yarn add --dev hardhat`.
3. Create a Hardhat project by running `npx hardhat` and following the prompts.
4. Install the hardhat-verify plugin (v3.0.0+) using `npm install --save-dev @nomicfoundation/hardhat-verify` or `yarn add --dev @nomicfoundation/hardhat-verify`.
5. Add the plugin reference to your `hardhat.config.js` or `hardhat.config.ts` file.

### Configuration

1. Set up your Hardhat config file to support the network you're working on (e.g., Lumia Testnet).
2. Add an RPC URL with an arbitrary string as the API key.
3. To use BlockScout for verification, specify the explorer details under a `customChains` object, including the `chainID`, `apiURL`, and `browserURL`.

### Deployment and Verification

1. Use Hardhat Ignition for deployment.
2. Deploy your contract.
3. Verify the deployed contract using:

`npx hardhat verify --network lumia-testnet DEPLOYED_CONTRACT_ADDRESS "Constructor argument 1"`.

{% hint style="info" %}
If the contract is automatically verified via the Ethereum Bytecode Database service, you may need to use the `--force` flag to enforce verification.
{% endhint %}

### Confirming Verification on BlockScout

1. Go to your Lumia Testnet URL and search for the contract address.
2. Check for a green checkmark ✅ indicating the contract is verified.
3. Scroll down to view and interact with the contract code.

<figure><img src="/files/S2uUBwwQCbA6LtnkCwgi" alt=""><figcaption><p>Sample verified contract view</p></figcaption></figure>


# Truffle

Verify your SmartContract using Truffle

### Verifying Contracts on Lumia Chain with Truffle

&#x20;Truffle is a popular development framework for Ethereum and compatible networks like Lumia chain. It provides a convenient way to verify contracts directly from the command line interface (CLI) using the `truffle-plugin-verify` plugin.

In this tutorial, we'll guide you through the process of verifying your contracts on the Lumia chain network using Truffle.

### Prerequisites&#x20;

Before getting started, ensure that you have the following:

* Truffle installed globally: `npm install -g truffle`
* `truffle-plugin-verify` plugin installed: `npm install -g truffle-plugin-verify`
* A Lumia L2 Explorer API key

### Lumia Chain Testnet

Let's start by verifying a contract on the Lumia chain Testnet. You can explore the Lumia chain Testnet Explorer to view verified contracts and transactions.

1. Open your Truffle configuration file (`truffle-config.js`) and add the following configuration:

```javascript
module.exports = {
  // ...
  plugins: ['truffle-plugin-verify'],
  api_keys: {
    lumia_l2_explorer: 'YOUR_LUMIA_L2_EXPLORER_API_KEY',
  },
  networks: {
    lumia_testnet: {
      provider: () => new HDWalletProvider(mnemonic, 'https://beam-rpc.lumia.org/'),
      network_id: 1001,
      timeoutBlocks: 200,
      confirmations: 5,
    },
  },
  // ...
};
```

{% hint style="danger" %}
Make sure&#x20;
{% endhint %}

{% hint style="info" %}
`YOUR_LUMIA_L2_EXPLORER_API_KEY -` this is just an arbtrary key as Blockscout does not need an API key for verification
{% endhint %}

2. Deploy your contracts to the Lumia L2 Testnet:

```bash
truffle migrate --network lumia_testnet
```

3. Verify your contracts using the `truffle run verify` command:

```bash
truffle run verify ConvertLib MetaCoin --network lumia_testnet
```

{% hint style="info" %}
Replace `ConvertLib` and `MetaCoin` with the names of your contract.
{% endhint %}

4. Wait for the verification process to complete. Truffle will display a success message once the contracts are verified.
5. View your verified contracts on the Lumia chain Testnet Explorer.

### Lumia Chain Mainnet&#x20;

To verify your contracts on the Lumia chain Mainnet, follow these steps:

1. Update your Truffle configuration file (`truffle-config.js`) with the Lumia chain Mainnet settings:

```javascript
module.exports = {
  // ...
  plugins: ['truffle-plugin-verify'],
  api_keys: {
    lumia_l2_explorer: 'YOUR_LUMIA_L2_EXPLORER_API_KEY',
  },
  networks: {
    lumia_mainnet: {
      provider: () => new HDWalletProvider(mnemonic, 'https://mainnet-rpc.lumia.org'),
      network_id: 8888,
      timeoutBlocks: 200,
      confirmations: 5,
    },
  },
  // ...
};
```

Replace `'YOUR_LUMIA_L2_EXPLORER_API_KEY'` with your actual Lumia chain Explorer API key.

2. Deploy your contracts to the Lumia chain Mainnet:

```bash
truffle migrate --network lumia_mainnet
```

3. Verify your contracts using the `truffle run verify` command:

```bash
truffle run verify ConvertLib MetaCoin --network lumia_mainnet
```

4. Wait for the verification process to complete. Truffle will display a success message once the contracts are verified.
5. View your verified contracts on the Lumia chain Mainnet Explorer.

If you encounter any issues during the verification process, feel free to reach out to the Lumia chain community on Discord for assistance.

By following this tutorial, you can easily verify your contracts on the Lumia chain network using Truffle, enhancing the transparency and trust in your decentralized applications.


# Interact

Connecting to Lumia chain with Web3 EVM Wallet Library

### Connecting to Lumia chain with Web3-Onboard

Web3-Onboard is a powerful library that simplifies the process of adding multi-wallet and multi-chain support to your project. With just a few lines of code, you can seamlessly integrate your app into the web3 world and connect to the Lumia chain network. Let's walk through the steps to get started.

### Installation

First, install the necessary dependencies using your preferred package manager:

```bash
yarn add @web3-onboard/core @web3-onboard/injected-wallets @web3-onboard/react ethers
```

### Configuration

Next, configure Web3-Onboard by defining the supported wallets and chains. Here's an example configuration file tailored for the Lumia chain network:

```javascript
import React from "react";
import { init, useConnectWallet } from "@web3-onboard/react";
import injectedModule from "@web3-onboard/injected-wallets";
import { ethers } from "ethers";

const wallets = [injectedModule()];

const chains = [
  {
    id: "0x51",
    token: "LOC",
    label: "Lumia Testnet",
    icon: '<svg>...</svg>',
    color: "#2c3335",
    rpcUrl: "https://beam-rpc.lumia.org",
    publicRpcUrl: "https://beam-rpc.lumia.org",
    blockExplorerUrl: "https://beam-explorer.lumia.org/",
  },
];

const appMetadata = {
  name: "My Lumia L2 App",
  icon: '<svg>...</svg>',
  logo: '<svg>...</svg>',
  description: "My app using Onboard on Lumia L2 Network",
  recommendedInjectedWallets: [
    { name: "MetaMask", url: "https://metamask.io" },
  ],
};

init({
  wallets,
  chains,
  appMetadata,
});

const [{ wallet, connecting }, connect, disconnect] = useConnectWallet();

let ethersProvider;

if (wallet) {
  ethersProvider = new ethers.providers.Web3Provider(wallet.provider, "any");
}
```

{% hint style="info" %}
Make sure to replace the SVG icons and URLs with the appropriate values for your app and the Lumia L2 network.
{% endhint %}

### Usage

With the configuration in place, you can now add a button to connect and activate the wallet:

```jsx
<button
  disabled={connecting}
  onClick={() => (wallet ? disconnect(wallet) : connect())}
>
  {connecting ? "Connecting" : wallet ? "Disconnect" : "Connect"}
</button>
```

That's it!&#x20;

Your app is now ready to connect to the Lumia chain network using Web3-Onboard. Users can easily connect their wallets and interact with your dApp seamlessly. For more advanced customization and features, refer to the [Web3-Onboard documentation](https://onboard.blocknative.com/docs/overview/introduction).&#x20;

By leveraging Web3-Onboard, you can provide a user-friendly and inclusive wallet connection experience, making your dApp accessible to a wide range of users on the Lumia chain network.


# Relay

### Meta Transactions

Meta transactions are a type of transaction that allows users to interact with the Flow Network without having to pay for gas fees. Instead, a third party, known as a relayer, pays the gas fees on behalf of the user. This enables users to interact with the network without having to hold FLOW tokens or manage their own wallets.

#### [Gelato](https://gelato.network/)

Relay services, like Gelato Relay, act as intermediaries that handle the submission of meta-transactions to the blockchain. By integrating relay contracts (such as GelatoRelayContext or ERC2771Context) into a smart contract, developers can enable gasless transactions. This allows users to interact with decentralized applications without holding native tokens, while maintaining security through features like EIP-712 signature validation.

The relayer ensures the transaction is executed securely and promptly, handling the gas fee payment either off-chain (via a sponsor) or on-chain (with the user’s funds). This system simplifies blockchain interactions, broadening accessibility and reducing friction for dapp users.

#### Use cases

* Highlight.xyz: Allows users to mint NFTs without incurring gas fees.
* ZED RUN: Automates breeding processes for digital racehorses.
* Reya: Enable gasless trading on the platform

**Off-chain and on-chain payments**

Transactions can be paid for in two primary ways: off-chain payments and on-chain payments. Each method offers flexibility depending on how developers wish to handle transaction fees for their users.

**Off-chain payments**

* **SponsoredCallERC2771**: In this method, Gelato uses the ERC-2771 meta-transaction standard to allow gasless transactions. The user signs a message, and the relay service covers the gas fees. ERC-2771Context ensures that the user’s identity is verified off-chain, by encoding the user’s address in the last 20 bytes of the transaction. This provides a secure, gasless experience where Gelato, using its 1Balance, sponsors the transaction fee.
* **SponsoredCall**: When there is no need for ERC-2771's off-chain signature verification, this more flexible method can be used. The transaction fees are still covered by the sponsor using 1balance, but the responsibility for managing security measures such as signature validation and replay protection lies with the project. This option is ideal for use cases that already have built-in security mechanisms.

**On-chain payments**

* **callWithSyncFeeERC2771**: This method combines ERC-2771 meta-transaction functionality with Gelato’s SyncFee model. The user’s gas fee is calculated and paid directly from the smart contract during the transaction execution. Gelato’s Fee Oracle estimates the fee in real-time, and the GelatoRelayContext contract automatically handles the fee transfer. This is ideal for developers who want to maintain user signature verification while ensuring users cover their transaction costs.
* **callWithSyncFee**: This method is similar to callWithSyncFeeERC2771 but without the need for ERC-2771’s off-chain signature verification. The user’s gas fee is calculated and paid directly from the target smart contract during the transaction execution. This approach is useful for applications where users are expected to pay for their own gas without requiring meta-transaction features.

#### Implementation

We will require three simple steps to implement Gelato Relay. Here, we are going to showcase the three steps required to implement the method `sponsoredCallERC2771`, which is the most used one.

**Step 1: Inherit Context Contract**

Depending on the method, you must inherit different contracts as they will provide other methods. In this case, we will have to inherit the `ERC2771Context`. The `ERC2771Context` provide us with the methods `_msgSender()` and `_msgData()` that will allow us to recover the original user sending the transaction.

```solidity
import {
    ERC2771Context
} from "@gelatonetwork/relay-context/contracts/vendor/ERC2771Context.sol";

contract CounterERC2771 is ERC2771Context {

    // ERC2771Context: setting the immutable trustedForwarder variable
    constructor(address trustedForwarder) ERC2771Context(trustedForwarder) {}

    function incrementContext() external {

        // Incrementing the counter mapped to the _msgSender!
        contextCounter[_msgSender()]++;

        // Emitting an event for testing purposes
        emit IncrementContextCounter(_msgSender());
    }
}
```

**Step 2: Import the relay SDK**

In your frontend/backend, you would need to import and instantiate the relay class.

```
import { GelatoRelay, SponsoredCallERC2771Request } from "@gelatonetwork/relay-sdk";
const relay = new GelatoRelay(API_KEY);
```

**Step 3: Send the payload to Gelato**

This is an example using Gelato's CounterERC2771.sol, which is deployed on these networks.

```
// Set up on-chain variables, such as target address
const counter = "0x00172f67db60E5fA346e599cdE675f0ca213b47b";
const abi = ["function incrementContext()"];
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = provider.getSigner();
const user = signer.getAddress();

// Generate the target payload
const contract = new ethers.Contract(counter, abi, signer);
const { data } = await contract.incrementContext.populateTransaction();

// Populate a relay request
const request: CallWithERC2771Request = {
  chainId: (await provider.getNetwork()).chainId,
  target: counter;
  data: data;
  user: user;
};

// Without a specific API key, the relay request will fail!
// Go to https://relay.gelato.network to get a testnet API key with 1Balance.
// Send a relay request using Gelato Relay!
const relayResponse = await relay.sponsoredCallERC2771(request, provider, apiKey);
```

**Further Gelato resources**

* [Gelato Relay Docs](https://docs.gelato.network/web3-services/relay)
* [What is 1Balance?](https://docs.gelato.network/web3-services/1balance)
* [YouTube - ERC2771](https://www.youtube.com/watch?v=P6LlzSzta1Q)
* [YouTube - non-ERC2771](https://youtu.be/shqLPDerunY)
* [GitHub Repository](https://github.com/gelatodigital/how-tos-5-6-7-8-relay-intro-methods)


# Web3 Functions

## Contract Automation

In the Filecoin network, smart contracts benefit from a secure, deterministic environment. While this ensures reliability, it also limits direct access to external data sources. However, developers can leverage automation services to seamlessly connect off-chain data with on-chain smart contracts. This unlocks advanced capabilities such as price feeds, data verification, and much more, empowering Filecoin dapps with dynamic, real-world functionality by integrating external data into on-chain logic.

#### [Gelato](https://gelato.network/)

Gelato's Web3 Functions is a powerful automation system designed to streamline and enhance Web3 operations. Web3 Functions serve as a comprehensive tool, enabling developers to effortlessly set up, manage, and automate their smart contract tasks.

**How Gelato Web3 functions work?**

Web3 Functions can be triggered by various events and allow developers to write both off-chain logic (TypeScript) and on-chain logic (Solidity). Once deployed, they handle automated smart contract interactions, providing real-time monitoring and flexibility.

**Off-chain Data or Computation?** Sometimes, automation tasks require data that isn't readily available on the blockchain, or they might need computations that are better performed off-chain. In such cases, Typescript Functions should be the choice.

**All Checks On-chain?** If all the conditions necessary for your automation task can be directly verified on the blockchain, you have the option to select between Typescript Functions, Solidity Functions & Automated Transactions

### Triggers

1. Time Interval Use this trigger to execute tasks at regular intervals, e.g., every 10 minutes or once every 24 hours. It's like setting a straightforward, recurring alarm.
2. Cron Expressions This offers a more refined control compared to the Time Interval. With cron expressions, you can set tasks to run at specific moments, such as "every Tuesday at 3 PM" or "on the 1st of every month". It gives you precision in task scheduling.
3. On-Chain Event Ideal for those wanting their tasks to respond dynamically to blockchain activities. Whenever a specified event occurs on the blockchain, this trigger springs your task into action. It's like a vigilant watcher, always ready to act.
4. Every Block This function operates with the rhythm of the blockchain itself, executing your chosen function each time a new block is created.

### What to Execute?

#### Typescript Functions

Typescript Functions are decentralized cloud functions that work similarly to AWS Lambda or Google Cloud, just for web3. They enable developers to execute on-chain transactions based on arbitrary off-chain data (APIs / subgraphs, etc) & computation. These functions are written in Typescript, stored on IPFS and run by Gelato.

#### Solidity Functions

Solidity Functions are crucial for making on-chain tasks automatic and more efficient. They connect set conditions with specific actions in a smart contract, providing a straightforward method to turn user needs into automated processes. Consider them as a set of "if-then" rules: If certain conditions are met on the blockchain, then a specific function gets executed. This level of automation ensures that the decentralized application can operate with minimal manual intervention, providing a seamless user experience.

#### Automated Transaction

Automated Transaction ensures that a specific function on the target smart contract gets reliably triggered. When you pre-define the inputs, it means that every time Gelato initiates the function call, it uses consistent, predetermined arguments.

**What is dedicatedMsgSender?**

For security reasons, during task creation, you will see an address that acts as the msg.sender for your task executions. This address is a proxy contract deployed by Gelato. It ensures that every task execution on behalf of your contract uses this dedicated msg.sender address, which is essential for validating the origin of the task.

### Quick Start

#### Writing & Deploying Typescript Functions

1. Clone the hardhat-template repo

```shell
git clone web3-functions-hardhat-template
```

2. CD into the folder and install

```shell
cd web3-functions-hardhat-template && yarn install
```

3. Update the `index.ts` in one of the examples

```typescript
Web3Function.onRun(async (context: Web3FunctionContext) => {
  const { userArgs, multiChainProvider } = context;

  const provider = multiChainProvider.default();
  // Retrieve Last oracle update time
  const oracleAddress =
    (userArgs.oracle as string) ?? "0x71B9B0F6C999CBbB0FeF9c92B80D54e4973214da";

  // YOUR CUSTOM LOGIC
  .....

  // Return if nothing has to be pushed on-chain
    return { canExec: false, message: `Coingecko call failed` };

  // Return if tx has to be pushed on-chain
  return {
    canExec: true,
    callData: [
      {
        to: oracleAddress,
        data: oracle.interface.encodeFunctionData("updatePrice", [price]),
      },
    ],
  };
});
```

4. Deploy the Web3 Function to IPFS and create the Task

```shell
npx w3f deploy web3-functions/YOUR-FUNCTION/index.ts
```

Result:

```shell
$ npx w3f deploy web3-functions/YOUR-FUNCTION/index.ts
 ✓ Web3Function deployed to ipfs.
 ✓ CID: QmYMysfAhYYYrdhVytSTiE9phuoT49kMByktXSbVp1aRPx

To create a task that runs your Web3 Function every minute, visit:
> https://beta.app.gelato.network/new-task?cid=QmYMysfAhYYYrdhVytSTiE9phuoT49kMByktXSbVp1aRPx
✨  Done in 3.56s.
```

Finally, go to the [Gelato App](https://app.gelato.network), create a new task, decide on the trigger, and input the CID.

For a detailed guide on creating and deploying Web3 Functions, including setting up your development environment, triggers, and security configurations, refer to the full developer guide [here](https://docs.gelato.network/web3-services/web3-functions/quick-start/writing-typescript-functions).

**Further Resources**

* [Gelato Web3 Functions Docs](https://docs.gelato.network/web3-services/web3-functions)
* [What is 1Balance?](https://docs.gelato.network/web3-services/1balance)
* [Github Repository](https://github.com/gelatodigital/how-tos-3-w3f-triggers)
* [YouTube - How to write Event driven Web3 Functions](https://www.youtube.com/watch?v=7UpqGsANsBQ\&ab_channel=JavierDonoso)


# On-Chain KYC

This guide provides the steps and instructions for integrating Privado ID-based KYC verification directly in your frontend application, utilizing the **Privado ID verifier API** at `https://verifier-backend.privado.id`.

***

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you begin integrating Privado ID verification, ensure you have the following:

* A **React-based frontend**.
* **Frontend access** to `https://verifier-backend.privado.id` for generating QR codes and checking the verification status.
* The `qrcode.react` npm package for rendering QR codes.

***

#### Integration Steps <a href="#integration-steps" id="integration-steps"></a>

**Step 1: Set up Frontend Components**

The frontend will be responsible for interacting with users, displaying the QR code, and updating the verification status.

**1.1 React Components**

* **StatusCard**: A component that shows the current KYC status (e.g., "Pending", "Verifying", "Approved", or "Failed").
* **QRCodeSection**: Displays the QR code generated for the user to scan with their Privado ID wallet.
* **ActionButtons**: Provides buttons like "Start KYC" and "Retry" to allow users to interact with the verification process.

```javascript
// Example for displaying QR code and status
import React, { useState } from 'react';
import { handlePolygonVerification, pollVerificationStatus } from './api'; // Functions to initiate verification and poll status

const KYCPage = () => {
  const [status, setStatus] = useState('pending');
  const [qrCode, setQrCode] = useState(null);
  const [sessionID, setSessionID] = useState(null);

  const startVerification = async () => {
    const result = await handlePolygonVerification();
    setQrCode(result.qrCode);
    setSessionID(result.sessionID);
    setStatus('verifying');
    pollVerificationStatus(result.sessionID, setStatus); // Poll verification status
  };

  return (
    <div>
      <h1>Privado ID KYC Verification</h1>
      <LhStatusCard status={status} />
      {status === 'verifying' && <LhQRCodeSection qrCode={qrCode} />}
      <LhActionButtons onClick={startVerification} />
    </div>
  );
};
```

**1.2 Handle Verification Requests**

Use a function to send a **POST** request to the Privado ID API to generate the QR code.

```javascript
// Function to handle verification request
export const handlePolygonVerification = async () => {
  const response = await fetch('https://verifier-backend.privado.id/sign-in', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      chainID: "1952959480", - Lumia Testnet
      scope: [
        {
          circuitId: "credentialAtomicQueryMTPV2",
          id: 1734435086,
          query: {
            allowedIssuers: ["*"],
            context: "https://raw.githubusercontent.com/shiva-decrypt/lumai-json/main/lumiav2.jsonld",
            type: "KYC",
            credentialSubject: {
              Kyc_Approved: { "$eq": true }
            }
          }
        }
      ],
      skipClaimRevocationCheck: false
    })
  });

  const data = await response.json();
  return {
    qrCode: data.qrCode,
    sessionID: data.sessionID,
  };
};
```

**Explanation of the `body` Section in the Request**

The `body` of the request is a JSON object sent to the Privado ID verifier backend. Here's a breakdown of its components:

***

**1. `chainID: "XXXXXXX"`**

* Specifies the blockchain network used.
* `1952959480` corresponds to the Lumia Testnet.
* `994873017` corresponds to the Lumia Mainnet (Prism)

***

**2. `scope`**

* **Purpose**: Defines the query parameters and the type of credential to verify.
* Contains an array of query objects. Each query object includes:
  * `circuitId`: `"credentialAtomicQueryMTPV2"`
    * Specifies the type of cryptographic circuit used for verification.
    * In this case, it's `credentialAtomicQueryMTPV2`, which supports secure and private verification of claims.
  * `id`: `1734435086`
    * A unique identifier for the query.
  * `query`: Describes the claim or condition to be checked.
    * **`allowedIssuers`: `["*"]`**
      * Allows credentials from any issuer (`*`).
    * **`context`**:
      * A URL pointing to the JSON-LD schema defining the structure of the credential.
      * In this case, it links to a schema stored in a GitHub repository.
    * **`type`: `"KYC"`**
      * Specifies the type of credential being validated.
    * **`credentialSubject`**:
      * Defines the specific conditions the credential must meet.
      * In this example, `Kyc_Approved: { "$eq": true }` requires that the `Kyc_Approved` field in the credential is `true`.

***

**3. `skipClaimRevocationCheck: false`**

* Ensures that the claim revocation status is verified.
* If set to `true`, the verification would skip checking if the claim has been revoked, which might reduce security.

***

**Possible Modifications**

**1. Customizing Allowed Issuers**

* Instead of allowing any issuer (`allowedIssuers: ["*"]`), you can specify trusted issuers. **Example**:

  Copy

  ```
  "allowedIssuers": ["did:polygon:abc123", "did:polygon:def456"]
  ```

**2. Using a Custom Credential Type**

* Change the `type` from `"KYC"` to other credential types if needed. Ensure the schema in the `context` URL matches the new type.

**3. Dynamic `chainID` Selection**

* If your application supports multiple networks, the `chainID` can be dynamically passed based on the selected environment (e.g., mainnet or testnet).

**4. Revocation Check Skipping**

* For faster verification in non-critical use cases, set `skipClaimRevocationCheck` to `true`. However, this is not recommended for sensitive processes.

**5. Adding Additional Query Conditions**

* You can validate more fields by adding them to the `credentialSubject`. **Example**:

  Copy

  ```
  "credentialSubject": {
    "Kyc_Approved": { "$eq": true },
    "Age": { "$gte": 18 }
  }
  ```

  This ensures the user is at least 18 years old and has passed KYC.

**Step 2: Poll Verification Status**

After the QR code is generated, you need to periodically check the status of the verification to keep the user updated.

```javascript
// Function to poll verification status
export const pollVerificationStatus = async (sessionID, setStatus) => {
  const response = await fetch(`https://verifier-backend.privado.id/status?sessionID=${sessionID}`);
  const data = await response.json();

  if (data.status === 'success') {
    setStatus('approved');
  } 

  // Poll every 5 seconds until verification is completed
  if (data.status !== 'approved' && data.status !== 'failed') {
    setTimeout(() => pollVerificationStatus(sessionID, setStatus), 5000);
  }
};
```

**Step 3: Handle User Interaction**

Users can interact with the system by clicking the "Start KYC" button to initiate the verification process and retry if needed.

**Example UI Components**

```javascript
import { QRCodeSVG } from 'qrcode.react';

export const LhStatusCard = ({ status }) => {
  return (
    <div>
      <h2>Status: {status}</h2>
    </div>
  );
};

export const LhQRCodeSection = ({ qrCode }) => {
  return (
    <div>
    <QRCodeSVG
              value={qrCode}
              size={400}
              level="H"
              className="h-full w-full"
              includeMargin
              bgColor="#f3f4f6"
              fgColor="#4f46e5"
            />
    </div>
  );
};

export const LhActionButtons = ({ onClick }) => {
  return (
    <div>
      <button onClick={onClick}>Start KYC</button>
    </div>
  );
};
```

***

#### Final Steps <a href="#final-steps" id="final-steps"></a>

1. **Start the KYC Process**:
   * The user clicks the “Start KYC” button, triggering the `startVerification` function.
   * A **QR code** will be displayed for the user to scan with their Polygon ID wallet.
2. **Track the Verification Status**:
   * Once the user scans the QR code, the status will update to "Verifying."
   * The frontend will automatically poll the status every 5 seconds until the status is either "Approved" or "Failed."
3. **Handle Status Changes**:
   * Upon successful verification, the status will update to "Approved".
   * If verification fails, the user can click “Retry” to attempt the process again.

***

#### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* **Issue**: QR code is not displayed.
  * **Solution**: Ensure that the API is returning a valid `qrCode` URL. Verify that your frontend is correctly displaying the image.
* **Issue**: Verification fails.
  * **Solution**: Confirm that the user's Privado ID wallet app is properly configured and connected to the internet.
* **Issue**: Status remains "Pending" for too long.
  * **Solution**: Ensure the sessionID is valid and being correctly used to check the verification status. You may also want to check for any issues with the Privado ID service.

***

#### Conclusion <a href="#conclusion" id="conclusion"></a>

By following this guide, you can integrate Privado ID verification directly into your frontend application, allowing users to verify their KYC status with ease. The process involves generating a QR code, tracking the status, and providing feedback to the user throughout the verification process.


# Oracles

In the expansive realm of blockchain technology, oracles serve as crucial intermediaries that bridge the gap between decentralized digital ecosystems and the tangible world. These pivotal components empower smart contracts, enabling them to interact fluidly with external data, systems, and events, which were previously inaccessible to traditional blockchain networks. By furnishing blockchains with real-world inputs, oracles facilitate a vast array of applications, thus unlocking the full potential of decentralized technologies.

### What are Oracles?

Oracles are specialized systems or services that function as external data aggregators for blockchains. They operate as trusted sources that feed real-world information to smart contracts. Smart contracts, which are essentially autonomous, self-executing agreements encoded on the blockchain, rely on oracles to obtain the data necessary to perform a wide array of functions. This data can include various metrics such as financial market prices, climatic conditions, sports scores, or even data from Internet of Things (IoT) devices. By providing these inputs, oracles transform smart contracts from static lines of code into dynamic instruments capable of executing real-world business logic.

### Why are Oracles Needed?

Blockchain networks, while secure and decentralized, are inherently siloed environments. Their isolation is intentional—designed to maintain integrity, security, and consensus within the network. However, this same isolation prevents blockchains from accessing external information directly. Without the inclusion of oracles, smart contracts would be limited to executing deterministic logic based purely on pre-existing on-chain data, rendering them incapable of responding to real-world dynamics. Oracles solve this limitation by serving as the conduit through which blockchains can access and interact with external data sources, thus enabling decentralized applications to make data-driven decisions and respond to real-time changes occurring in the world.

### How Do Oracles Work?

Oracles function by providing off-chain data to on-chain applications in a secure and reliable manner. They do so through various methodologies:

* **Inbound Oracles**: These oracles pull data from external sources into the blockchain, allowing smart contracts to use this information to trigger specific actions or outputs. For instance, a smart contract managing an insurance policy might use an inbound oracle to receive weather data to determine if a payout condition has been met.
* **Outbound Oracles**: Unlike inbound oracles, outbound oracles send data from the blockchain to external systems. This functionality is crucial for scenarios that require blockchain events to influence real-world actions, such as unlocking a secure door upon a successful blockchain transaction.
* **Consensus-Based Oracles**: These oracles aggregate data from multiple sources to ensure accuracy, reliability, and trustworthiness. By utilizing a consensus mechanism, they minimize the risk of any single point of failure or malicious data entry, ensuring the integrity of the data fed to the blockchain.
* **Cross-Chain Oracles**: These oracles enable interoperability between different blockchains, allowing them to share and verify data across chains, which is essential for various decentralized finance (DeFi) applications.

#### Lumia L2 and Oracles

Lumia L2, an innovative Layer 2 solution, leverages oracles to optimize dApp operations while maintaining the foundational aspects of security and decentralization. By integrating oracles, Lumia L2 facilitates enhanced functionality across diverse sectors, including decentralized finance, real world asset tokenization and trading. This integration allows scalable, rapid interactions between on-chain operations and off-chain data inputs, forging a seamless integration between the isolated blockchain world and dynamic real-world applications.

In essence, the implementation of robust oracle systems is vital for the growth and sophistication of blockchain applications. These systems enable a rich, interactive ecosystem that transcends simple transactions to support a variety of complex, data-driven use cases, validating the blockchain platform's true potential as a transformative technology capable of influencing real-world operations.


# API3

[API3](https://api3.org/) is a collaborative project to deliver traditional API services to smart contract platforms in a decentralized and trust-minimized way. Its primary focus is to bring cryptocurrency price data to smart contracts in a secure and reliable manner. API3 price feeds have [OEV](https://docs.api3.org/oev-searchers/) (Oracle Extractable Value) built in to the price feeds by default, this allows dapps to monetize the update of the price feeds they are using. It is governed by a decentralized autonomous organization (DAO).

{% hint style="info" %}
Read more about how The API3 DAO works.\
[Click here](https://api3.org/dao/)
{% endhint %}

### Using dAPIs - API3 datafeeds <a href="#using-dapis-api3-datafeeds" id="using-dapis-api3-datafeeds"></a>

[dAPIs](https://docs.api3.org/dapps/quickstart/) are continuously updated streams of offchain cryptocurrency price data. They can power various decentralized applications such as DeFi lending, synthetic assets, stablecoins, derivatives, NFTs and more.

The data feeds are continuously updated by first party oracles using signed data. Dapp owners can read the onchain value of any dAPI in real-time.

Due to being composed of first-party data feeds, dAPIs offer security,\
transparency, cost-efficiency and scalability in a turn-key package.

Apart from relying on deviation threshold and heartbeat configuration updates,\
unlike traditional data feeds, [OEV Network](https://docs.api3.org/oev-searchers/in-depth/oev-network/) enables dapps using dAPIs to auction off the right to update the data feeds to searcher bots. Searcher bots can bid for price updates through the OEV Network to update the data feeds. All the OEV proceeds go back to the dapp.

The [API3 Market](https://market.api3.org/linea) enables users to connect to a dAPI and access the associated data feed services.

![dapi-main](https://hackmd.io/_uploads/BJ6y9zwSyg.png)

[Learn more about how dAPIs work](https://docs.api3.org/oev-searchers/in-depth/dapis/).

#### Subscribe to dAPIs <a href="#subscribe-to-dapis" id="subscribe-to-dapis"></a>

The [API3 Market](https://market.api3.org/lumia) lets users access dAPIs on both [Lumia Mainnet](https://market.api3.org/lumia) and [testnet](https://market.api3.org/lumia-sepolia-testnet).

**Explore, select and configure your dAPI**

The [API3 Market](https://market.api3.org/lumia) provides a list of all the dAPIs available across multiple chains including testnets. You can filter the list by mainnet or testnet chains. After selecting the chain, you can search for a specific dAPI by name. Once selected, you will land on the details page (eg ETH/USD on Lumia Testnet) where you can find more information about the dAPI.

The current supported configurations for dAPIs are:

| Deviation | Heartbeat |
| --------- | --------- |
| 0.25%     | 24 hours  |
| 0.5%      | 24 hours  |
| 1%        | 24 hours  |
| 5%        | 24 hours  |

![dapi-1](https://hackmd.io/_uploads/SkraqMPByg.png)

**Activate your dAPI**

{% hint style="info" %}
If a dAPI is already activated, make sure to check the expiration date and\
update parameters. You can update the parameters and extend the subscription by\
purchasing a new configuration.
{% endhint %}

After selecting the dAPI and the configuration, you will be presented with an\
option to purchase the dAPI and activate it. Make sure to check the time and\
amount of the subscription. If everything looks good, click "Purchase".

![dapi-2](https://hackmd.io/_uploads/rkSWofwrJg.png)

You can then connect your wallet and confirm the transaction. Once it's\
confirmed, you will be able to see the updated configuration for the dAPI.

**Get the proxy address**

Once you are done configuring and activating the dAPI, you can now integrate it. To do so, click on the "Integrate" button on the dAPI details page.

![dapi-5](https://hackmd.io/_uploads/r18fsfwr1l.png)

You can now see the deployed proxy contract address. You can now use this to\
read from the configured dAPI.

#### Read from a dAPI <a href="#read-from-a-dapi" id="read-from-a-dapi"></a>

Here's an example of a basic contract that reads from a dAPI.

```
// SPDX-License-Identifier: MIT
pragma solidity 0.8.17;

import "@openzeppelin/contracts@4.9.5/access/Ownable.sol";
import "@api3/contracts/api3-server-v1/proxies/interfaces/IProxy.sol";

contract DataFeedReaderExample is Ownable {
    // The proxy contract address obtained from the API3 Market UI.
    address public proxyAddress;

    // Updating the proxy contract address is a security-critical
    // action. In this example, only the owner is allowed to do so.
    function setProxyAddress(address _proxyAddress) public onlyOwner {
        proxyAddress = _proxyAddress;
    }

    function readDataFeed()
        external
        view
        returns (int224 value, uint256 timestamp)
    {
        // Use the IProxy interface to read a dAPI via its proxy contract .
        (value, timestamp) = IProxy(proxyAddress).read();
        // If you have any assumptions about `value` and `timestamp`,
        // make sure to validate them after reading from the proxy.
    }
}

```

* `setProxyAddress()` is used to set the address of the dAPI Proxy Contract.
* `readDataFeed()` is a view function that returns the latest price of the set dAPI.

[Read more about dAPIs](https://docs.api3.org/oev-searchers/in-depth/dapis/).

[Try deploying it on Remix!](https://remix.ethereum.org/#url=https://github.com/api3-ecosystem/remix-contracts/blob/master/contracts/DapiReader.sol\&lang=en\&optimize=false\&runs=200\&evmVersion=null\&version=soljson-v0.8.18+commit.87f61d96.js)

### Resources <a href="#resources" id="resources"></a>

Here are some additional developer resources:

* [API3 docs](https://docs.api3.org/)
* [API3 Market](https://market.api3.org/linea)
* [dAPI docs](https://docs.api3.org/oev-searchers/in-depth/dapis/)
* [OEV docs](https://docs.api3.org/oev-searchers/)
* [Github](https://github.com/api3dao/)
* [Medium](https://medium.com/api3)
* [YouTube](https://www.youtube.com/API3DAO)


# Supra

Lumia L2 integrates with Supra's high-performance oracle system to provide fast, reliable price feeds through their Distributed Oracle Agreement (DORA) protocol. This guide explains how to integrate Supra oracles into your dApps on Lumia L2.

### Overview

Supra provides two types of oracle implementations:

* **Pull Oracle**: On-demand price data with sub-second response time
* **Push Oracle**: Automated price updates with layer-1 security guarantees

This guide focuses on the Pull Oracle implementation, which gives you maximum control over when and how to fetch price data.

### Integration Process&#x20;

{% hint style="info" %}
Full list of feeds: <https://docs.supra.com/oracles/data-feeds/data-feeds-index>
{% endhint %}

#### 1. Smart Contract Setup

First, create your smart contract that will receive and process oracle data:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity 0.8.20;

import "@openzeppelin/contracts/access/Ownable.sol";

interface ISupraOraclePull {
    struct PriceData {
        uint256[] pairs;    // List of pairs
        uint256[] prices;   // prices[i] is the price of pairs[i]
        uint256[] decimals; // decimals[i] is the decimals of pairs[i]
    }

    function verifyOracleProof(bytes calldata _bytesproof) 
        external 
        returns (PriceData memory);
}

contract SupraPriceConsumer is Ownable {
    ISupraOraclePull internal oracle;
    
    // Store latest prices
    mapping(uint256 => uint256) public latestPrices;
    
    constructor(address oracle_) Ownable(msg.sender) {
        oracle = ISupraOraclePull(oracle_);
    }

    function deliverPriceData(bytes calldata _bytesProof) 
        external 
        onlyOwner 
    {
        ISupraOraclePull.PriceData memory prices = 
            oracle.verifyOracleProof(_bytesProof);
        
        // Store the latest prices
        for (uint256 i = 0; i < prices.pairs.length; i++) {
            latestPrices[prices.pairs[i]] = prices.prices[i];
        }
    }

    function updateOracleAddress(address oracle_) 
        external 
        onlyOwner 
    {
        oracle = ISupraOraclePull(oracle_);
    }
}
```

#### 2. Web2 Integration

You'll need a Node.js application to fetch price data from Supra's gRPC server and send it to your smart contract. Here's a basic implementation:

```javascript
const Web3 = require('web3');
const { PullServiceClient } = require('@supraoracles/sdk');

// Configuration
const config = {
    grpc: {
        address: "YOUR_GRPC_SERVER",
        pairIndexes: [1, 2, 3], // Asset pairs you want to track
        chainType: "EVM"
    },
    client: {
        rpcUrl: "https://testnet-rpc.lumia.org", // Lumia L2 RPC
        contractAddress: "YOUR_CONTRACT_ADDRESS",
        walletAddress: "YOUR_WALLET_ADDRESS",
        privateKey: "YOUR_PRIVATE_KEY"
    }
};

async function main() {
    // Initialize gRPC client
    const client = new PullServiceClient(
        config.grpc.address,
        config.grpc.pairIndexes,
        config.grpc.chainType
    );

    // Get price data
    const priceData = await client.getPrice();
    
    // Send to contract
    await sendToContract(priceData);
}

async function sendToContract(priceData) {
    const web3 = new Web3(config.client.rpcUrl);
    const contract = new web3.eth.Contract(ABI, config.client.contractAddress);
    
    const tx = {
        from: config.client.walletAddress,
        to: config.client.contractAddress,
        data: contract.methods.deliverPriceData(priceData).encodeABI(),
        gas: await contract.methods.deliverPriceData(priceData)
            .estimateGas({from: config.client.walletAddress})
    };

    const signedTx = await web3.eth.accounts.signTransaction(
        tx, 
        config.client.privateKey
    );
    
    await web3.eth.sendSignedTransaction(signedTx.rawTransaction);
}

// Run price updates every minute
setInterval(main, 60000);
```

#### 3. Contract Deployment

Deploy your contract using your preferred method (Hardhat, Truffle, etc.) with the appropriate Supra Oracle address:

**Lumia Mainnet**

* Oracle Address: [0x16f70cAD28dd621b0072B5A8a8c392970E87C3dD](https://explorer.lumia.org/address/0x16f70cAD28dd621b0072B5A8a8c392970E87C3dD)

### Best Practices

1. **Error Handling**

```solidity
function deliverPriceData(bytes calldata _bytesProof) 
    external 
    onlyOwner 
{
    try oracle.verifyOracleProof(_bytesProof) returns (
        ISupraOraclePull.PriceData memory prices
    ) {
        for (uint256 i = 0; i < prices.pairs.length; i++) {
            latestPrices[prices.pairs[i]] = prices.prices[i];
        }
    } catch {
        revert("Invalid oracle proof");
    }
}
```

2. **Price Validation**

```solidity
function validatePrice(uint256 price, uint256 oldPrice) 
    internal 
    pure 
    returns (bool) 
{
    // Example: Reject prices that changed more than 50%
    if (oldPrice > 0) {
        uint256 change = price > oldPrice ? 
            price - oldPrice : oldPrice - price;
        if (change * 100 / oldPrice > 50) {
            return false;
        }
    }
    return true;
}
```

3. **Update Frequency**

* Consider implementing a minimum time between updates
* Use price deviation thresholds to optimize gas costs
* implement redundancy in your web2 infrastructure

### Technical Specifications

* **Response Time**: Sub-second for pull oracle
* **Data Sources**: 40+ sources aggregated
* **Security**: Byzantine Fault Tolerant consensus with DORA
* **Price Calculation**: Median-of-medians with coherent cluster validation
* **Update Frequency**: Customizable (recommended: 1-5 minutes)
* **Gas Optimization**: Batch price updates supported

### Support & Resources

* [Supra Documentation](https://docs.supra.com/)


# Commodity Prices

## Commodity Price Oracle

Lumia provides real-time commodity price feeds through an on-chain oracle system, allowing developers to access current market prices for various commodities including precious metals, energy products, and agricultural goods.

### Overview

The commodity price oracle provides real-time price data for:

* Precious Metals (XAU/Gold, XAG/Silver, XPT/Platinum)
* Energy (Brent Oil, Natural Gas)
* Agricultural (Wheat, Corn, Sugar, Milk, Barley)
* Industrial Metals (Copper, Aluminum)

### How to Use

#### Contract Details

**Mainnet**

* Oracle Contract Address: `0x146447574c02deB3B802A1d4c9447CB7648aA56D`
* Sender Address: `0x1ad5b38c108feca340398538e45c4e3abcce7401`

**Testnet**

* Oracle Contract Address: `0x146447574c02deB3B802A1d4c9447CB7648aA56D`
* Sender Address: `0x682e737dcd1d679cb0dbfd34b137038480d45ead`

#### Integration Example

Here's a simple example showing how to query commodity prices in your smart contracts:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface IOracle {
    function readAsUint256ByKey(
        address sender,
        bytes32 key
    ) external view returns (int256);
}

contract CommodityPriceConsumer {
    IOracle public oracle;

    constructor(address _oracleAddress) {
        oracle = IOracle(_oracleAddress);
    }

    function getPrice(address senderAddress, bytes32 dataKey) external view returns (int256) {
        return oracle.readAsUint256ByKey(senderAddress, dataKey);
    }
}
```

#### Available Commodity Keys

Each commodity has a unique key for price queries. Here are the available commodities and their corresponding keys:

**Precious Metals**

* **Gold (XAU/USD)**
  * Mainnet Key: `0x1A4CF14646A65ED92B0F79291D4B537D4D634DAF4AE7BDEA7F95E16AFC106676`
  * Testnet Key: `0x8A8DF5C5476AD99D933701968710B3E18D16864A1D08F10916F09ED75E638DBB`
  * Data Source: investing.com/currencies/xau-usd
* **Silver (XAG/USD)**
  * Mainnet Key: `0xBB2F960A195C867A42E2AA5340AF4B3C62E789C0568FBBCE1925417E0FC62024`
  * Testnet Key: `0xF6743B90FD9E84F36C8E4D4D44A1642360BEFEBB48804CA013A613447930D311`
  * Data Source: investing.com/currencies/xag-usd

**Energy**

* **Brent Oil**
  * Mainnet Key: `0x08250CF04C3D466C046942A4C0968A955202155F43CADB5699065CC1CD966BA7`
  * Testnet Key: `0x694848F20CA37676DF8E14670A53CD521332673EAFEC2F6735D0D3064891BE82`
  * Data Source: investing.com/commodities/brent-oil
* **Natural Gas (NG)**
  * Mainnet Key: `0x598B52FA996FB56351A0B86CEFB0D12210D046DA2372044271F3495FC36081C9`
  * Testnet Key: `0x5AADF097C2159913CAA090D92F4947F7423FBC2404F6F6CDE21382E81B499198`
  * Data Source: investing.com/commodities/natural-gas

**Industrial Metals**

* **Copper (XCU)**
  * Mainnet Key: `0x3C66B438005B1823E9544AC4BCA1BF1F3F70E40F75EBCD0F6E2DB3E968EF46E5`
  * Testnet Key: `0xEB93D2CB02A06E6CE522A66C58A90300E2A41B1226EED095141AD0B8B759BCF7`
  * Data Source: fxempire.com/commodities/copper
* **Aluminum (ALU)**
  * Mainnet Key: `0xC746629AF536F44CA9EB4CEC98D18FE161700538200FABD786095A8D4894E0C2`
  * Testnet Key: `0xE5CE8F97E49B8C566DB4B97E61B0D89E6C08ED27D014A26C657D134C0A16199E`
  * Data Source: markets.businessinsider.com/commodities/aluminum-price

<details>

<summary>All keys available on Mainnet and Testnet</summary>

**💎 Precious Metals**

### Gold (XAU/USD)

* **Data Source:** investing.com/currencies/xau-usd
* **Mainnet Key:** `0x1A4CF14646A65ED92B0F79291D4B537D4D634DAF4AE7BDEA7F95E16AFC106676`
* **Testnet Key:** `0x8A8DF5C5476AD99D933701968710B3E18D16864A1D08F10916F09ED75E638DBB`

### Silver (XAG/USD)

* **Data Source:** investing.com/currencies/xag-usd
* **Mainnet Key:** `0xBB2F960A195C867A42E2AA5340AF4B3C62E789C0568FBBCE1925417E0FC62024`
* **Testnet Key:** `0xF6743B90FD9E84F36C8E4D4D44A1642360BEFEBB48804CA013A613447930D311`

### Platinum (XPT/USD)

* **Data Source:** investing.com/currencies/xpt-usd
* **Mainnet Key:** `0x6B3C26B2E54C43133545F29AD5EFA218C33B971ECFA3D416BBE124CCE36E3C23`
* **Testnet Key:** `0x7F37D17D21F56D6F66D6A24DEC201D9E71E687FD4532EADF0B0C5E97C486135B`

**⚡ Energy**

### Brent Oil

* **Data Source:** investing.com/commodities/brent-oil
* **Mainnet Key:** `0x08250CF04C3D466C046942A4C0968A955202155F43CADB5699065CC1CD966BA7`
* **Testnet Key:** `0x694848F20CA37676DF8E14670A53CD521332673EAFEC2F6735D0D3064891BE82`

### Crude Oil (CL1)

* **Data Source:** marketwatch.com/investing/future/cl.1
* **Mainnet Key:** `0x439A675FE33C23051E2204B402F68B3D91A1CAD75671D04508F74336BAF85C58`
* **Testnet Key:** `0x24507204DC7AFD2FE0DE6DE7E2332C2337C21CBC4EFCAF19B76AF78C2875E9A8`

### Natural Gas (NG)

* **Data Source:** investing.com/commodities/natural-gas
* **Mainnet Key:** `0x598B52FA996FB56351A0B86CEFB0D12210D046DA2372044271F3495FC36081C9`
* **Testnet Key:** `0x5AADF097C2159913CAA090D92F4947F7423FBC2404F6F6CDE21382E81B499198`

**🌾 Agricultural**

### Soybeans (S1)

* **Data Source:** marketwatch.com/investing/future/s.1
* **Mainnet Key:** `0xB9A774F78B3BBDD683742DDE0B16358520EDD8AB27E647957C86F8BE64F7714E`
* **Testnet Key:** `0x0580E41830824C4E6A5D33AE323333CAABD928DC86A460AB56BC4C671951ABDE`

### Sugar (SB1)

* **Data Source:** marketwatch.com/investing/future/sb.1
* **Mainnet Key:** `0x54E8C6E777BC98A2524B5796C806D60CF679F095A1E6EF7BD1115386504130AA`
* **Testnet Key:** `0x95EF16A79150121C34CF3CCCF617868B3CB328390645017CC8824184317258F5`

### Wheat

* **Data Source:** markets.businessinsider.com/commodities/wheat-price
* **Mainnet Key:** `0xD44B850488E674DB7B52C7BA53F62952AAA0F7736DDEC400EFC926125E6CE631`
* **Testnet Key:** `0x841CB2F3A7D406F8DA0C35D33EF75B568748D6E16572B5FAFBC9D0EA02903125`

### Milk

* **Data Source:** markets.businessinsider.com/commodities/milk-price
* **Mainnet Key:** `0xC8B9A93B99CAC793A3E9BC0D3F0C148E8BB74C2BA17ACF338AC9B68C4D3245A3`
* **Testnet Key:** `0x4B7629AE8E616818C1BE5893CBD393AC2F03F9C3C826891C7B33F481B65498BE`

### Corn (C1)

* **Data Source:** marketwatch.com/investing/future/c.1
* **Mainnet Key:** `0x1BFEC616411F9068149BDBB93E09A3382BD7CF1DD64087C2233904729DBD22BA`
* **Testnet Key:** `0xF00B0505C993C9E8D602A2F620F38F3C3372A964504EDF087798BB2DE2326810`

### Barley (NBLc1)

* **Data Source:** investing.com/commodities/ncdex-barley-futures
* **Mainnet Key:** `0x750C1DE2A1D628DFDC0D1B03CF4071B7CB7DBC83043DECC61F0297565074CABB`
* **Testnet Key:** `0x39C7337A5313B996E08A34446AB8A6A005830AC1BAED6AD1C529027528223222`
* **Note:** Price converted from INR to USD

### Hard Red Winter Wheat (HRN00)

* **Data Source:** marketwatch.com/investing/future/hrn00
* **Mainnet Key:** `0xB683174E54D13CD5CE8F3775A79CE55ECA20060D76A9FADA1962BFCA2D70E810`
* **Testnet Key:** `0x17FEB2E491F2D704607BD2CE00313564A732091B4844AE7C460532C2F1B1EEF3`

🏭 Industrial Metals

### Copper (XCU)

* **Data Source:** fxempire.com/commodities/copper
* **Mainnet Key:** `0x3C66B438005B1823E9544AC4BCA1BF1F3F70E40F75EBCD0F6E2DB3E968EF46E5`
* **Testnet Key:** `0xEB93D2CB02A06E6CE522A66C58A90300E2A41B1226EED095141AD0B8B759BCF7`

### Aluminum (ALU)

* **Data Source:** markets.businessinsider.com/commodities/aluminum-price
* **Mainnet Key:** `0xC746629AF536F44CA9EB4CEC98D18FE161700538200FABD786095A8D4894E0C2`
* **Testnet Key:** `0xE5CE8F97E49B8C566DB4B97E61B0D89E6C08ED27D014A26C657D134C0A16199E`

</details>

#### Testing the Oracle

You can test the oracle integration using the Neeedle UI:

**Mainnet:** [Neeedle UI Mainnet Link](https://neeedle.org/?abiUrl=https%3A%2F%2Fgithub.com%2Fhorizonx-tech%2Fchainsight-management-oracle%2Fblob%2Fmain%2Fabi%2FIOracle.json\&chainId=994873017\&contractAddress=0x146447574c02deB3B802A1d4c9447CB7648aA56D\&rpcUrl=https%3A%2F%2Fmainnet-rpc.lumia.org)

**Testnet:** [Neeedle UI Testnet Link](https://neeedle.org/?abiUrl=https%3A%2F%2Fgithub.com%2Fhorizonx-tech%2Fchainsight-management-oracle%2Fblob%2Fmain%2Fabi%2FIOracle.json\&chainId=1952959480\&contractAddress=0x146447574c02deB3B802A1d4c9447CB7648aA56D\&rpcUrl=https%3A%2F%2Ftestnet-rpc.lumia.org)

To test:

1. Connect your wallet to the appropriate network (Mainnet or Testnet)
2. Use the `readAsUint256ByKey()` function
3. Input the sender address and commodity key
4. Click "Read" to get the current price

#### Best Practices

1. **Error Handling**: Always implement proper error handling when interacting with the oracle
2. **Gas Optimization**: Cache oracle responses when possible instead of querying frequently
3. **Validation**: Verify returned prices are within expected ranges before using them
4. **Update Frequency**: Consider the update frequency of the price feeds when designing your application

#### Technical Considerations

* Price feeds are updated regularly but may have slight delays
* Check and confirm decimal places for each feed
* Prices are sourced from reliable market data providers
* The oracle contract is non-upgradeable for security

### Support

For technical support or questions about the commodity price oracle:

* Review the contract on [Explorer](https://explorer.lumia.org/address/0x146447574c02deB3B802A1d4c9447CB7648aA56D)


# Gateway Oracles

* **Entry Point Contract:** `0x10D5fa2fa8EBD9623867FAfB83650431Af0c041C`
* **Update Time:** 5 minutes
* **Decimals:** 8

| Asset        | Pair               | Pair ID (Asset Address)                      | Aggregator Address                           | Signer (Admin)                               |
| ------------ | ------------------ | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
| ADA          | ADA / USD          | `0x3ee2200efb3400fabb9aacf31297cbdd1d435d47` | `0x57B3320e0B9799b84e84CC782Cc1673755BBb5E7` | `0xF000351dfE832379901cBEC933Be660F606156ED` |
| ALGO         | ALGO / USD         | `0x89500e7a0E3C66Fd00e1b1a2957e5D30393E1907` | `0x22AB7c654443b56b07A05Bf6aA4BDF604b6eA4Ad` | `0x8B32b4A0A73eCA3d0eB3F14043Ae719E8Aebdafc` |
| ARB          | ARB / USD          | `0xb50721bcf8d664c30412cfbc6cf7a15145234ad1` | `0x9c403885F77E1E03bBA0b507BFAE854FF73Da8E6` | `0x0aa10A13166BaEA1016073b7fdb2dBa8b4045841` |
| AVAX         | AVAX / USD         | `0x1ce0c2827e2ef14d5c4f29a091d735a204794041` | `0x425183C9945144d653f498605B22B16E5673c5C8` | `0x2B832D8a8231b7303bE12334d9e5532924b68fBA` |
| BNB          | BNB / USD          | `0xB8c77482e45F1F44dE1745F52C74426C631bDD52` | `0x7dA9ee82E0829c4331A8Fd82F0333a98A2C006E7` | `0x488ac75Fa0e9Ce99d2a2495C495bC4df27B4F697` |
| BTC          | BTC / USD          | `0x44ECcb1d05e9d0c0302536847bba44AA28f626BD` | `0xC3b075773c02d26AeD6Eef3c295467f7d7CF7053` | `0x84815C2B62dc5Ee5C7889c034ebE9c74651264bf` |
| DOGE         | DOGE / USD         | `0xba2ae424d960c26247dd6c32edc70b295c744c43` | `0xf644AdCc2209B82b96B997E93dddbc386F9e2452` | `0x850F6727f27f46de9646BDbCe59168547d8306f5` |
| ETH          | ETH / USD          | `0xf471107cC2cD7f4e54A5e4a8bAF1188329d9CaD9` | `0x3D03A34DEAd651C2305CED7b8E096dd5F7e893d1` | `0x817cB13CdB6Fc493684a5AB53Bf5D45f7c694aea` |
| FIL          | FIL / USD          | `0x0d8ce2a99bb6e3b7db580ed848240e4a0f9ae153` | `0x044aFEaBe7b568d6AaE3f9288366459a57f070Cc` | `0x8469aa371986332b7c3d3f06b79E7C27C0cD7671` |
| FLR          | FLR / USD          | `0xB56Be7693853aADb502500D8b093a1845C6DcCB7` | `0x418498bE1a1b61F7deDC6396140b165921C3A09A` | `0x7AE159518561F8Fe203d23dc95f2B563ABEBc962` |
| LTC          | LTC / USD          | `0x4338665cbb7b2485a8855a139b75d5e34ab0db94` | `0xf82d472bAD46d3DEA4a687fa191faE79D92184A3` | `0x83Ad0b7b7E13B466497733c4fFADaFbbEC2F9877` |
| SOL          | SOL / USD          | `0x8b07d1077881a00b09abeD421d4Df464F87F30De` | `0x586000231031236f25dfed3E731B5f0114E454c8` | `0x35E824F28165BE1E33CdadfB2301c5A10AC2071f` |
| USDC         | USDC / USD         | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | `0xa9794e55d9f96598CECC7CB375d34907C3cE4e04` | `0x3c181F44654FE23ba2e0a761B2BB5D12B1B6ae17` |
| USDT         | USDT / USD         | `0xdAC17F958D2ee523a2206206994597C13D831ec7` | `0x0e61D288e716ee2C105B9c341bb27648eb2b083d` | `0x254864eaccEd5ca8FFb7dEAaFF64BB3b68F2756b` |
| XDC          | XDC / USD          | `0x19225BB926Fb19831104F787498cF92Fd79D73FF` | `0xFBaf9E1eD72C2F7bd8159980E90D70311Af2B451` | `0x538FfCb815c9cF1ea7eB516964BcD6280dcF1EB8` |
| XLM          | XLM / USD          | `0x2Fae5c9db9194c6619CBdcC8Dea40FA502d0e328` | `0x15bF7f8D51C3fa136981e7CBE3247fE7cbdbB601` | `0x800753f0e008085C97ea0bD987012d95Ba469731` |
| XRP          | XRP / USD          | `0x1d2f0da169ceb9fc7b3144628db156f3f6c60dbe` | `0xd1C14d941bE195e47168A06D3f4BCB0c0452fBf9` | `0x2f93796311dA555B4af2C08E01Bf7fa13D775532` |
| DAI          | DAI / USD          | `0x6B175474E89094C44Da98b954EedeAC495271d0F` | `0x646f59E82A8D47533f50B3ACEda622f57B4CfAeF` | `0x6c0aaE53ae9Fa0D5904d77056f8a65aa878AECa3` |
| LINEA        | LINEA / USD        | `0x1789e0043623282d5dcc7f213d703c6d8bafbb04` | `0x0Cf14F3cDFb779574CAB032AbA0c5A905D8c9af4` | `0xbEF3a8790c575FD2295567d42B6C080428508d4E` |
| SNT          | SNT / USD          | `0x744d70fdbe2ba4cf95131626614a1763df805b9e` | `0x658863f95903E3D98f3A090F320c7936602700dF` | `0xcAf62e7E1cecA71c896faD8381fDA46Fe74011D5` |
| ENS          | ENS / USD          | `0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72` | `0x7f030C8B961993134a8902a6C1403689A8354B3c` | `0x7dA0cb9988fB4C7532beBe86bB7f6683F80C24cD` |
| LDO          | LDO / USD          | `0x5A98FcBEA516Cf06857215779Fd812CA3beF1B32` | `0x6B96c13BDacedAbc1390790C61c8ebDAa4c16416` | `0x35AC03a026467Dac0D7D5E3750cCab160E025700` |
| GRT          | GRT / USD          | `0xc944e90c64b2c07662a292be6244bdf05cda44a7` | `0xDdE1D42b995a297DF4C35F748527de70Bb689c30` | `0x88f051fFA0f108a475Cfb4A39ED64d9e971ec3D7` |
| TRX          | TRX / USD          | `0x50327c6c5a14dcade707abad2e27eb517df87ab5` | `0x1e228e90983d8CdF0cAF9e4Eca887e977a47deF8` | `0x66E4C438499DfE7a89706cFE77b4f4D2c2EC98Fc` |
| BCH          | BCH / USD          | `0x8fF795a6F4D97E7887C79beA79aba5cc76444aDf` | `0x636DE4660bC3cCAB0AFd6c7751bD522652bAE1f8` | `0x2F903f8c5978Fcd318b75826948949573eC2bE47` |
| HYPE         | HYPE / USD         | `0xA06e44f6E88fD144F867BbCA68a35BB601E3890A` | `0xD2c3fc7e79f2Ba8288a43b5DEC2a607b40e47C4d` | `0xc33B111C5701E8775D6e69109383666e3E3746AC` |
| XMR          | XMR / USD          | `0x768D587Fbd998E47F0C8ef5195c7c81d75911C83` | `0x6F87100464ac955564fa0dd5ce693c4f3F2d8604` | `0x7E7097B7C70E2fd22DC38a46dBD67cBD5d6555Cb` |
| LEO          | LEO / USD          | `0x2af5d2ad76741191d15dfe7bf6ac92d4bd912ca3` | `0xD9e8822385146cAEDD89a9D199548D490b1a4B6c` | `0x4792a601053A40Fa4F56eEcE76BcA2AC96A8e72a` |
| LINK         | LINK / USD         | `0x514910771af9ca656af840dff83e8264ecf986ca` | `0x3e8b5b5d8823ef8721Fc1490A7b672EC8BeA18eb` | `0x69d944c21B55e5f9C3F5e9ea3274FA1fd4954Fbb` |
| CC           | CC / USD           | `0x34B2310CbEb1F0bdeD45282E00dD4c94a204562a` | `0x8Ab8dE62d8F4129dDc51894344970d13620a6e37` | `0xdE0b3528c188a056112b3cBB59fc36b847e398E9` |
| ZEC          | ZEC / USD          | `0x1ba42e5193dfa8b03d15dd1b86a3113bbbef8eeb` | `0x365d80297C206B0CF0e56a35bd649250555FC789` | `0x5b2a157100823f3c3FcB9FAB7C46E640d4157Bd3` |
| SUI          | SUI / USD          | `0xF24236F239120758AA955d0066Cd8D93793b52c4` | `0x36B7886Eda341Bd2Ba45Bd616d71D74EB3ecbE54` | `0x78ad352043F779d9aC50AEEb126D808AC008aA9A` |
| USD1         | USD1 / USD         | `0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d` | `0x12194712198aA108CED3EA707C38c8511424A46f` | `0xa96324D88391d5c9b66FfF823F91cb56410AC8ba` |
| HBAR         | HBAR / USD         | `0x0CDAf4D2CAea17C1fdda401347Bb17108AC71291` | `0x77F482334AD66D90598E66D8933C62dFf03A1292` | `0x9dbe5401B8F1e8A4E982D39C6d78ea529E73Ea9D` |
| WLFI         | WLFI / USD         | `0xdA5e1988097297dCdc1f90D4dFE7909e847CBeF6` | `0x5f8327DD31f626E35a732833cc7Ed3554052a210` | `0x27dBFc0a0501628a838F665e7a745958E89535D3` |
| PYUSD        | PYUSD / USD        | `0x6c3ea9036406852006290770bedfcaba0e23a0e8` | `0x8580534b1946fD6098c331A331794B1D283f086b` | `0xc89228FA278092258837F8332B872a3c57DB62B1` |
| TON          | TON / USD          | `0x582d872a1b094fc48f5de31d3b73f2d9be47def1` | `0x9EC7A9Dc1ee992E085B83308d6316E2C479B15d7` | `0x940eA092f3aAde44E4Ff803bF0D1E6829007DAF1` |
| CRO          | CRO / USD          | `0xa0b73e1ff0b80914ab6fe0444e65848c4c34450b` | `0x05D677BEE8d7960e718383640DCE06d100517FD3` | `0xE078a2229Df9eb7362B327786BFe413f121979cD` |
| DOT          | DOT / USD          | `0x7083609fce4d1d8dc0c979aab8c869ea2c873402` | `0x58eA1336bE7A46140d7A7a4a958c8BBeBE6E8021` | `0x0CCd9783C1ED0d415c960BA262398e0A7e167117` |
| UNI          | UNI / USD          | `0x1f9840a85d5af5bf1d1762f925bdaddc4201f984` | `0xb89dC12E36C3AC7396560767B80865eeDc320a64` | `0x7C6b88b67CDE21600cD25af3E4FBaFe94eaF428c` |
| MNT          | MNT / USD          | `0x3c3a81e81dc49a522a592e7622a7e711c06bf354` | `0x3475A820d01eF7536e07De62F9D210603012d68A` | `0x0AC5dbcdC743B2963Fc931fB51E81E0409DE307f` |
| TAO          | TAO / USD          | `0x7E396108220B688994223183d739451A252262aB` | `0x6ce2291Bf87FbCa04F33f5F6cD4D1ADf1e8f9950` | `0x26a8C2E249e0eDc6BAD4f11F2A48168f4DbE4dc2` |
| AAVE         | AAVE / USD         | `0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9` | `0xd6C93d9b5993f2fe338751f5538D3Fc44Ac666e3` | `0xe7638489a9cb5fa11A90e848b7BF57122B4b6d16` |
| OKB          | OKB / USD          | `0x75231f58b43240c9718dd58b4967c5114342a86c` | `0x8F8667bf417076625F210058C6F93eD8557F4cB0` | `0x42eE13D69D993379408A27e83409a0fadA331494` |
| M            | M / USD            | `0x22b1458e780f8fa71e2f84502cee8b5a3cc731fa` | `0x9f3279717a8046EF5bDa42B35923f35824A5De3A` | `0x41bdDCA2dFCC031b4B3a4e4AB5CAeCd76F613c0f` |
| NEAR         | NEAR / USD         | `0x85f17cf997934a597031b2e18a9ab6ebd4b9f6a4` | `0x50B617f094eb1Db166E633632218fCa49767Efb7` | `0x32b4cFe91252CDD23265c0a15A10729325679f19` |
| ETC          | ETC / USD          | `0x3d6545b08693dae087e957cb1180ee38b9e3c25e` | `0xd9c49bDb0De280740171E65e567896967d0DCb8f` | `0x3298E492d4eaecE4C125ecfaA47D8b6dF7d01f2D` |
| ICP          | ICP / USD          | `0x0C826714C530F4795E1bd637039c2dC1118191F9` | `0x3509bd28551d68C64e80b062bF752998E1C82e29` | `0x8B0d1Fc5CAF535c442734e3bf5bd6c319ECF5350` |
| ASTER        | ASTER / USD        | `0x000Ae314E2A2172a039B26378814C252734f556A` | `0xF5284F68C75BF95CBE5680E08eeb00c3dbBF436a` | `0x8C4C36EF83C762D79289Fe69a0Fb20c0933Ec54D` |
| ONDO         | ONDO / USD         | `0xfaba6f8e4a5e8ab82f62fe7c39859fa577269be3` | `0xFD3c60b53deB8733f57f6e707B1D44fb60273237` | `0xc3E2195630Aa17ef2A62ba863aeff7AFedde8ED8` |
| USDG         | USDG / USD         | `0xe343167631d89B6Ffc58B88d6b7fB0228795491D` | `0x193B3c57e47b3616Ba252891ad9506AEA594A0c3` | `0x275b05A55D84C7148Dca07D8562E89E72e8a1233` |
| SKY          | SKY / USD          | `0x56072C95FAA701256059aa122697B133aDEd9279` | `0x60f288b6b833e0a6b8ad0cA2fE0C186144D35774` | `0x17B563C5C04Af597EB2a910E8620615792c18CA5` |
| LUMIA        | LUMIA / USD        | `0xD9343a049D5DBd89CD19DC6BcA8c48fB3a0a42a7` | `0x568ee01CE4c8805a5D82b691b311B99B8cC6F725` | `0x3aE21Dac4AedeE3aB6D25D2Fd016B63963cDC843` |
| WTI          | WTI / USD          | `0x913487DbCF0F1EB5EC420FB9a7D05522a2856583` | `0xD95fCb814CD9D715131c59a6dE7612609D5D0033` | `0x7439b8967677F51f7cf920d7370831288F486DD7` |
| BRENT        | BRENT / USD        | `0x38664bFBbFac79154F94eaa485912d610eA0B337` | `0x2F4711C0cddBEB5B29136A25d322dA0464585BfE` | `0xAAfE2b8aD84F9Aedb8D3668fde2DAfa63f78fB26` |
| NATURAL\_GAS | NATURAL\_GAS / USD | `0xFB95C1B740B6973dce87DD73afb52eFf3B8C3999` | `0xA5d459074bcCbB05a16A11f3aCd0c863D1999632` | `0xd646179Cda17c9E62456E804bf47871cFbd9d9C1` |
| COPPER       | COPPER / USD       | `0xEb955041FBACE2D84774ecb8FCdbc001218f58a9` | `0x975aAabaeCcfC1B87FbCe250326B0B9683A82a5a` | `0x214915e922c6666c90cC980340c07C73A7052927` |
| ALUMINUM     | ALUMINUM / USD     | `0x217eA64a825d91CfAE8170C78EbaF28C21eFb9d6` | `0xF9C86f134CB908163605E76FBbefa9aC06E5293B` | `0x6e829Ad2f7bA77eba74a2B02C246ca61C8D91aBF` |
| WHEAT        | WHEAT / USD        | `0x6F558684F69555209Ab3A4391C66bED95c77961E` | `0x2A9220250537c1E79080CcDa5D7Afe61b5BC002E` | `0xA2041390D8bB3170Ec30daF4b66aa21dc90021DA` |
| CORN         | CORN / USD         | `0xdac5959d14f545A85112584e9eBdF21c7E126284` | `0xf94eB9730864D6E0C22712Ba52E80576c73d9C51` | `0xFF8bFaddCD84183c14a3D39a7E861bb84a113a55` |
| COFFEE       | COFFEE / USD       | `0x59de5A836040dF0c78eCA825e7dea02C879fCd9A` | `0x15A5ebaaE7dE84cEd12bbD5F5b306b6052C50907` | `0x721E8Aa40F190ab3bc82A77D9be8aC52fB417264` |


# Indexers

Indexers play a crucial role in the Lumia L2 ecosystem by transforming on-chain data into easily queryable formats, enabling efficient access to historical blockchain data, and powering essential analytics for decentralized applications (dApps). While Lumia L2's RPC nodes provide real-time access to current blockchain state, indexers complement this by organizing historical data in optimized database structures for complex queries and analytics.

### Understanding Blockchain Indexing

At its core, blockchain indexing involves:

1. **Data Extraction**: Continuously monitoring and processing blockchain events, transactions, and state changes
2. **Data Transformation**: Converting raw blockchain data into structured formats optimized for querying
3. **Data Storage**: Maintaining organized databases that allow for efficient retrieval and complex queries
4. **Query Interface**: Providing APIs (typically GraphQL) for applications to access the processed data

For Lumia L2, indexing is particularly important for many things but some examples could be:

* Tracking liquidity positions and historical trading activity across Lumia Stream
* Monitoring Real World Asset (RWA) tokenization events and ownership changes
* Analyzing cross-chain bridge transactions and token movements
* Supporting complex DeFi analytics and portfolio tracking

### Available Indexing Solutions

Lumia L2 supports two primary indexing solutions:

#### The Graph Protocol

A decentralized indexing protocol that enables the creation of open APIs (subgraphs) for accessing blockchain data. The Graph uses a decentralized network of indexers who process blockchain data and serve queries.

#### Goldsky

A high-performance indexing solution that offers managed indexing infrastructure with advanced features like real-time indexing and customizable data transformations.


# Indexing with TheGraph

Getting historical data on a smart contract can be frustrating when building a dapp. [The Graph](https://thegraph.com/) provides an easy way to query smart contract data through APIs known as subgraphs. The Graph’s infrastructure relies on a decentralized network of indexers, enabling your dapp to become truly decentralized.

**Lumia is supported by The Graph!**

### Quick Start

These subgraphs only take a few minutes to set up. To get started, follow these three steps:

1. Initialize your subgraph project
2. Deploy & Publish
3. Query from your dapp

Here’s a step by step walk through:

### 1. Initialize your subgraph project

#### Create a subgraph on Subgraph Studio⁠

Go to the [Subgraph Studio](https://thegraph.com/studio/) and connect your wallet. Once your wallet is connected, you can begin by clicking “Create a Subgraph”. When choosing a name, it is recommended to use Title Case: “Subgraph Name Chain Name.”

![Create a Subgraph](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/main/img/studio-create-subgraph.png)

You will then land on your subgraph’s page. All the CLI commands you need will be visible on the right side of the page:

![CLI commands](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/lumia/img/studio-cli-commands.webp)

#### Install the Graph CLI⁠

On your local machine run the following:

```
npm install -g @graphprotocol/graph-cli
```

#### Initialize your Subgraph⁠

You can copy this directly from your subgraph page to include your specific subgraph slug:

```
graph init --studio <SUBGRAPH_SLUG>
```

You’ll be prompted to provide some info on your subgraph like this:

![cli sample](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/lumia/img/cli-sample.png)

Simply have your contract verified on the block explorer and the CLI will automatically obtain the ABI and set up your subgraph. The default settings will generate an entity for each event.

### 2. Deploy & Publish

#### Deploy to Subgraph Studio⁠

First run these commands:

```bash
$ graph codegend
$ graph build
```

Then run these to authenticate and deploy your subgraph. You can copy these commands directly from your subgraph’s page in Studio to include your specific deploy key and subgraph slug:

```bash
$ graph auth --studio <DEPLOY_KEY>
$ graph deploy --studio <SUBGRAPH_SLUG>
```

You will be asked for a version label. You can enter something like v0.0.1, but you’re free to choose the format.

#### Test your subgraph⁠

You can test your subgraph by making a sample query in the playground section. The Details tab will show you an API endpoint. You can use that endpoint to test from your dapp.

![Playground](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/main/img/studio-playground.png)

#### Publish Your Subgraph to The Graph’s Decentralized Network

Once your subgraph is ready to be put into production, you can publish it to the decentralized network. On your subgraph’s page in Subgraph Studio, click on the Publish button:

![publish button](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/lumia/img/studio-publish-button.png)

You'll need some ETH on Arbitrum One to create an on-chain transaction. The Graph's smart contracts are all on Arbitrum One, even if your subgraph is indexing data from Lumia or any other [supported chain](https://thegraph.com/docs/en/developing/supported-networks/).

![Publish screen](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/lumia/img/studio-publish-modal.png)

> **Note:** When publishing, you might see a "Partial Indexer Support" alert. This means the network's subgraphs will be indexed by The Graph's default indexer, but won’t be served by independent indexers on The Graph Network. Testnets will always have this limitation. Mainnet subgraphs will soon be able to attract additional indexers once a voting process on The Graph Network is completed. This will unlock indexer rewards, incentivizing other indexers to support the subgraphs. At that point, the "Partial Indexer Support" warning will no longer appear.

### 3. Query your Subgraph

Congratulations! You can now query your subgraph on the decentralized network!

For any subgraph on the decentralized network, you can start querying it by passing a GraphQL query into the subgraph’s query URL which can be found at the top of its Explorer page.

Here’s an example from the [CryptoPunks Ethereum subgraph](https://thegraph.com/explorer/subgraphs/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK) by Messari:

![Query URL](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/main/img/explorer-query-url.png)

The query URL for this subgraph is:

`https://gateway-arbitrum.network.thegraph.com/api/`**\[api-key]**`/subgraphs/id/HdVdERFUe8h61vm2fDyycgxjsde5PbB832NHgJfZNqK`

Now, you simply need to  fill in your own API Key to start sending GraphQL queries to this endpoint.

#### Getting your own API Key

![API keys](https://raw.githubusercontent.com/alinobrasil/the_graph_getting_started/refs/heads/main/img/getting-api-key.png)

In Subgraph Studio, you’ll see the “API Keys” menu at the top of the page. Here you can create API Keys.

### Appendix

#### Sample Query

This query shows the most expensive CryptoPunks sold.

```graphql
{
  trades(orderBy: priceETH, orderDirection: desc) {
    priceETH
    tokenId
  }
}

```

Passing this into the query URL returns this result:

```
{
  "data": {
    "trades": [
      {
        "priceETH": "124457.067524886018255505",
        "tokenId": "9998"
      },
      {
        "priceETH": "8000",
        "tokenId": "5822"
      },
//      ...
```

💡 Trivia: Looking at the top sales on \[CryptoPunks website]\(<https://cryptopunks.app/cryptopunks/topsales>) it looks like the top sale is Punk #5822, not #9998. Why? Because they censor the flash-loan sale that happened.

#### Sample code

```jsx
const axios = require('axios');

const graphqlQuery = `{
  trades(orderBy: priceETH, orderDirection: desc) {
    priceETH
    tokenId
  }
}`;
const queryUrl = 'https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK'

const graphQLRequest = {
  method: 'post',
  url: queryUrl,
  data: {
    query: graphqlQuery,
  },
};

// Send the GraphQL query
axios(graphQLRequest)
  .then((response) => {
    // Handle the response here
    const data = response.data.data
    console.log(data)

  })
  .catch((error) => {
    // Handle any errors
    console.error(error);
  });
```

#### Additional resources:

* To explore all the ways you can optimize & customize your subgraph for a better performance, read more about [creating a subgraph here](https://thegraph.com/docs/en/developing/creating-a-subgraph/).
* For more information about querying data from your subgraph, read more [here](https://thegraph.com/docs/en/querying/querying-the-graph/).


# Indexing with Goldsky

Goldsky is Web3’s realtime data platform, giving developers access to world-class data infrastructure to power their onchain applications.

Seamlessly access the data you need with lightning-fast indexing, resilient subgraphs, and flexible data streaming pipelines. Spend less time on the complexities of infra maintenance and more time building incredible user experiences.

### Why Goldsky?

* **Scalable Infrastructure**: Scalable and resilient infrastructure, handling data challenges as your application grows.
* **Developer-Friendly Tools**: Easily integrate and iterate without being slowed down by complex data engineering.
* **Enterprise Support:** The Goldsky team is available 24/7 to help if things go wrong.

### Goldsky Subgraphs

**Subgraphs** let you efficiently access blockchain data relevant to your application.

* **Fast Queries**: Optimized infrastructure means faster query responses and better performance.
* **Flexible Integration**: Customize your queries and adapt indexing to suit your application's unique needs.
* **Tagging & Organization**: Use tagging to organize your data, making it easier to manage and access.

**Use Cases**: dApps, NFT marketplaces, gaming, DAOs – any scenario where you need reliable, real-time blockchain data.

### Getting Started

For more details, check out the [Goldsky Documentation](https://docs.goldsky.com/chains/lumia/?utm_source=lumia\&utm_medium=docs).&#x20;

Start building smarter, faster, and focus on what really matters: delivering a great experience to your users.


# Run an RPC

## Overview&#x20;

Operators can deploy permissionless RPC nodes for the Lumia zkEVM.

dApp projects ***should ideally*** run their own RPC node to retrieve the necessary blockchain data and shouldn't rely on public infrastructure. Public endpoints may respond slowly or not at all during times of high network traffic, and are rate limited.&#x20;

{% hint style="success" %}
Alchemy nodes will soon be available, docs will be updated once ready.
{% endhint %}

### Requirements System&#x20;

{% hint style="info" %}
Note: Storage space requirements will increase as the network grows.
{% endhint %}

* Linux OS
* 32GB RAM
* 1TB Storage (SSD)

### Prerequisites&#x20;

This tutorial requires Docker and Docker Compose to be installed on your machine. If you don't have these installed, check out the links provided below:

* Docker: <https://www.docker.com/get-started>
* Docker Compose: <https://docs.docker.com/compose/install/>

### Ethereum RPC Node

A Beam chain (Ethereum testnet) RPC node is required for running a Lumia zkEVM testnet node. There are two options available:

1. Set up your own - the Geth client is one example.
2. Use an RPC provider endpoint - developers building on Lumia may be entitled to special offers or promos.

This document does not cover the installation of the Ethereum node. We will use a public RPC endpoint for this document, but keep in mind that this is not a viable production solution: public endpoints are rate limited and as a result, your Lumia zkEVM node may not synchronize correctly.

### RPC via Docker Image

For a streamlined development experience, it’s highly recommended to utilize the below mentioned repository. The repo will be actively maintained by Lumia team and Docker images within dockerfile will be updated and will simply restarts services with new images to upgrade ForkIDs.

**Steps**

1. Clone GitHub repository to your local machine:

```
git clone https://github.com/LumiaChain/cdk-validium-permissionless-node.git
```

2. Navigate to the cloned directory:

```
cd cdk-validium-permissionless-node
```

3. Copy the content of [.env.example](https://github.com/orionprotocol/cdk-validium-permissionless-node/blob/main/.env.example) into the `.env` file and:
   1. Set `CDK_ERIGON_L1_RPC_URL`  to a valid L1 RPC URL, e.g. from Alchemy or Infura. \
      Make it a premium URL for better throughput and limits.
   2. Set `NETWORK_ENV`  to `testnet` or `mainnet` accordingly.
4. To start a node, run:

```
docker-compose up
```

{% hint style="danger" %}
Nodes will take up to 12 hours to sync up with latest state of Lumia L2.
{% endhint %}

#### Access from outside

To make an RPC endpoint URL available from outside, it is recommended to add an HTTP server.


# JSON RPC Endpoints

Endpoints are listed in the playground doc below.

### Terminal <a href="#terminal" id="terminal"></a>

Use the Lumia TestNet: <https://testnet-rpc.lumia.org> to test the endpoint methods in a terminal. For example:

#### `zkevm_estimateGasPrice` <a href="#zkevm_estimategasprice" id="zkevm_estimategasprice"></a>

```
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"zkevm_estimateGasPrice","params":[{"from":"0x0000000000000000000000000000000000000001","to":"0x0000000000000000000000000000000000000002","value":"0x1"}],"id":1}' \
    https://testnet-rpc.lumia.org
```

**Result**

```
{"jsonrpc":"2.0","id":1,"result":"0xe2ea2f0"}
```

<details>

<summary>RPC API Source</summary>

```json
{
    "openrpc": "1.0.0-rc1",
    "info": {
      "title": "Lumia zkEVM Endpoints",
      "version": "2.0.0"
    },
    "methods": [
      {
        "name": "zkevm_consolidatedBlockNumber",
        "summary": "Returns the latest block number that is connected to the latest batch verified.",
        "params": [],
        "result": {
          "$ref": "#/components/contentDescriptors/BlockNumber"
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": "0x1"
            }
          }
        ]
      },
      {
        "name": "zkevm_isBlockVirtualized",
        "summary": "Returns true if the provided block number is already connected to a batch that was already virtualized, otherwise false.",
        "params": [
          {
            "name": "blockNumber",
            "schema": {
              "$ref": "#/components/contentDescriptors/BlockNumber"
            }
          }
        ],
        "result": {
          "name": "result",
          "schema": {
            "type": "boolean"
          }
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": true
            }
          }
        ]
      },
      {
        "name": "zkevm_isBlockConsolidated",
        "summary": "Returns true if the provided block number is already connected to a batch that was already verified, otherwise false.",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/BlockNumber"
          }
        ],
        "result": {
          "name": "result",
          "schema": {
            "type": "boolean"
          }
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": true
            }
          }
        ]
      },
      {
        "name": "zkevm_batchNumber",
        "summary": "Returns the latest batch number.",
        "params": [],
        "result": {
          "$ref": "#/components/contentDescriptors/BatchNumber"
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": "0x1"
            }
          }
        ]
      },
      {
        "name": "zkevm_virtualBatchNumber",
        "summary": "Returns the latest virtual batch number.",
        "params": [],
        "result": {
          "$ref": "#/components/contentDescriptors/BatchNumber"
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": "0x1"
            }
          }
        ]
      },
      {
        "name": "zkevm_verifiedBatchNumber",
        "summary": "Returns the latest verified batch number.",
        "params": [],
        "result": {
          "$ref": "#/components/contentDescriptors/BatchNumber"
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": "0x1"
            }
          }
        ]
      },
      {
        "name": "zkevm_batchNumberByBlockNumber",
        "summary": "Returns the batch number of the batch connected to the block.",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/BlockNumber"
          }
        ],
        "result": {
          "$ref": "#/components/contentDescriptors/BatchNumber"
        },
        "examples": [
          {
            "name": "example",
            "description": "",
            "params": [],
            "result": {
              "name": "exampleResult",
              "description": "",
              "value": "0x1"
            }
          }
        ]
      },
      {
        "name": "zkevm_getBatchByNumber",
        "summary": "Gets a batch for a given number",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/BatchNumberOrTag"
          },
          {
            "name": "includeTransactions",
            "description": "If `true` it returns the full transaction objects, if `false` only the hashes of the transactions.",
            "required": true,
            "schema": {
              "title": "isTransactionsIncluded",
              "type": "boolean"
            }
          }
        ],
        "result": {
          "$ref": "#/components/contentDescriptors/Batch"
        },
        "examples": [
          {
            "name": "batch without tx details",
            "description": "Batch without transaction details",
            "params": [
              {
                "name": "batch number",
                "value": "0x1"
              },
              {
                "name": "include txs",
                "value": "false"
              }
            ],
            "result": {
              "name": "Batch",
              "value": {
                "number": "0x1",
                "coinbase": "0x0000000000000000000000000000000000000001",
                "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000001",
                "globalExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000002",
                "mainnetExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000003",
                "rollupExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000004",
                "localExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000005",
                "accInputHash": "0x0000000000000000000000000000000000000000000000000000000000000006",
                "timestamp": "0x642af31f",
                "sendSequencesTxHash": "0x0000000000000000000000000000000000000000000000000000000000000007",
                "verifyBatchTxHash": "0x0000000000000000000000000000000000000000000000000000000000000008",
                "transactions": [
                  "0x0000000000000000000000000000000000000000000000000000000000000009",
                  "0x0000000000000000000000000000000000000000000000000000000000000010",
                  "0x0000000000000000000000000000000000000000000000000000000000000011"
                ]
              }
            }
          },
          {
            "name": "batch with tx detail",
            "description": "Batch with transaction details",
            "params": [
              {
                "name": "batch number",
                "value": "0x1"
              },
              {
                "name": "include txs",
                "value": "true"
              }
            ],
            "result": {
              "name": "Batch",
              "value": {
                "number": "0x1",
                "coinbase": "0x0000000000000000000000000000000000000001",
                "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000001",
                "globalExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000002",
                "mainnetExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000003",
                "rollupExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000004",
                "localExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000005",
                "accInputHash": "0x0000000000000000000000000000000000000000000000000000000000000006",
                "timestamp": "0x642af31f",
                "sendSequencesTxHash": "0x0000000000000000000000000000000000000000000000000000000000000007",
                "verifyBatchTxHash": "0x0000000000000000000000000000000000000000000000000000000000000008",
                "transactions": [
                  {
                    "nonce": "0x1",
                    "gasPrice": "0x123456",
                    "gas": "0x59D8",
                    "to": "0x0000000000000000000000000000000000000002",
                    "value": "0x1",
                    "input": "0x",
                    "v": "0xAAA",
                    "r": "0x0000000000000000000000000000000000000000000000000000000000000010",
                    "s": "0x0000000000000000000000000000000000000000000000000000000000000011",
                    "hash": "0x0000000000000000000000000000000000000000000000000000000000000012",
                    "from": "0x0000000000000000000000000000000000000003",
                    "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000013",
                    "blockNumber": "0x1",
                    "transactionIndex": "0x0",
                    "chainId": "0x539",
                    "type": "0x0"
                  }
                ]
              }
            }
          }
        ]
      },
      {
        "name": "zkevm_getFullBlockByNumber",
        "summary": "Gets a block with extra information for a given number",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/BlockNumber"
          },
          {
            "name": "includeTransactions",
            "description": "If `true` it returns the full transaction objects, if `false` only the hashes of the transactions.",
            "required": true,
            "schema": {
              "title": "isTransactionsIncluded",
              "type": "boolean"
            }
          }
        ],
        "result": {
          "name": "getBlockByNumberResult",
          "schema": {
            "$ref": "#/components/schemas/FullBlockOrNull"
          }
        }
      },
      {
        "name": "zkevm_getFullBlockByHash",
        "summary": "Gets a block with extra information for a given hash",
        "params": [
          {
            "name": "blockHash",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/BlockHash"
            }
          },
          {
            "name": "includeTransactions",
            "description": "If `true` it returns the full transaction objects, if `false` only the hashes of the transactions.",
            "required": true,
            "schema": {
              "title": "isTransactionsIncluded",
              "type": "boolean"
            }
          }
        ],
        "result": {
          "name": "getBlockByHashResult",
          "schema": {
            "$ref": "#/components/schemas/FullBlockOrNull"
          }
        }
      },
      {
        "name": "zkevm_getNativeBlockHashesInRange",
        "summary": "Returns the list of native block hashes.",
        "params": [
          {
            "name": "filter",
            "schema": {
              "$ref": "#/components/schemas/NativeBlockHashBlockRangeFilter"
            }
          }
        ],
        "result": {
          "name": "filter",
            "schema": {
              "$ref": "#/components/schemas/NativeBlockHashes"
            }
        }
      },
      {
        "name": "zkevm_getTransactionByL2Hash",
        "summary": "Returns the information about a transaction requested by transaction l2 hash.",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/TransactionHash"
          }
        ],
        "result": {
          "$ref": "#/components/contentDescriptors/TransactionResult"
        }
      },
      {
        "name": "zkevm_getTransactionReceiptByL2Hash",
        "summary": "Returns the receipt information of a transaction by its l2 hash.",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/TransactionHash"
          }
        ],
        "result": {
          "name": "transactionReceiptResult",
          "description": "returns either a receipt or null",
          "schema": {
            "title": "transactionReceiptOrNull",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Receipt"
              },
              {
                "$ref": "#/components/schemas/Null"
              }
            ]
          }
        }
      },
      {
        "name": "zkevm_getExitRootsByGER",
        "summary": "Gets the exit roots accordingly to the provided Global Exit Root",
        "params": [
          {
            "$ref": "#/components/schemas/Keccak"
          }
        ],
        "result": {
          "$ref": "#/components/schemas/ExitRoots"
        },
        "examples": [
          {
            "name": "exit roots",
            "params": [
              {
                "name": "global exit root",
                "value": "0x0000000000000000000000000000000000000000000000000000000000000001"
              }
            ],
            "result": {
              "name": "Exit Roots",
              "value": {
                "blockNumber": "0x1",
                "timestamp": "0x642af31f",
                "mainnetExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000002",
                "rollupExitRoot": "0x0000000000000000000000000000000000000000000000000000000000000003"
              }
            }
          }
        ]
      },
      {
        "name": "zkevm_getLatestGlobalExitRoot",
        "summary": "Returns the latest global exit root used in a batch.",
        "params": [
        ],
        "result": {
          "name": "GER",
            "schema": {
              "$ref": "#/components/schemas/Keccak"
            }
        }
      },
      {
        "name": "zkevm_estimateCounters",
        "summary": "Estimates the transaction ZK Counters",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/Transaction"
          }
        ],
        "result": {
          "name": "counters",
          "description": "The counters used, limits and revert info when tx reverted",
          "schema": {
            "$ref": "#/components/schemas/ZKCountersResponse"
          }
        }
      },
      {
        "name": "zkevm_estimateFee",
        "summary": "Estimates the transaction Fee following the effective gas price rules",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/Transaction"
          }
        ],
        "result": {
          "name": "fee",
          "description": "The amount of the fee",
          "schema": {
            "$ref": "#/components/schemas/Integer"
          }
        }
      },
      {
        "name": "zkevm_estimateGasPrice",
        "summary": "Estimates the transaction Gas Price following the effective gas price rules",
        "params": [
          {
            "$ref": "#/components/contentDescriptors/Transaction"
          }
        ],
        "result": {
          "name": "gasPrice",
          "description": "The amount of gas price",
          "schema": {
            "$ref": "#/components/schemas/Integer"
          }
        }
      }
    ],
    "components": {
      "contentDescriptors": {
        "BlockNumber": {
          "name": "blockNumber",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/BlockNumber"
          }
        },
        "BatchNumber": {
          "name": "batchNumber",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/BatchNumber"
          }
        },
        "BatchNumberOrTag": {
          "name": "batchNumberOrTag",
          "required": true,
          "schema": {
            "title": "batchNumberOrTag",
            "oneOf": [
              {
                "$ref": "#/components/schemas/BatchNumber"
              },
              {
                "$ref": "#/components/schemas/BatchNumberTag"
              }
            ]
          }
        },
        "Batch": {
          "name": "batch",
          "description": "batch",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Batch"
          }
        },
        "Block": {
          "name": "block",
          "summary": "A block",
          "description": "A block object",
          "schema": {
            "$ref": "#/components/schemas/Block"
          }
        },
        "Transaction": {
          "required": true,
          "name": "transaction",
          "schema": {
            "$ref": "#/components/schemas/Transaction"
          }
        },
        "TransactionHash": {
          "name": "transactionHash",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/TransactionHash"
          }
        },
        "TransactionResult": {
          "name": "transactionResult",
          "description": "Returns a transaction or null",
          "schema": {
            "title": "TransactionOrNull",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Transaction"
              },
              {
                "$ref": "#/components/schemas/Null"
              }
            ]
          }
        }
      },
      "schemas": {
        "Null": {
          "title": "null",
          "type": "null",
          "description": "Null"
        },
        "BatchNumberTag": {
          "title": "batchNumberTag",
          "type": "string",
          "description": "The optional batch height description",
          "enum": [
            "earliest",
            "latest"
          ]
        },
        "Integer": {
          "title": "integer",
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]+$",
          "description": "Hex representation of the integer"
        },
        "Keccak": {
          "title": "keccak",
          "type": "string",
          "description": "Hex representation of a Keccak 256 hash",
          "pattern": "^0x[a-fA-F\\d]{64}$"
        },
        "Address": {
          "title": "address",
          "type": "string",
          "pattern": "^0x[a-fA-F\\d]{40}$"
        },
        "BlockHash": {
          "title": "blockHash",
          "type": "string",
          "pattern": "^0x[a-fA-F\\d]{64}$",
          "description": "The hex representation of the Keccak 256 of the RLP encoded block"
        },
        "BlockNumber": {
          "title": "blockNumber",
          "type": "string",
          "description": "The hex representation of the block's height",
          "$ref": "#/components/schemas/Integer"
        },
        "FullBlockOrNull": {
          "title": "fullBlockOrNull",
          "oneOf": [
            {
              "$ref": "#/components/schemas/FullBlock"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "BatchNumber": {
          "title": "batchNumber",
          "type": "string",
          "description": "The hex representation of the batch's height",
          "$ref": "#/components/schemas/Integer"
        },
        "TransactionHash": {
          "title": "transactionHash",
          "type": "string",
          "description": "Keccak 256 Hash of the RLP encoding of a transaction",
          "$ref": "#/components/schemas/Keccak"
        },
        "NonceOrNull": {
          "title": "nonceOrNull",
          "description": "Randomly selected number to satisfy the proof-of-work or null when its the pending block",
          "oneOf": [
            {
              "$ref": "#/components/schemas/Nonce"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "Nonce": {
          "title": "nonce",
          "description": "A number only to be used once",
          "$ref": "#/components/schemas/Integer"
        },
        "From": {
          "title": "From",
          "description": "The sender of the transaction",
          "$ref": "#/components/schemas/Address"
        },
        "BlockNumberOrNull": {
          "title": "blockNumberOrNull",
          "description": "The block number or null when its the pending block",
          "oneOf": [
            {
              "$ref": "#/components/schemas/BlockNumber"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "IntegerOrNull": {
          "title": "integerOrNull",
          "oneOf": [
            {
              "$ref": "#/components/schemas/Integer"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "AddressOrNull": {
          "title": "addressOrNull",
          "oneOf": [
            {
              "$ref": "#/components/schemas/Address"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "KeccakOrPending": {
          "title": "keccakOrPending",
          "oneOf": [
            {
              "$ref": "#/components/schemas/Keccak"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "To": {
          "title": "To",
          "description": "Destination address of the transaction. Null if it was a contract create.",
          "oneOf": [
            {
              "$ref": "#/components/schemas/Address"
            },
            {
              "$ref": "#/components/schemas/Null"
            }
          ]
        },
        "BlockHashOrNull": {
          "title": "blockHashOrNull",
          "description": "The block hash or null when its the pending block",
          "$ref": "#/components/schemas/KeccakOrPending"
        },
        "TransactionIndex": {
          "title": "transactionIndex",
          "description": "The index of the transaction. null when its pending",
          "$ref": "#/components/schemas/IntegerOrNull"
        },
        "Batch": {
          "title": "Batch",
          "type": "object",
          "readOnly": true,
          "properties": {
            "number": {
              "$ref": "#/components/schemas/BlockNumber"
            },
            "globalExitRoot": {
              "$ref": "#/components/schemas/Keccak"
            },
            "mainnetExitRoot": {
              "$ref": "#/components/schemas/Keccak"
            },
            "rollupExitRoot": {
              "$ref": "#/components/schemas/Keccak"
            },
            "accInputHash": {
              "$ref": "#/components/schemas/Keccak"
            },
            "timestamp": {
              "$ref": "#/components/schemas/Integer"
            },
            "sendSequencesTxHash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "verifyBatchTxHash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "closed": {
              "title": "closed",
              "type": "boolean",
              "description": "True if the batch is already closed, otherwise false"
            },
            "blocks": {
              "title": "blocksOrHashes",
              "description": "Array of block objects, or 32 Bytes block hashes depending on the last given parameter",
              "type": "array",
              "items": {
                "title": "blockOrBlockHash",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Block"
                  },
                  {
                    "$ref": "#/components/schemas/BlockHash"
                  }
                ]
              }
            },
            "transactions": {
              "title": "transactionsOrHashes",
              "description": "Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter",
              "type": "array",
              "items": {
                "title": "transactionOrTransactionHash",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Transaction"
                  },
                  {
                    "$ref": "#/components/schemas/TransactionHash"
                  }
                ]
              }
            },
            "stateRoot": {
              "$ref": "#/components/schemas/Keccak"
            },
            "coinbase": {
              "$ref": "#/components/schemas/Address"
            }
          }
        },
        "Block": {
          "title": "Block",
          "type": "object",
          "properties": {
            "number": {
              "$ref": "#/components/schemas/BlockNumberOrNull"
            },
            "hash": {
              "$ref": "#/components/schemas/BlockHashOrNull"
            },
            "parentHash": {
              "$ref": "#/components/schemas/BlockHash"
            },
            "nonce": {
              "$ref": "#/components/schemas/NonceOrNull"
            },
            "sha3Uncles": {
              "title": "blockShaUncles",
              "description": "Keccak hash of the uncles data in the block",
              "$ref": "#/components/schemas/Keccak"
            },
            "logsBloom": {
              "title": "blockLogsBloom",
              "type": "string",
              "description": "The bloom filter for the logs of the block or null when its the pending block",
              "pattern": "^0x[a-fA-F\\d]+$"
            },
            "transactionsRoot": {
              "title": "blockTransactionsRoot",
              "description": "The root of the transactions trie of the block.",
              "$ref": "#/components/schemas/Keccak"
            },
            "stateRoot": {
              "title": "blockStateRoot",
              "description": "The root of the final state trie of the block",
              "$ref": "#/components/schemas/Keccak"
            },
            "receiptsRoot": {
              "title": "blockReceiptsRoot",
              "description": "The root of the receipts trie of the block",
              "$ref": "#/components/schemas/Keccak"
            },
            "miner": {
              "$ref": "#/components/schemas/AddressOrNull"
            },
            "difficulty": {
              "title": "blockDifficulty",
              "type": "string",
              "description": "Integer of the difficulty for this block"
            },
            "totalDifficulty": {
              "title": "blockTotalDifficulty",
              "description": "Integer of the total difficulty of the chain until this block",
              "$ref": "#/components/schemas/IntegerOrNull"
            },
            "extraData": {
              "title": "blockExtraData",
              "type": "string",
              "description": "The 'extra data' field of this block"
            },
            "size": {
              "title": "blockSize",
              "type": "string",
              "description": "Integer the size of this block in bytes"
            },
            "gasLimit": {
              "title": "blockGasLimit",
              "type": "string",
              "description": "The maximum gas allowed in this block"
            },
            "gasUsed": {
              "title": "blockGasUsed",
              "type": "string",
              "description": "The total used gas by all transactions in this block"
            },
            "timestamp": {
              "title": "blockTimeStamp",
              "type": "string",
              "description": "The unix timestamp for when the block was collated"
            },
            "transactions": {
              "title": "transactionsOrHashes",
              "description": "Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter",
              "type": "array",
              "items": {
                "title": "transactionOrTransactionHash",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Transaction"
                  },
                  {
                    "$ref": "#/components/schemas/TransactionHash"
                  }
                ]
              }
            },
            "uncles": {
              "title": "uncleHashes",
              "description": "Array of uncle hashes",
              "type": "array",
              "items": {
                "title": "uncleHash",
                "description": "Block hash of the RLP encoding of an uncle block",
                "$ref": "#/components/schemas/Keccak"
              }
            }
          }
        },
        "FullBlock": {
          "title": "fullBlock",
          "type": "object",
          "properties": {
            "number": {
              "$ref": "#/components/schemas/BlockNumberOrNull"
            },
            "hash": {
              "$ref": "#/components/schemas/BlockHashOrNull"
            },
            "parentHash": {
              "$ref": "#/components/schemas/BlockHash"
            },
            "nonce": {
              "$ref": "#/components/schemas/NonceOrNull"
            },
            "sha3Uncles": {
              "title": "blockShaUncles",
              "description": "Keccak hash of the uncles data in the block",
              "$ref": "#/components/schemas/Keccak"
            },
            "logsBloom": {
              "title": "blockLogsBloom",
              "type": "string",
              "description": "The bloom filter for the logs of the block or null when its the pending block",
              "pattern": "^0x[a-fA-F\\d]+$"
            },
            "transactionsRoot": {
              "title": "blockTransactionsRoot",
              "description": "The root of the transactions trie of the block.",
              "$ref": "#/components/schemas/Keccak"
            },
            "stateRoot": {
              "title": "blockStateRoot",
              "description": "The root of the final state trie of the block",
              "$ref": "#/components/schemas/Keccak"
            },
            "receiptsRoot": {
              "title": "blockReceiptsRoot",
              "description": "The root of the receipts trie of the block",
              "$ref": "#/components/schemas/Keccak"
            },
            "miner": {
              "$ref": "#/components/schemas/AddressOrNull"
            },
            "difficulty": {
              "title": "blockDifficulty",
              "type": "string",
              "description": "Integer of the difficulty for this block"
            },
            "totalDifficulty": {
              "title": "blockTotalDifficulty",
              "description": "Integer of the total difficulty of the chain until this block",
              "$ref": "#/components/schemas/IntegerOrNull"
            },
            "extraData": {
              "title": "blockExtraData",
              "type": "string",
              "description": "The 'extra data' field of this block"
            },
            "size": {
              "title": "blockSize",
              "type": "string",
              "description": "Integer the size of this block in bytes"
            },
            "gasLimit": {
              "title": "blockGasLimit",
              "type": "string",
              "description": "The maximum gas allowed in this block"
            },
            "gasUsed": {
              "title": "blockGasUsed",
              "type": "string",
              "description": "The total used gas by all transactions in this block"
            },
            "timestamp": {
              "title": "blockTimeStamp",
              "type": "string",
              "description": "The unix timestamp for when the block was collated"
            },
            "transactions": {
              "title": "transactionsOrHashes",
              "description": "Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter",
              "type": "array",
              "items": {
                "title": "transactionOrTransactionHash",
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/FullTransaction"
                  },
                  {
                    "$ref": "#/components/schemas/TransactionHash"
                  }
                ]
              }
            },
            "uncles": {
              "title": "uncleHashes",
              "description": "Array of uncle hashes",
              "type": "array",
              "items": {
                "title": "uncleHash",
                "description": "Block hash of the RLP encoding of an uncle block",
                "$ref": "#/components/schemas/Keccak"
              }
            }
          }
        },
        "Transaction": {
          "title": "transaction",
          "type": "object",
          "required": [
            "gas",
            "gasPrice",
            "nonce"
          ],
          "properties": {
            "blockHash": {
              "$ref": "#/components/schemas/BlockHashOrNull"
            },
            "blockNumber": {
              "$ref": "#/components/schemas/BlockNumberOrNull"
            },
            "from": {
              "$ref": "#/components/schemas/From"
            },
            "gas": {
              "title": "transactionGas",
              "type": "string",
              "description": "The gas limit provided by the sender in Wei"
            },
            "gasPrice": {
              "title": "transactionGasPrice",
              "type": "string",
              "description": "The gas price willing to be paid by the sender in Wei"
            },
            "hash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "l2Hash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "input": {
              "title": "transactionInput",
              "type": "string",
              "description": "The data field sent with the transaction"
            },
            "nonce": {
              "title": "transactionNonce",
              "description": "The total number of prior transactions made by the sender",
              "$ref": "#/components/schemas/Nonce"
            },
            "to": {
              "$ref": "#/components/schemas/To"
            },
            "transactionIndex": {
              "$ref": "#/components/schemas/TransactionIndex"
            },
            "value": {
              "title": "transactionValue",
              "description": "Value of Ether being transferred in Wei",
              "$ref": "#/components/schemas/Keccak"
            },
            "v": {
              "title": "transactionSigV",
              "type": "string",
              "description": "ECDSA recovery id"
            },
            "r": {
              "title": "transactionSigR",
              "type": "string",
              "description": "ECDSA signature r"
            },
            "s": {
              "title": "transactionSigS",
              "type": "string",
              "description": "ECDSA signature s"
            }
          }
        },
        "FullTransaction": {
          "title": "fullTransaction",
          "type": "object",
          "required": [
            "gas",
            "gasPrice",
            "nonce"
          ],
          "properties": {
            "blockHash": {
              "$ref": "#/components/schemas/BlockHashOrNull"
            },
            "blockNumber": {
              "$ref": "#/components/schemas/BlockNumberOrNull"
            },
            "from": {
              "$ref": "#/components/schemas/From"
            },
            "gas": {
              "title": "transactionGas",
              "type": "string",
              "description": "The gas limit provided by the sender in Wei"
            },
            "gasPrice": {
              "title": "transactionGasPrice",
              "type": "string",
              "description": "The gas price willing to be paid by the sender in Wei"
            },
            "hash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "input": {
              "title": "transactionInput",
              "type": "string",
              "description": "The data field sent with the transaction"
            },
            "nonce": {
              "title": "transactionNonce",
              "description": "The total number of prior transactions made by the sender",
              "$ref": "#/components/schemas/Nonce"
            },
            "to": {
              "$ref": "#/components/schemas/To"
            },
            "transactionIndex": {
              "$ref": "#/components/schemas/TransactionIndex"
            },
            "value": {
              "title": "transactionValue",
              "description": "Value of Ether being transferred in Wei",
              "$ref": "#/components/schemas/Keccak"
            },
            "v": {
              "title": "transactionSigV",
              "type": "string",
              "description": "ECDSA recovery id"
            },
            "r": {
              "title": "transactionSigR",
              "type": "string",
              "description": "ECDSA signature r"
            },
            "s": {
              "title": "transactionSigS",
              "type": "string",
              "description": "ECDSA signature s"
            },
            "receipt": {
              "$ref": "#/components/schemas/Receipt"
            }
          }
        },
        "Transactions": {
          "title": "transactions",
          "description": "An array of transactions",
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Transaction"
          }
        },
        "Receipt": {
          "title": "receipt",
          "type": "object",
          "description": "The receipt of a transaction",
          "required": [
            "blockHash",
            "blockNumber",
            "contractAddress",
            "cumulativeGasUsed",
            "from",
            "gasUsed",
            "logs",
            "logsBloom",
            "to",
            "transactionHash",
            "transactionIndex"
          ],
          "properties": {
            "blockHash": {
              "$ref": "#/components/schemas/BlockHash"
            },
            "blockNumber": {
              "$ref": "#/components/schemas/BlockNumber"
            },
            "contractAddress": {
              "title": "ReceiptContractAddress",
              "description": "The contract address created, if the transaction was a contract creation, otherwise null",
              "$ref": "#/components/schemas/AddressOrNull"
            },
            "cumulativeGasUsed": {
              "title": "ReceiptCumulativeGasUsed",
              "description": "The gas units used by the transaction",
              "$ref": "#/components/schemas/Integer"
            },
            "from": {
              "$ref": "#/components/schemas/From"
            },
            "gasUsed": {
              "title": "ReceiptGasUsed",
              "description": "The total gas used by the transaction",
              "$ref": "#/components/schemas/Integer"
            },
            "logs": {
              "title": "logs",
              "type": "array",
              "description": "An array of all the logs triggered during the transaction",
              "items": {
                "$ref": "#/components/schemas/Log"
              }
            },
            "logsBloom": {
              "$ref": "#/components/schemas/BloomFilter"
            },
            "to": {
              "$ref": "#/components/schemas/To"
            },
            "transactionHash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "transactionL2Hash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "transactionIndex": {
              "$ref": "#/components/schemas/TransactionIndex"
            },
            "postTransactionState": {
              "title": "ReceiptPostTransactionState",
              "description": "The intermediate stateRoot directly after transaction execution.",
              "$ref": "#/components/schemas/Keccak"
            },
            "status": {
              "title": "ReceiptStatus",
              "description": "Whether or not the transaction threw an error.",
              "type": "boolean"
            }
          }
        },
        "BloomFilter": {
          "title": "bloomFilter",
          "type": "string",
          "description": "A 2048 bit bloom filter from the logs of the transaction. Each log sets 3 bits though taking the low-order 11 bits of each of the first three pairs of bytes in a Keccak 256 hash of the log's byte series"
        },
        "Log": {
          "title": "log",
          "type": "object",
          "description": "An indexed event generated during a transaction",
          "properties": {
            "address": {
              "title": "LogAddress",
              "description": "Sender of the transaction",
              "$ref": "#/components/schemas/Address"
            },
            "blockHash": {
              "$ref": "#/components/schemas/BlockHash"
            },
            "blockNumber": {
              "$ref": "#/components/schemas/BlockNumber"
            },
            "data": {
              "title": "LogData",
              "description": "The data/input string sent along with the transaction",
              "$ref": "#/components/schemas/Bytes"
            },
            "logIndex": {
              "title": "LogIndex",
              "description": "The index of the event within its transaction, null when its pending",
              "$ref": "#/components/schemas/Integer"
            },
            "removed": {
              "title": "logIsRemoved",
              "description": "Whether or not the log was orphaned off the main chain",
              "type": "boolean"
            },
            "topics": {
              "$ref": "#/components/schemas/Topics"
            },
            "transactionHash": {
              "$ref": "#/components/schemas/TransactionHash"
            },
            "transactionIndex": {
              "$ref": "#/components/schemas/TransactionIndex"
            }
          }
        },
        "Topics": {
          "title": "LogTopics",
          "description": "Topics are order-dependent. Each topic can also be an array of DATA with 'or' options.",
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Topic"
          }
        },
        "Topic": {
          "title": "topic",
          "description": "32 Bytes DATA of indexed log arguments. (In solidity: The first topic is the hash of the signature of the event (e.g. Deposit(address,bytes32,uint256))",
          "$ref": "#/components/schemas/DataWord"
        },
        "DataWord": {
          "title": "dataWord",
          "type": "string",
          "description": "Hex representation of a 256 bit unit of data",
          "pattern": "^0x([a-fA-F\\d]{64})?$"
        },
        "Bytes": {
          "title": "bytes",
          "type": "string",
          "description": "Hex representation of a variable length byte array",
          "pattern": "^0x([a-fA-F0-9]?)+$"
        },
        "NativeBlockHashes": {
          "title": "native block hashes",
          "description": "An array of hashes",
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Keccak"
          }
        },
        "NativeBlockHashBlockRangeFilter": {
          "title": "NativeBlockHashBlockRangeFilter",
          "type": "object",
          "properties": {
            "fromBlock": {
              "$ref": "#/components/schemas/BlockNumber"
            },
            "toBlock": {
              "$ref": "#/components/schemas/BlockNumber"
            }
          }
        },
        "ExitRoots": {
          "title": "ExitRoots",
          "type": "object",
          "readOnly": true,
          "properties": {
            "blockNumber": {
              "$ref": "#/components/schemas/BlockNumber"
            },
            "timestamp": {
              "title": "timestamp",
              "type": "string",
              "description": "The unix timestamp of the block mentioned in the blockNumber field"
            },
            "mainnetExitRoot": {
              "$ref": "#/components/schemas/Keccak"
            },
            "rollupExitRoot": {
              "$ref": "#/components/schemas/Keccak"
            }
          }
        },
        "ZKCountersResponse": {
          "title": "ZKCountersResponse",
          "type": "object",
          "readOnly": true,
          "properties": {
            "countersUsed": {
              "$ref": "#/components/schemas/ZKCountersUsed"
            },
            "countersLimits": {
              "$ref": "#/components/schemas/ZKCountersLimits"
            },
            "revertInfo": {
              "$ref": "#/components/schemas/RevertInfo"
            },
            "oocError": {
              "type": "string"
            }
          }
        },
        "ZKCountersUsed": {
          "title": "ZKCountersUsed",
          "type": "object",
          "readOnly": true,
          "properties": {
            "gasUsed": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedKeccakHashes": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedPoseidonHashes": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedPoseidonPaddings": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedMemAligns": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedArithmetics": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedBinaries": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedSteps": {
              "$ref": "#/components/schemas/Integer"
            },
            "usedSHA256Hashes": {
              "$ref": "#/components/schemas/Integer"
            }
          }
        },
        "ZKCountersLimits":{
          "title": "ZKCountersLimits",
          "type": "object",
          "readOnly": true,
          "properties": {
            "maxGasUsed": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedKeccakHashes": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedPoseidonHashes": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedPoseidonPaddings": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedMemAligns": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedArithmetics": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedBinaries": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedSteps": {
              "$ref": "#/components/schemas/Integer"
            },
            "maxUsedSHA256Hashes": {
              "$ref": "#/components/schemas/Integer"
            }
          }
        },
        "RevertInfo":{
          "title": "RevertInfo",
          "type": "object",
          "readOnly": true,
          "properties": {
            "message": {
              "type": "string"
            },
            "data": {
              "$ref": "#/components/schemas/Integer"
            }
          }
        }
      }
    }
  }

```

</details>

### Playground <a href="#playground" id="playground"></a>

The available methods are detailed in the playground description below.

Each method description provides:

* Method name and explanation.
* Parameters required if any and their details.
* Expected return.
* Examples.

{% embed url="<https://playground.open-rpc.org/?schemaUrl=https://gist.githubusercontent.com/dnzdlklc/b75ea6849eac715b889be61255242d47/raw/a92fd497a8cadf99ce2abbb5d7c5300407114cbd/LumiaRPC.json&uiSchema[appBar>]\[ui:input]=false\&uiSchema\[appBar]\[ui:splitView]=false" %}


# zkNode

### The Core Software for Running a zkEVM Node

zkNode is the essential software required to run a zkEVM node on the Lumia L2 network. It acts as a client that allows network users to synchronize and stay updated with the state of the Lumia L2 zkEVM. The two main factors that influence the L2 state and its finality are the trusted Sequencer and the trusted Aggregator.

#### zkNode Architecture and Transaction Flow

The zkNode architecture follows a modular design, as illustrated in the diagram below:

<figure><img src="/files/bkhpPotAs6jRx80NvTns" alt=""><figcaption><p>Based off PolygonCDK</p></figcaption></figure>

To understand the zkNode architecture, it's crucial to grasp the primary path taken by transactions, starting from when users submit them to the zkEVM network until they are finalized and incorporated into the L1 state.

Lumia L2 zkEVM achieves this through the interaction of several key components:

1. **Users**: They connect to the zkEVM network via an RPC node (e.g., MetaMask) and submit their transactions to the Pool DB.
2. **Pool DB**: This database stores the transactions submitted by users, waiting to be included in a batch by the Sequencer.
3. **Sequencer**: This node fetches transactions from the Pool DB, validates them, and puts valid ones into a batch. It submits the batches to L1 and sequences them for inclusion in the L1 state.
4. **Synchronizer**: This component updates the State DB by fetching data from Ethereum through Etherman.
5. **Etherman**: It is a low-level component that handles all interactions with the L1 network and smart contracts.
6. **State DB**: This database permanently stores state data (excluding Merkle trees).
7. **Aggregator**: This node produces zero-knowledge proofs (ZK-proofs) attesting to the integrity of the Sequencer's proposed state changes. It utilizes the Prover for this purpose.
8. **Prover**: This complex cryptographic tool generates ZK-proofs for hundreds of batches and aggregates them into a single ZK-proof, which is published as the validity proof.

### zkNode Roles and Required Services

&#x20;The zkNode software supports the execution of multiple roles, each requiring different services to function properly. While most services can run on separate instances, the JSON RPC can have multiple instances (all other services must have a single instance).

#### RPC Endpoints (Open to Any User):

* JSON RPC: Can run on separate instances and have multiple instances.
* Synchronizer: Single instance that can run on a separate instance.
* Executor & Merkle Tree: Can run on a separate instance.
* State DB: PostgreSQL that can run on a separate instance.

RPC Endpoints and its relevant documentation can be found below:

* [`zkEVM RPC endpoints`](https://github.com/0xPolygonHermez/zkevm-node/blob/develop/docs/json-rpc-endpoints.md)
* [`zkEVM RPC Custom endpoints documentation`](https://github.com/0xPolygonHermez/zkevm-node/blob/develop/docs/zkEVM-custom-endpoints.md)

#### Trusted Sequencer (Single Entity Role):

* **JSON RPC**: Can run on separate instances and have multiple instances.
* **Sequencer & Synchronizer**: Single instance that needs to run together.
* **Executor & Merkle Tree**: Can run on a separate instance.
* **Pool DB**: PostgreSQL that can run on a separate instance.
* **State DB**: PostgreSQL that can run on a separate instance.

#### Aggregator (Open to Anyone):

* **Synchronizer**: Single instance that can run on a separate instance.
* **Executor & Merkle Tree**: Can run on a separate instance.
* **State DB**: PostgreSQL that can run on a separate instance.&#x20;
* **Aggregator**: Single instance that can run on a separate instance.
* **Prover**: Single instance that can run on a separate instance.
* **Executor**: Single instance that can run on a separate instance.

By understanding the zkNode architecture, transaction flow, and the roles of different components, users can effectively participate in the Lumia L2 zkEVM network and contribute to its smooth operation.


# Run Local Validium Node

## Setting Up a Validium on Lumia L2

This quick start guide will walk you through the process of setting up a CDK validium on your local machine for the Lumia L2 network. The setup includes the following components:

* **Lumia zkEVM databases**: `data node, event, explorer L1 and L2, pool, state, and bridge service`
* **Lumia zkEVM node components**: `aggregator, approve service, sequencer and sequence sender, synchronizer`
* **L1 network (mock)**
* **Prover**
* **Explorers L1, L2**
* **JSON RPC explorer**
* **L2 gas pricer**
* **DAC**: `data availability service, DAC setup committee`
* **Lumia zkEVM bridge service and UI**

{% hint style="info" %}
Note: The documentation describes standard deployments. You can edit the configuration files to implement your own custom setups.
{% endhint %}

### Prerequisites Hardware Requirements:

* A Linux-based OS (e.g., Ubuntu Server 22.04 LTS)
* At least 16GB RAM with a 4-core CPU
* An AMD64 architecture system

{% hint style="info" %}
Note: CDK does not support ARM-based Macs.
{% endhint %}

### Software Requirements:

* Go
* Docker and Docker Compose

{% hint style="info" %}
Note: This document uses Docker Compose v2.
{% endhint %}

#### Installing Make on Ubuntu:

```
sudo apt install make
```

#### Cloning the Repository:

```
git clone https://github.com/orionprotocol/zkValidium-quickstart.git
cd zkValidium-quickstart
```

{% hint style="info" %}
Testnet and Mainnet zkNode Config files required can be downloaded using IPFS links below.

Testnet: [ipfs://QmNMnawxoSo7N1xFB73Ygw571T3Cj67Rqg2edsUCNob9h3/lumia-testnet-node-config.zip](https://d391b93f5f62d9c15f67142e43841acc.ipfscdn.io/ipfs/bafybeiaajj6kjs2jq4w2sqq3zf4cde4wersc5hpru7b32q427mvcjy5qyi/lumia-testnet-node-config.zip)

Mainnet: [ipfs://QmfNFzWVJxiu9JHHAS7rFnnUVCvdVTfrtF6TtmVKkcf1xA/prism-mainnet-node-config.zip](https://d391b93f5f62d9c15f67142e43841acc.ipfscdn.io/ipfs/bafybeih5aatsposgc6m6ncealoj7653hbx3zjhxt4tc6hfbirhysyh4z74/prism-mainnet-node-config.zip)
{% endhint %}

#### Create the `.env` file by copying the example:

```
cp .env.example .env
```

#### Launching Validium Locally

Pull the required Docker images from Docker Hub:

```
sudo docker compose pull
```

Start your local CDK validium:

```
sudo make run
```

Check the status of each container:

```
sudo docker compose ps
```

{% hint style="danger" %}
You may see errors related to `amd64` such as:

`zkevm-prover no matching manifest for linux/arm64/v8 in the manifest list entries`

`make: *** [run] Error 18`

If so, go to the `docker-compose.yml,` search for the component details - in this case `zkevm-prover`, and add the `platform: linux/amd64` environment variable under the `environment` variable (which you should also add if it is not there):

```markup
environment:
  - EXPERIMENTAL_DOCKER_DESKTOP_FORCE_QEMU=1
platform: linux/amd64
```

You may find the explorer components affected similarly.&#x20;
{% endhint %}

{% hint style="info" %}
If you receive any errors such as below, make sure your Docker has SUDO rights.

`error getting credentials - err: exit status 1`
{% endhint %}

You should see an output similar to the provided container status details.

<details>

<summary>Container Status</summary>

```
$ sudo docker ps --format "table {{.Names}}\t{{.Command}}\t{{.Status}}\t{{.Ports}}"
NAMES                              COMMAND                  STATUS                    PORTS
explorer-sig-provider              "./sig-provider-serv…"   Up 11 minutes             0.0.0.0:8151->8050/tcp, :::8151->8050/tcp
visualizer-proxy                   "/docker-entrypoint.…"   Up 11 minutes             80/tcp, 0.0.0.0:8083->8081/tcp, :::8083->8081/tcp
explorer-visualizer                "./visualizer-server"    Up 11 minutes             0.0.0.0:8152->8050/tcp, :::8152->8050/tcp
explorer-smart-contract-verifier   "./smart-contract-ve…"   Up 11 minutes             0.0.0.0:8150->8050/tcp, :::8150->8050/tcp
explorer-proxy-l2                  "/docker-entrypoint.…"   Up 11 minutes             0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:8084->8080/tcp, :::8084->8080/tcp
explorer-stats-l2                  "./stats-server"         Up 11 minutes             0.0.0.0:8154->8050/tcp, :::8154->8050/tcp
explorer-stats-db-l2               "docker-entrypoint.s…"   Up 11 minutes             0.0.0.0:7434->5432/tcp, :::7434->5432/tcp
explorer-frontend-l2               "./entrypoint.sh nod…"   Up 11 minutes             0.0.0.0:3001->3000/tcp, :::3001->3000/tcp
explorer-backend-l2                "sh -c 'bin/blocksco…"   Up 11 minutes             0.0.0.0:4001->4000/tcp, :::4001->4000/tcp
zkevm-explorer-json-rpc            "/bin/sh -c '/app/zk…"   Up 11 minutes             0.0.0.0:8124->8124/tcp, :::8124->8124/tcp, 8123/tcp, 0.0.0.0:8134->8134/tcp, :::8134->8134/tcp
explorer-backend-l2-db             "docker-entrypoint.s…"   Up 11 minutes             0.0.0.0:5437->5432/tcp, :::5437->5432/tcp
explorer-proxy-l1                  "/docker-entrypoint.…"   Up 11 minutes             0.0.0.0:81->80/tcp, :::81->80/tcp, 0.0.0.0:8082->8080/tcp, :::8082->8080/tcp
explorer-stats-l1                  "./stats-server"         Up 12 minutes             0.0.0.0:8153->8050/tcp, :::8153->8050/tcp
explorer-stats-db-l1               "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:7433->5432/tcp, :::7433->5432/tcp
explorer-frontend-l1               "./entrypoint.sh nod…"   Up 12 minutes             0.0.0.0:3000->3000/tcp, :::3000->3000/tcp
explorer-backend-l1                "sh -c 'bin/blocksco…"   Up 12 minutes             0.0.0.0:4000->4000/tcp, :::4000->4000/tcp
explorer-backend-l1-db             "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5436->5432/tcp, :::5436->5432/tcp
zkevm-bridge-ui                    "/bin/sh /app/script…"   Up 12 minutes             0.0.0.0:8088->80/tcp, :::8088->80/tcp
zkevm-bridge-service               "/bin/sh -c '/app/zk…"   Up 12 minutes             0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp
zkevm-bridge-db                    "docker-entrypoint.s…"   Up 12 minutes             5438/tcp, 0.0.0.0:5438->5432/tcp, :::5438->5432/tcp
zkevm-json-rpc                     "/bin/sh -c '/app/zk…"   Up 12 minutes             0.0.0.0:8123->8123/tcp, :::8123->8123/tcp, 0.0.0.0:8133->8133/tcp, :::8133->8133/tcp, 0.0.0.0:9091->9091/tcp, :::9091->9091/tcp
zkevm-aggregator                   "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp, 0.0.0.0:50081->50081/tcp, :::50081->50081/tcp, 0.0.0.0:9093->9091/tcp, :::9093->9091/tcp
zkevm-l2gaspricer                  "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp
zkevm-sequence-sender              "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp
zkevm-sequencer                    "/bin/sh -c '/app/zk…"   Up 12 minutes             0.0.0.0:6060->6060/tcp, :::6060->6060/tcp, 0.0.0.0:6900->6900/tcp, :::6900->6900/tcp, 8123/tcp, 0.0.0.0:9092->9091/tcp, :::9092->9091/tcp
zkevm-eth-tx-manager               "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp, 0.0.0.0:9094->9091/tcp, :::9094->9091/tcp
zkevm-sync                         "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp, 0.0.0.0:9095->9091/tcp, :::9095->9091/tcp
zkevm-prover                       "zkProver -c /usr/sr…"   Up 12 minutes             0.0.0.0:50061->50061/tcp, :::50061->50061/tcp, 0.0.0.0:50071->50071/tcp, :::50071->50071/tcp
zkevm-data-availability            "/bin/sh -c '/app/cd…"   Up 12 minutes             0.0.0.0:8444->8444/tcp, :::8444->8444/tcp
zkevm-data-node-db                 "docker-entrypoint.s…"   Up 12 minutes (healthy)   0.0.0.0:5444->5432/tcp, :::5444->5432/tcp
zkevm-mock-l1-network              "geth --http --http.…"   Up 12 minutes             0.0.0.0:8545-8546->8545-8546/tcp, :::8545-8546->8545-8546/tcp, 30303/tcp, 30303/udp
zkevm-event-db                     "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5435->5432/tcp, :::5435->5432/tcp
zkevm-pool-db                      "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5433->5432/tcp, :::5433->5432/tcp
zkevm-state-db                     "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5432->5432/tcp, :::5432->5432/tcp
```

</details>

If a service isn't running (i.e., it is in **Exit1** state), investigate further using the logs:

```
sudo docker compose logs <container_name>
```

<details>

<summary>Useful Commands:</summary>

* To stop CDK validium:

  ```
  sudo make stop
  ```
* To restart all services:

  ```
  sudo make restart
  ```

</details>

{% hint style="info" %}
Note: This local deployment runs on an L1 Geth instance.
{% endhint %}

### Testing Validium

1. Verify the block explorer is running by navigating to [localhost](http://localhost:3001/).&#x20;
2. Add the network to a Web3 wallet (e.g., MetaMask) by following the instructions on how to set up a network manually.&#x20;
3. Set the chain ID to 1001 and use "POL" as the currency symbol. The RPC node and block explorer containers can be found at ports 8123 and 80, respectively.
4. Switch to the new network in MetaMask.

{% hint style="danger" %}
**Important**: An account with test funds is available with the private key `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`.
{% endhint %}

> **NEVER** transfer real assets to the address associated with this private key.
>
> Import the account to MetaMask. The balance should show up as 100000 POL

5. Transfer some tokens to another account and confirm the transaction. Check the updated balances.
6. View the transaction details in the block explorer by clicking on the transaction details in MetaMask.

{% hint style="warning" %}
**Troubleshooting Stuck Transactions with MetaMask:** If you encounter a stuck transaction, it is likely due to an incorrect nonce setting. To resolve this issue:

1. Open MetaMask and navigate to your account.
2. Click on Settings > Advanced.
3. Locate the option "Clear activity and nonce data" and click on it. This resets the nonce data associated with the account, which often resolves transaction-related issues.
   {% endhint %}

### Testing the Bridge

Lumia L2 has a native bridge portal with UI that allows you to transfer funds between the L1 and the L2 validium.

#### L1 to L2:

1. Add the L1 RPC to MetaMask and switch to the L1 network. You will see the previously imported account with \~999 POL on the L1 chain.
2. Verify the bridge UI by navigating to localhost:8088. Click on "Connect a wallet" > "MetaMask" and select the previously imported account.
3. Enter the amount to bridge (e.g., 5) and click "Continue". After confirming that you understand what you're doing, you will see the "Confirm Bridge" page.
4. Click "Bridge" and approve the transaction on the MetaMask pop-up. Once bridging is complete, you should see the "Activity" page.

#### L2 to L1:

1. Switch the network on MetaMask to your validium chain and navigate back to localhost:8088. You should see both the updated L1 and L2 balances.
2. Enter an amount and follow the same process to bridge the funds back to L1.

   Note: You cannot bridge back funds more than what you have previously bridged from L1 to L2.
3. The L2->L1 bridging process is slightly different from L1->L2. After the transaction is executed, you will see the "Activity" page.
4. Click "Finalise" and approve the transaction. MetaMask will pop up a window asking you to switch to the L1 network first. Once the bridging is complete, you will see the confirmation page.


# Gas Fees

In Lumia L2, the gas fee is calculated by applying a fixed factor over the L1 gas fee. This price factor is a fixed value that doesn't change often, and its value is based on the rollup's cost to publish transactions to L1. In simple terms, gas prices in L2 will linearly follow gas prices in L1.

The formula for calculating the L2 gas fee is as follows:

$$
𝐿2{𝑔𝑎𝑠\_𝑓𝑒𝑒} = 𝐿1{𝑔𝑎𝑠\_𝑓𝑒𝑒} ∗ 𝐹𝑎𝑐𝑡𝑜𝑟
$$

where:

* 𝐿2{𝑔𝑎𝑠\_𝑓𝑒𝑒} represents the gas fee on Lumia L2
* 𝐿1{𝑔𝑎𝑠\_𝑓𝑒𝑒} represents the gas fee on the Ethereum L1
* 𝐹𝑎𝑐𝑡𝑜𝑟 is the fixed value that determines the relationship between L1 and L2 gas fees

The L1 fee will vary depending on the number of transactions on the L1 network. If the timing of your transaction is flexible, you can save costs by submitting transactions during periods of lower gas on the L1 (for example, over the weekend).

In the future, Lumia L2 plans to support a congestion mechanism based on EIP-1559, which will make the L2 gas fee dynamic and more responsive to network conditions.

### Fetching Gas Price from Lumia L2 RPC Node

To fetch the current gas price on Lumia L2, you can make the following RPC call to the Lumia L2 Sequencer:

```
curl https://mainnet-rpc.lumia.org \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_gasPrice","params":[],"id":1,"jsonrpc":"2.0"}'
```

The result of this RPC call will be the hex value of the gas price in wei.

By understanding the relationship between L1 and L2 gas fees and utilizing the provided RPC call, developers and users can make informed decisions about transaction costs and optimize their interactions with the Lumia L2 network.


# DA Lightclient

## Introduction

{% hint style="info" %}
We're using DA Node, DA Lightclient Node, and DA Lightclient interchangeably in this doc.
{% endhint %}

Lumia chain builds on the concept of lightclients introduced by the AvailDA team. Lumia uses them as part of the infrastructure to enable seamless cross-chain interaction and liquidity interoperability.&#x20;

As part of the goal to reach "**stage 2**", Lumia is putting emphasis on decentralization and community participation.&#x20;

What does it mean?

November 2024, Lumia held a "Node sale" event. Participants who have purchased a node license NFT can become a DA Lightclient operator. These node licenses grant the holders the right participate in running of the Lumia chain — spin up and operate a DA Lightclient and earn a portion of the LUMIA rewards allocated to the DA nodes cluster.

For a general understanding of the Lumia's lightclient , read [Lumia DA Lightclient Nodes](/lumia/data-availability/lumia-da-lightclient-nodes).

For a general understanding of the underlying Avail technology, read [Avail DA](/lumia/data-availability/what-is-avail-da).

## How to Run a DA Lightclient

The following provides step-by-step instructions on how to set up, run, and monitor DA Lightclient.

{% hint style="info" %}
The repository (repo), holding the application, is [**lumia-lightclient**](https://github.com/orionprotocol/lumia-lightclient).
{% endhint %}

### Prerequisites

Ensure the following are installed on your system:

* Docker: we recommend [Docker Desktop](https://docs.docker.com/desktop/) (Windows, Linux, macOS).
* Docker Compose: comes with Docker Desktop; alternatively, can be installed [separately](https://docs.docker.com/compose/install/).
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).

### Setting Up DA Lightclient

#### Step 1: Clone the repo

1. In the terminal, navigate to a directory of your choice, then clone the repo:&#x20;

   ```
   git clone https://github.com/orionprotocol/lumia-lightclient
   ```
2. Navigate to the directory of the newly cloned repo:&#x20;

   ```
   cd lumia-lightclient
   ```

#### Step 2: Create config.yaml

1. In the directory of the newly cloned repo, create a file named *config.yaml:*

   ```
   touch config.yaml
   ```
2. Copy-paste the following configuration into it:

   ```
   log_level = "info"
   http_server_host = "0.0.0.0"
   http_server_port = 7008
   port = 37100            # Unique P2P port
   webrtc_port = 37101     # Unique WebRTC port
   full_node_ws = ["wss://turing-rpc.avail.so/ws"]
   app_id = 206
   confidence = 92.0
   avail_path = "avail_path_node"
   # Bootstrap peer with updated port of the first node
   bootstraps = ["/ip4/127.0.0.1/tcp/37000/p2p/12D3KooWMm1c4pzeLPGkkCJMAgFbsfQ8xmVDusg272icWsaNHWzN"]
   ```

   \
   Ensure the file is saved in the same directory as *docker-compose.yml*.

### Running DA Lightclient

#### **Step 1: Build and Start the Docker Container**

To build and start the application in a docker container, from the directory of the newly cloned repo, run:

```
sudo docker compose up --build -d
```

**Step 2: Verify the Application and Record Your peer\_id**

1. Once the application starts:
   1. &#x20;Before proceeding, ensure you have waited at least 2 minutes after starting your Docker container.

   2. Verify its functionality by opening *<http://localhost:3008/status>* in your browser or using a tool like *curl* to access it.\
      You'll see a response; a typical response might look like this:

      ```
      {
        "status": {
          "success": false,
          "message": "connect ECONNREFUSED 172.23.0.3:7008",
          "errorDetails": "No details available"
        },
        "nodePeerData": {
          "peer_id": "12D3KooWJ2vPjeRRvGV64VVTUgjHEsrC3jdjEgmFS1BNeewmrtsY",
          "listeners": {
            "local": ["/ip4/127.0.0.1/tcp/37100"],
            "external": [],
            "public": []
          },
          "operation_mode": "client",
          "routing_table_peers_count": 0,
          "routing_table_external_peers_count": 0
        },
        "nodeApiIdData": {
          "modes": ["light", "app"],
          "app_id": 206,
          "genesis_hash": "0xd3d2f3a349...",
          "blocks": {
            "latest": 1235113,
            "available": {
              "first": 1235110,
              "last": 1235112
            },
            "app_data": {
              "first": 1235110,
              "last": 1235112
            }
          }
        }
      }
      ```

   3. In this status response, find and record the *peer\_id* value. This ID is essential for adding the node to the Lumia DA Tracker and must be recorded accurately for further configuration.

### Adding Your DA Lighclient into the System

To add your DA Lightlclient to the system:

1. Visit [Lumia DA Tracker.](https://lumia-da-tracker.blockchainaustralia.link/)
2. In the top-right corner, click **Add Node**.
3. Connect the wallet that holds your Node Sale NFT.
4. In the newly opened dialogue named **Add New Validator Node**:
   1. Enter the NFT Token ID from your wallet (we aim to auto-populate this in the future).
   2. Enter you **PeerId** (*peer\_id*) from the DA Lightclient that you've started.
   3. Click **Add Node** to finalize.

{% hint style="info" %}
Now that your node is added to the system, it starts accruing rewards per hour as long as your uptime remains above 95%. You can claim your rewards directly to your connected wallet on Lumia Network once a month.
{% endhint %}

### Monitoring Your DA Lightclient

Regularly check on your DA Lightlient to ensure it runs smoothly and keeps earning you LUMIA.

#### Check Logs

To monitor logs for debugging or status updates, use:

```
sudo docker compose logs -f
```

#### Access the API

* Endpoint: <http://localhost:3008/status>
* Method: `GET`&#x20;
* Example response structure:
  * Status: Details about the service's health and connection state.
  * Node Peer Data: Information about the node’s peer configuration and connectivity.
  * Node API ID Data: Blockchain details such as genesis\_hash, latest block, and app\_data.

### Troubleshooting

If your DA Lightclient is down, here are some common cases and solutions for them.

#### **1. Connection Refused**

Verify the service bound to port 7008 is running and accessible:

```
curl http://localhost:7008/v2/status
```

Check the container's networking:

```
docker network inspect <network-name>
```

#### **2. Port Conflicts**

Ensure ports *7008*, *37100*, and *37101* are not being used by other services.

**3. Debugging Logs**

View detailed logs to diagnose other issues:

```
sudo docker logs <container-name>
```

**4. Validate Configuration**

Ensure the *config.yaml* is formatted correctly and placed in the correct directory. Read [Setting Up DA Lightclient ](#setting-up-da-lightclient)for details.

### Further Help

If you encounter issues or need further assistance, feel free to [reach out to us on Discord](https://discord.gg/lumia).

<br>


# CDK Repos

| [CDK validium node](https://github.com/0xPolygon/cdk-validium-node)               | Node implementation for the CDK networks in Validium mode            |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [CDK validium contracts](https://github.com/0xPolygon/cdk-validium-contracts)     | Smart contracts implementation for the CDK networks in Validium mode |
| [CDK data availability layer](https://github.com/0xPolygon/cdk-data-availability) | Data availability nodes implementation for the CDK networks          |
| [Prover/Executor](https://github.com/0xPolygonHermez/zkevm-prover)                | zkEVM engine and prover implementation                               |
| [Bridge service](https://github.com/0xPolygonHermez/zkevm-bridge-service)         | Bridge service implementation for CDK networks                       |
| [Bridge UI](https://github.com/0xPolygonHermez/zkevm-bridge-ui)                   | UI for the CDK networks bridge                                       |


# FAQs

Below you will find some common questions and answers around Lumia zkEVM.

<details>

<summary>Which EVM op_codes are different on Lumia zkEVM?</summary>

* SELFDESTRUCT: removed by SENDALL&#x20;
* EXTCODEHASH: returns hash contract bytecode from zkEVM state tree (do not check if the account is empty)
* DIFFICULTY: returns 0
* BLOCKCHASH: returns all previous block hashes (not just the last 256 blocks)&#x20;
* BLOCKCHASH is the state root at the end of a processable transaction and it is stored on the system smart contract
* NUMBER: number of processable transactions

</details>

<details>

<summary>Which op_codes are missing from Lumia zkEVM?</summary>

Lumia zkEVM supports all opcodes but SHA256, BLAKE and PAIRINGS.

</details>

<details>

<summary>Which precompiled SmartContract functions does Lumia zkEVM support?</summary>

ecRecover and identity are presently supported. Others return a revert.

</details>


