The IOTX token, introduced in 2019 for the IoTeX L1, serves as the currency balancing incentives among validators (Delegates), Dapp builders, and users. Validators receive IOTX rewards for staking and validating transactions, while developers and users pay IOTX for transactions and smart contract interactions. Additionally, IOTX tokens are staked by token-holders for participation in network governance.

Expanded Tokenomics for IOTX

As IoTeX evolves from a simple L1 to a modular platform with interconnected infrastructure, the tokenomics of the IOTX token will also expand to align with our vision for IoTeX 2.0. This includes new utilities for the IOTX token, which will be integrated into the new technology offerings of IoTeX 2.0.

A key goal of IoTeX 2.0 tokenomics is to balance inflationary staking rewards and deflationary token burning based on platform usage. Additionally, we aim to incentivize DePIN Dapps and L2s to utilize our modular infrastructure. The upgraded tokenomics will not only introduce new utility and value for the IOTX token by connecting it to W3bstream, ioID, ioDDK, and other DIMs but also maintain a stable token supply through balanced inflationary and deflationary mechanisms.

As IoTeX's modular infrastructure sees increased adoption, the IOTX token will gain new value as the currency of the IoTeX 2.0 network.

IoTeX was founded in 2017 to empower people to own and control their smart devices, as well as the data and value their devices produce, by connecting the Internet of Things with blockchain. Our founding thesis was that the orchestration of billions of smart devices using decentralized blockchains would resolve major issues with the existing Internet of Things, such as trust, security, and sovereignty, as well as enable a new paradigm for user-owned device networks to flourish.

Over the past 6 years, we have pioneered the synthesis of the real world and blockchains, exploring and building out several core use cases.

IOTX tokens will be used across the entire IoTeX 2.0 infrastructure and ecosystem, expanding from the existing L1 utility to the new infrastructure modules.

Let's go through them:

Utility in the IoTeX Blockchain

Existing L1 Utility

IOTX tokens are still being used for rewarding Delegate nodes for validating L1 transctions and participate in consensus. Also, token holders will participate in governance by staking IOTX and vote their favorite delegate and receive IOTX rewards for it. The IOTX token will continue to serve as the native currency of the IoTeX L1 blockchain in IoTeX 2.0, where users and developers will pay fees in IOTX to deploy and utilize Dapps.

New L1 Utility

IOTX Re-Staking (Modular Security Pool)

This introduces a new economy involving staked IOTX, where the MSP effectively "leases" security and trust to DIMs, which are required to stake IOTX. This also creates new earning opportunities for IOTX stakers, who will earn their base IOTX staking rewards as well as additional rewards for re-staking their tokens, including potential bribes from DIM projects.

DePIN Infrastructures Staking IOTX

DePIN Infrastructure Modules (DIMs) will be required to stake IOTX in order to join the Modular Security Pool (MSP), gain security from the pool of re-staked assets, and offer their services in a verifiable fashion to Dapps, L2s, and users. DIMs may also choose to utilize IOTX as payment from Dapps that leverage their services, or they may utilize their own tokens. For example, a long-term storage provider like Filecoin or a data availability provider like NEAR would stake IOTX to join IoTeX 2.0 as a DIM, after which they could charge Dapps for their data services in their own tokens. For several of the IoTeX 2.0 DIMs that are built in-house by the IoTeX team, such as ioID and ioConnect, payment for these services will be denominated in the IOTX token.

DePIN Projects and L2s Fees

Projects and L2s that launch on the IoTeX 2.0 tech stack will pay IOTX to process transactions and interact with smart contracts. In addition, Dapps and L2 chains may choose their own modular tech stack and pay one or more DIMs for services, such as connectivity, data storage, off-chain compute, and more, in the DIM's token. To close the loop, most Dapps will have their own tokens that users will acquire and spend to access the Dapps services.

In addition to the utility for IOTX token above, there are also new designs for IoTeX 2.0 regarding how IOTX tokens will be burned based on infrastructure usage, how IOTX will be shared with Dapps and builders via incentives programs, and how new IOTX will be emitted to stakers going forward.

Inflationary Staking Rewards

When the IoTeX Mainnet launched in 2019, 12% of the total IOTX supply (1.2 billion IOTX) was allocated for staking rewards to Delegates. Token-holders stake IOTX to vote for Delegates who share a portion of the staking rewards with their voters. Since then, approximately 200 million IOTX per year has been distributed as block and epoch rewards to Delegates and voters. Block rewards were given to the Top 36 Consensus Delegates for each new block produced, while epoch rewards were distributed proportionally among the Top 100 Delegates every hour.

After more than four years of Mainnet operation, the initial IOTX allocation for staking rewards is nearly exhausted. To continue incentivizing Delegates to validate transactions and secure the network, IoTeX 2.0 will introduce inflationary staking rewards. These rewards involve minting new IOTX tokens, which are distributed to Delegates and stakers participating in network consensus.

Inflationary staking rewards will maintain the existing distribution structure, with block rewards for block-producing Delegates and epoch rewards for the Top 100 Delegates. This approach ensures a higher staking ratio and enhanced security for the IoTeX network. The specific annual inflation rate will be determined by network-wide governance, aiming for mild inflation that offers competitive staking rewards APRs, while considering deflationary token burning to maintain a stable token supply.

This concept aligns with practices of other Layer 1 blockchains, such as Ethereum, Solana, and Cosmos. For instance, Solana started with an 8% inflation rate, reducing annually by 15%, reaching about 5.5% in early 2024. IoTeX 2.0 aims to introduce a balanced inflationary mechanism that supports network growth and security, detailed further in the following sections.

Deflationary Burning

To maintain a stable token supply, IoTeX 2.0 introduces deflationary burning of tokens based on network usage, similar to the Burn and Mint Equilibrium model. For instance, Ethereum balances the issuance of new ETH with the deflationary burning of gas fees (EIP-1559) to achieve a stable or deflationary token supply. Since 2020, IoTeX has implemented the Burn-Drop program, resulting in approximately 4% (400M IOTX) of the total supply being burned based on new device registrations.

With IoTeX 2.0, new deflationary mechanisms will be introduced at the protocol level:

• Gas Fee Burning: Similar to Ethereum's EIP-1559, gas fees will be burned to incentivize and redistribute value to IOTX token-holders as network usage increases.

• ioID: Creating new on-chain identities for devices will require burning IOTX, with the burn rate dynamic based on the total number of registered devices. Additionally, obtaining Verifiable Credentials (VCs) for DIDs will involve burning IOTX, linking device identities to the IoTeX L1 and DIMs like W3bstream.

• Modular Products: The adoption of modular products like W3bstream, ioConnect, and ioDDK by Dapps and companies will drive deflationary burning of IOTX due to device interactions. Periodic token burns based on community-defined adoption thresholds may also be implemented.

IoTeX 2.0 tokenomics aim to reward increased usage of the platform's modular components through deflationary burning, initially counterbalancing inflationary staking rewards to maintain a stable token supply. As the platform achieves mass adoption, the IOTX token supply could become net deflationary. To support this growth, IoTeX 2.0 will allocate IOTX tokens to various builders through growth incentive programs.

Growth Incentives

An important pillar of IoTeX 2.0 is The Marshall DAO (IIP-23), a Decentralized Autonomous Organization (DAO) that will enable IoTeX stakeholders to make proposals regarding how to allocate IOTX incentives to grow the IoTeX ecosystem, including onboarding reputable DePIN projects and funding network-wide initiatives. This creates a transparent and meritocratic system where the best ideas are funded using IOTX. The Marshall DAO will initially be funded by more than 500M IOTX that was repurposed from the Burn-Drop allocation, which was decided by the IoTeX community via a network-wide vote in Q1 2024. In the future, additional funding for the Marshall DAO may be added via further network-wide votes to add newly minted IOTX to the pool.

The Marshall DAO employs a vote-escrow on-chain governance model, which means the more IOTX is staked in the DAO the more voting power a user has. This ensures decisions to fund projects and initiatives are made by those who are most invested in the long-term success of IoTeX. Token-holders that stake for at least 91 days will earn veIOTX, a non-transferrable on-chain token, which can be used to propose and vote on funding allocations via gauges that represent specific proposals. This means long-term stakers can vote using their veIOTX to shape how IOTX from the DAO funds various projects, including but not limited to boosting liquidity for DEX trading pairs on IoTeX, sponsoring early-stage DePIN projects via launchpads, accelerating DePIN projects via dual-mining, issuing grants for public goods and network-wide tools, and more.

Since its inception, IoTeX has been a pioneer in the blockchain industry, focusing on creating secure and scalable infrastructures that bridge the gap between the physical and digital worlds. Initially established as a Layer 1 blockchain, IoTeX has expanded its vision by spearheading the development of Decentralized Physical Infrastructure Networks (DePINs).

What is IoTeX 2.0?

IoTeX 2.0 unveils its brand new vision, upgrading its L1 blockchain into an open Modular Infrastructure for all DePINs.

The new whitepaper provides a comprehensive tech stack including composable modules and a unified trust layer to accelerate DePIN adoption. All underpinned by our new tokenomics design that links together the interconnected set of DePIN Dapps, L2 chains, modules, and devices.

IoTeX 2.0 is embarking on a new roadmap to onboard 100 million devices and unlock trillions of dollars in real-world value on chain within the next 3-5 years. Realizing IoTeX’s mission of “DePIN for Everyone”.

"At IoTeX, we firmly believe small teams with big hearts should have full support to build impactful DePINs. Because together, we can make more. That is the foundation of IoTeX's 2.0 mission to democratize DePIN for everyone." - Raullen Chai, CEO & Cofounder of IoTeX

Discover why IoTeX is the ideal platform for building and deploying your Decentralized Physical Infrastructure Network (DePIN) projects. Explore the key features and advantages that make IoTeX stand out.

1. Modular DePIN Infrastructure

IoTeX offers a modular approach allowing DePIN projects to construct a tech stack tailored to their needs. This includes critical products built in-house by IoTeX and integrations with partner products from top projects. This modularity enables DePIN builders to focus on what they do best (their infrastructure) while utilizing cutting-edge Web3 technologies such as Decentralized Identities, off-chain scaling, zero-knowledge proofs, and artificial intelligence​​.

2. MSP: A Unified Security Layer for DePINs

The IoTeX Modular Security Pool (MSP) provides a unified trusted layer, offering security and trust to DePIN Infrastructure Modules (DIMs) and DePIN applications. This system leverages existing security from established L1 blockchains like IoTeX, Bitcoin, and Ethereum, and utilizes restaking to ensure a robust and secure foundation for new projects​​.

3. End-to-End Support for DePIN Lifecycle

IoTeX 2.0 offers full support for DePIN projects throughout their lifecycle. From initial stages focused on tech stack development to later stages requiring scalability and decentralization, IoTeX provides the necessary infrastructure and public resources to capture attention, liquidity, and users​​.

4. Public Goods and Resources: tools for DePIN growth

IoTeX provides a suite of public goods designed to support DePIN builders. These include user-facing tools (e.g., explorers, wallets, bridges), developer-focused tools (e.g., IDEs, SDKs), and network-wide resources (e.g., governance, accelerator, liquidity). This ecosystem of tools and resources helps builders launch their projects more easily and provides the foundation for growth​​.

5. Meritocratic Tokenomics: Incentivizing Value

IoTeX employs a meritocratic tokenomics system designed to reward significant contributions. The IOTX token is more than just an L1 protocol token, it is used to incentivize various DePIN stakeholders, ensuring that rewards are distributed based on the value provided to the network. This system drives new utility to the IOTX token, making it a foundational currency for the DePIN sector​​.

6. Leading the Innovation with Cutting-edge Technologies

IoTeX integrates advanced technologies such as zero-knowledge proofs (ZKP), trusted execution environments (TEE), and self-sovereign identity (SSI) for devices. These technologies enhance security, scalability, and trust within DePIN projects, enabling innovative and secure applications​​.

7. Decentralized Governance

In addition to the existing decentralized process for managing Improvement Proposals for the blockchain, IoTeX 2.0 introduces one more important pillar for decentralized governance: The Marshall DAO (IIP-23). Marshall DAO is a Decentralized Autonomous Organization that will enable IoTeX stakeholders to make proposals regarding how to allocate IOTX incentives to grow the IoTeX ecosystem, including onboarding reputable DePIN projects and funding network-wide initiatives. This creates a transparent and meritocratic system where the best projects are funded using IOTX. allowing stakeholders to contribute to the growth of the IoTeX ecosystem.

Whether a DePIN focuses on physical resources or digital resources or targets a specific vertical, it must interface with real-world smart devices that generate an incredible amount of data. The need for a modular, end-to-end tech stack that connects real-world data to the blockchain world is essential.

Blockchain, as an immutable ledger, is a perfect foundation to document facts about what happened in the physical world; however, before writing "proofs of physical work" from devices to the blockchain permanently, a series of steps must be completed to verify the real world activity that actually happened and if the data is trustworthy.

Devices must be registered on-chain, raw data must be collected, parsed, sequenced, and stored, and computations over data must be performed in a verifiable fashion before any "proof of real-world activity" can be settled to a blockchain. The reference architecture above shows nine essential layers for DePIN projects to consider.

Our curated selection of key resources and topics, designed to provide you with quick access to the most popular topics on the IoTeX platform.

🤝 Community

👨‍💻 Builders

⚙️ Node Operators

IoTeX is committed to building a decentralized and inclusive ecosystem. As a digital democracy, IoTeX acknowledges and rewards community contributions in various ways.

Voters

In the IoTeX ecosystem, any token holder who stakes at least 100 IOTX and votes for a Delegate is recognized as a "Voter." Voting for a Delegate is a mandatory part of the staking process. By doing so, Voters help to secure and decentralize the network. In return for their participation, Voters receive rewards in the form of IOTX tokens, with the amount depending on their staking settings. This system creates a cycle that incentivizes voting, secures the network, and maintains decentralization.

Delegates

Delegates are elected by IOTX token holders and represent the IoTeX network. They run the protocol, maintain consensus, promote project awareness, organize community-wide initiatives, and more. Any token holder can self-candidate as a Delegate in the IoTeX ecosystem. After profile registration (which costs 100 IOTX) the minimum requirement to become a Delegate is to receive at least 1.2 million votes from a single account, which can be the candidate's own account self-voting, or a third-party account endorsing the candidate.

The top 100 Delegates, ranked by votes, receive rewards proportional to their share of the total votes versus the total votes in the network. This incentivizes participation and ensures the IoTeX ecosystem remains secure, decentralized, and vibrant.

Consensus Delegates

The top 36 Delegates with the most votes are “Consensus Delegates” that manage transaction verification and block production. Consensus Delegates also receive fixed block rewards for every mined block in addition to the variable rewards shared by all IoTeX Delegates.

IoTeX is compatible with the most recent Ethereum Virtual Machine (EVM), allowing developers to deploy smart contracts written in Solidity and interact seamlessly with the IoTeX blockchain.

This compatibility provides access to a wide range of Ethereum-based tools and libraries, enhancing the development ecosystem.

↗ Building and Deploying Smart contracts on IoTeX

Like other blockchains, IoTeX was bootstrapped from an initial ("genesis") state, which is then altered over time through transactions, or "Actions" as they are called in IoTeX.

An action is fundamentally a packet of data, signed by a blockchain account, that instructs the blockchain to make a specific change to the distributed ledger. The action can be sent to any blockchain node acting as a gateway, which in turn broadcasts it to the entire network of nodes for verification. Once verified, it gets applied and stored permanently in the ledger.

In IoTeX, there are different types of Actions depending on the type of operation required:

• Transfer Action

• Execution Action

• Governance Actions

Find the structure for all IoTeX Actions in the protobuf definition on GitHub:

An "account" is a fundamental concept in the IoTeX blockchain, represented by a pair of cryptographic keys: a private key and a public key, utilized to sign and verify blockchain actions.

IoTeX accounts could represent individual users, machines, or entities, facilitating interactions with the blockchain and dApps. Like Ethereum, IoTeX's architecture includes two types of accounts:

• Externally Owned Accounts (EOAs): Controlled by private keys, these accounts represent individual users or entities.

• Contract Accounts: These are associated with smart contracts deployed on the blockchain and operate based on their programmed logic. Each contract account maintains a balance, nonce, and storage, contributing to IoTeX's global state.

-> Learn more about IoTeX Account Cryptography

Account Abstraction

IoTeX supports Account Abstraction as defined by ERC-4337 v0.6.0.

By enabling people to use Smart Contracts as their primary accounts, ERC-4337 introduces many user experience benefits.

ERC-4337 runs on top of the blockchain and does not require any changes to the blockchain itself. Currently, the IoTeX Account Abstraction code is based on ERC-4337 0.6.0 release version.

ioID Identities

The blockchain also supports ioID identities, providing a secure and verified identity system that integrates seamlessly with various DePIN projects and applications.

↗ Learn more about ioID

IoTeX is designed to interact with other blockchains and systems. Cross-chain bridges and standards enable the integration of various tokens, applications, and services, making IoTeX a versatile platform for cross-blockchain Web3 development and innovation.

↗ Learn more about the iotube crosschain bridge

↗ Learn more about deploying crosschain tokens

Smart Contracts

Thanks to the native integration of the EVM, smart contracts on IoTeX function similarly to Ethereum. Developers upload reusable code pieces to the EVM's state, known as "smart contracts." These contracts, once invoked by sending a transaction to their address with specific parameters, execute the contract specific code performing some computations given certain conditions are met.

For instance, transferring IOTX to a designated contract address might result in the assignment of a certain digital asset to the sender. Smart contracts allow Web3 developers to create trusted applications on the IoTeX network, ranging from games to financial tools to decentralized infrastructures and data marketplaces.

The Blockchain Layer acts as the trust anchor of a DePIN application, managing participant identities, transactions, device data, and status, among other functions. It also handles crucial tasks such as verification of off-chain computations, orchestration of machine networks, distribution of token rewards to DePIN miners, and on-chain governance.

Introducing the IoTeX L1 Blockchain

Inspired by Ethereum, the IoTeX blockchain pioneers innovative solutions to address challenges related to blockchain scalability, which is paramount in Decentralized Physical Infrastructure Networks. IoTeX makes it easy for Web3 developers to create trustworthy and decentralized applications that benefit from instant transactions with 1-block finality and a transaction fee of under $0.001.

Quick facts about the IoTeX blockchain

Quick Links

↗ Configure Metamask

↗ IoTeX RPC Endpoints

↗ Download ioPay Mobile Wallet

Overview

The IOTX token, commonly known as "iotex," serves as the native cryptocurrency of the IoTeX blockchain, playing a role similar to Ether (ETH) in Ethereum. It underpins a marketplace for computational power, ensuring that nodes who run the blockchain are financially motivated to validate and process transactions, as well as to supply the computational power required to execute smart contracts across the network. This mechanism is vital for maintaining the network's operation and efficiency.

↗ Read more about IOTX token in this blog article

Tokenomics

↗ Check out IOTX on CoinMarketCap

↗ Check out IOTX on CoinGecko

Transaction fees

In the IoTeX network, anyone initiating a transaction must pay a fee in IOTX, similar to Ethereum's transaction fee structure. This fee compensates the network nodes responsible for validating, executing, and recording the transaction on the blockchain. The size of the fee corresponds to the computational effort required for the transaction, helping to prevent network abuse by discouraging excessively demanding computational tasks without appropriate compensation.

IOTX Token utility

IOTX serves multiple crucial roles in maintaining the crypto-economic security of the IoTeX network:

Rewards: IOTX is used to reward nodes who successfully propose new blocks and identify fraudulent activities within the network.

Staking by Validators: Validator nodes stake IOTX as a form of commitment and collateral, helping to safeguard the network against dishonest behaviors.

Delegate Election: IOTX is crucial for staking by token holders, who use it to vote for delegates. This process is vital for maintaining decentralized governance and overall network security.

Burn-Drop Mechanism: In a unique deflationary tactic specific to the IoT environment, IOTX implements the "Burn-Drop" scheme. Whenever a new IoT device is registered on the IoTeX blockchain, a specified number of tokens are burned, and a corresponding amount is airdropped to stakers, simultaneously reducing the total supply and rewarding active participants.

IOTX Token Fractions

6 fractions of the IOTX token are defined, where 1 Rau is the smallest IOTX token unit:

What Are ERC20 Tokens and NFTs?

ERC20 tokens provide a standardized approach for creating fungible tokens on EVM blockchains, facilitating everything from decentralized finance to governance mechanisms. NFTs, on the other hand, certify the uniqueness and ownership of digital assets, opening up possibilities for art, collectibles, and beyond.

IoTeX supports ERC20 tokens and NFTs through its Ethereum Virtual Machine (EVM) compatibility. This allows developers to deploy Ethereum-based smart contracts directly on IoTeX, taking advantage of faster transaction times, reduced costs, and enhanced scalability.

ERC20 Tokens

ERC20 is a protocol standard that defines rules for issuing fungible tokens on Ethereum. Key functions include:

• totalSupply(): Displays the total token supply.

• balanceOf(address): Provides the token balance of a specific account.

• transfer(address, amount): Enables token transfers between accounts.

• approve(address, amount) and allowance(owner, spender): Manage spending permissions.

NFTs

Unlike ERC20 tokens, NFTs are unique digital tokens that represent ownership and authenticity of a specific item or asset, managed on the blockchain. Each NFT has distinct information or attributes that make it irreplaceable, making them ideal for applications in digital art, real estate, and more.

Advantages on IoTeX

Using ERC20 tokens and NFTs on IoTeX offers several benefits:

Faster Transactions: IoTeX’s blockchain architecture offers quicker transaction confirmations with instant finality compared to other EVM blockchains.

Lower Fees: Transaction costs on IoTeX are significantly lower, enhancing the economic viability for microtransactions, large-volume operations, and contract executions.

DePIN Applications: IoTeX’s focus on Decentralized Physical Infrastructure Networks (DePIN) integrates ERC20 and NFTs with real-world data and utility, enabling use cases like the incentivization of community-owned infrastructure and data marketplaces.

This document provides an overview of the various formats of the IOTX token, including their respective networks, descriptions, and typical usages. Understanding these different formats is essential for users interacting with the IoTeX network and its associated DeFi applications.

IoTeX Improvement Proposals

An IoTeX Improvement Proposal (or "IIP") is a design document providing information to the IoTeX community, or describing a new feature for IoTeX, its processes, or its environment.

IIPs are intended to be the primary mechanisms for proposing new features, collecting community input on an issue, and documenting the design decisions that have been implemented in the IoTeX ecosystem.

Because IIPs are maintained as text files in a versioned repository, their revision history also represents the historical record of the feature proposal itself.

Submitting an IIP

Anyone can submit an IIP: A proposal should provide a concise technical specification and a rationale for the new feature. The IIP author is responsible for building consensus within the community and documenting dissenting opinions.

You can read more about IoTeX IIPs, browse past proposals and submit a new one by sending a pull request to the GitHub repository:

The Governance Portal

The IoTeX Governance Portal is powered by Snapshot, a no-fee governance tool based on IPFS that makes it simple for decentralized networks to run open votes, polls, and referendums. Follow the link below to browse through or vote on existing proposals, as well as create a new one. 👇

The Governance Forum

Check out our governance forum, if you'd like to meet the community and discuss new proposals: 👇

Feel free to checkout this blog article if you'd like to learn more about decentralized governance in the IoTeX ecosystem.

IOTX ERC20

IOTX ERC20 token is the original form of the IOTX token that was issued on the Ethereum blockchain during the initial development phase of the IoTeX blockchain protocol. Before the launch of the IoTeX blockchain in 2019, IOTX was primarily an Ethereum ERC20 token to facilitate early distribution and community engagement.

Wrapped IOTX (WIOTX)

CrossChain IOTX (CIOTX)

Blockchain Wallets Overview

A blockchain wallet, sometimes just called a 'crypto wallet,' is a digital tool that allows individuals to store, send, and receive digital currencies like IoTeX, Ethereum, and many others. If you're just getting started with blockchain, think of it like an online banking app, but instead of using it for traditional money, you use it for cryptocurrencies.

Just like learning to use a new app or device, it might take a little time to get used to how a blockchain wallet works, but it's an essential tool for anyone looking to engage with cryptocurrencies.

IoTeX Wallets

IoTeX users have a wide range of both official and third-party wallets to choose from. For more information, see the next section, which provides an introduction to IoTeX wallets.

Connect your favorite wallet

You can connect any multi-chain wallet to ioTeX, as long as it supports the addition of an EVM chain. Below are the required configuration details:

ioPay Mobile Wallet is a versatile and secure digital wallet designed for the IoTeX network also offering a comprehensive solution for managing digital assets across multiple blockchain networks, making it a valuable tool for users looking to engage with a variety of cryptocurrencies and decentralized applications.

Main Features of ioPay Mobile Wallet

1. Staking and Voting Capabilities: The wallet enables in-app staking and voting processes on the IoTeX blockchain, allowing users to contribute to network governance and consensus mechanisms.

2. Multi-Chain Support: ioPay supports multiple blockchain networks pre-configured and ready to use, including Ethereum, Polygon, BSC (Binance Smart Chain), Arbitrum, Avalanche, Fantom, and Base. This multi-chain functionality allows users to manage a diverse range of digital assets across various ecosystems.

3. User-Friendly Interface: The wallet offers an intuitive interface, ensuring ease of use for both novices and seasoned crypto enthusiasts. This simplifies the process of managing digital assets and engaging with dApps.

4. High-Level Security: ioPay prioritizes the security of your digital assets. It incorporates advanced security measures to safeguard your tokens and sensitive data like biometric authentication and per-transaction authentication options.

5. In-App Swap Capability: ioPay integrates in-app swap functionality, allowing users to easily swap tokens using popular DeFi platforms like mimo on IoTeX or Uniswap on Ethereum. This feature provides a convenient and efficient way to exchange tokens without leaving the wallet.

6. Direct dApp Interaction: Users can access and interact with a wide array of decentralized applications directly through the wallet, enhancing the user experience within the IoTeX ecosystem and all supported networks.

7. Real-Time Notifications: Stay informed with instant push notifications about transactions and wallet activities.

8. and more...

Supported Chain

ioPay Mobile allows you to easily manage your accounts on multiple Networks, including:

• Bitcoin

• Ethereum

• BNB Smart Chain

• Polygon

• Avalanche

• Fantom

• Arbitrum

• Base

• more...

IoTeX Web Wallet

Prerequisites

Rabby Wallet offers a seamless and straightforward UI to engage with your assets, thanks to its native integration of the IoTeX Blockchain. This means that users do not need to undergo any additional configuration steps to manage their IOTX tokens, track their staked IOTX balance, participate in staking, or interact with IoTeX's decentralized applications (DApps).

Randomized Delegated Proof of Stake (Roll-DPoS)

To have a fast and efficient consensus mechanism with instant block finality in the context of DePIN, the IoTeX blockchain combines the concepts of Delegated Proof of Stake (DPoS), Proctical Bizantine Fault Tolerance (PBFT) and Verifiable Random Functions (VRFs). VRF is a family of functions that can produce publicly verifiable proofs for the correctness of their random outputs. At a high level, our Roll-DPOS has four phases elect candidates, form committee, propose block and finalize block.

Elect Candidates

All nodes in the IoTeX network participate this phase in terms of voting for the committee candidates. To encourage nodes to vote, the system makes sure the delegates share forged rewards with their voters. The candidates forms a set of at least 36 delegates; this number will increase in the future to further avoid the centralization of the mining power. Once the candidates are selected, they will be  fixed in one epoch, which consists of 30 iterations.

Form Committee

In each iteration, a random committee of size 24 is selected from the candidate pool using VRF for creating blocks in the next 30 rounds. The use of VRF is important as it provides a non-interactive way to sort all delegates for proposing blocks in a fairness and security way. To this end, we use the efficient VRF as being used in Algorand.

Propose Block

In each round (which is roughly every 5 seconds), every committee node proposes a new block and broadcasts it to the network, together with the the proof. Only the block proposed by the expected committee node and has not been proposed in the same iteration is considered by other nodes, which is called a candidate block.

Finalize Block

In the same round, all other nodes use PBFT to vote for/against the candidate block. If more than 2/3 committee nodes agree on candidate block's validness, it is finalized and is appended to the blockchain by everyone in the network. After that, "propose block" and "finalize block" are executed in the next round; if the current iteration finishes, another random committee will be formed before propose block and finalize block are executed again.

The process mirrors the experience of using Ledger with any other blockchain on Rabby Wallet, which supports IoTeX out of the box.

Prerequisites

• A Ledger Hardware Wallet

• Rabbit Wallet software installed on your computer

• The latest version of the Ethereum app installed on your Ledger device (for ERC20 tokens)

Configuration Guide

Step 1: Connect Your Ledger to Your Computer

1. Connect your Ledger Hardware Wallet to your computer using the provided USB cable.

2. Enter your PIN on the Ledger device to unlock it.

Step 2: Open Rabbit Wallet

1. Launch Rabby Wallet on your computer.

2. If it's your first time using Rabby Wallet, follow the on-screen instructions to set it up. If you're an existing user, proceed to the next step.

Step 3: Connect Ledger Wallet to Rabby Wallet

1. Navigate to the settings or wallet management section within Rabby Wallet.

2. Select the option to connect a hardware wallet.

3. Choose Ledger from the list of available hardware wallets.

4. Follow the prompts to allow Rabby Wallet to access your Ledger device.

While the Native IoTeX Ledger App is fully functional, users who wish to migrate to the Ethereum Ledger App can do so as well. Simply refer to the Migrate Assets to a different wallet guide for instructions on how to move all your assets from one wallet to another.

Ledger Nano S and Ledger Nano X are hardware wallets, which are considered very secure for the storage of private keys in the blockchain world. When using a hardware wallet like Ledger Nano, your digital assets are safe even when operating on a compromised (or untrusted) PC.

IoTeX Options for Ledger Wallet:

Depending on the combination of the app on your Ledger key, and the wallet software you're utilizing, here are your available options:

1. Ethereum App on Ledger + Metamask This is the preferred setup and enables you to transfer both native IOTX and any ERC20 tokens on the IoTeX network. Additionally, it supports managing staking actions on stake.iotex.io.

2. IoTeX App on Ledger + IoTeX Hub Portal This option is available for existing users that created an account in the IoTeX Ledger App in the past. As the option above, it enables you to transfer both native IOTX and any ERC20 tokens on the IoTeX network, and supports managing staking activities on stake.iotex.io. See also #Mi

3. Ethereum App on Ledger + Ledger Live Software: Allows only for the transfer of IOTX in the form of ERC20 tokens (e.g. on the Ethereum or Polygon blockchains).

Before you begin

Please make sure that:

• Ledger Live is installed and ready to use

• You have initialized your Ledger Nano Device

• The latest Ledger firmware is installed

Features

• Native IoTeX API: The IoTeX Desktop Wallet is based on the native (non-EVM) IoTeX API.

• Supported Actions IOTX transfers & ERC20 transfers

• Smart Contract Interaction Includes an integrated user interface for interacting with smart contracts.

Getting Started

To download and install the IoTeX Desktop Wallet, click the link below:

-> Download IoTeX Desktop Desktop

→ Learn more about the IoTeX specific HD Derivation Path

Please note that the recommended way to use a Ledger Hardware Wallet with IoTeX is by using the Ethereum Ledger App and pairing it with a Web3 wallet such as Metamask or Rabby.

Install the Ethereum Ledger App on your device

The Ethereum Ledger App is required for the new IoTeX Ledger App to be installed.

• Please ensure you installed the Ethereum App on your Ledger before installing or updating to the new IoTeX App.

Install the IoTeX Ledger App on your device

Next, the IoTeX Ledger App needs to be installed on your device to allow it to generate a native IoTeX account and sign blockchain actions.

Follow the instructions below to install the IoTeX Ledger App:

1. Install and open the official Ledger Live application.

2. Connect your Ledger device to Ledger Live

Ensure you exit any opened app on your Ledger. In Ledger Live, open the "My Ledger" section, then connect and unlock your Ledger Nano device:

3. Allow Ledger Manager on your device

You may be asked to “Allow Ledger Manager” on your device: do so by clicking both buttons on your device:

4. Install the IoTeX Ledger App

In Ledger Live "Manager" section, select the “App Catalog” tab, find “IoTeX” among the apps and click the “Install” button next to it:

Follow the instructions in the Ledger Live software and on your device to complete the installation.

Connect Ledger Nano to the IoTeX Hub Portal

The IoTeX Hub Portal allows you to manage all your assets on the IoTeX blockchain, from IOTX tokens, to ERC20 to NFTs, up to your staking deposits and even DePIN devices you own.

To connect with your account on the IoTeX Ledger app follow the steps below:

1. Open https://hub.iotex.io in your browser (Google Chrome -based browsers are supported)

2. Connect and unlock your Ledger Nano device

3. On your Ledger device open the IoTeX App

4. In the IoTeX Hub Portal, click the Ledger icon in the top right of the page to connect your Ledger:

1. Select your Ledger from the browser list of connected devices:

Once you connected your Ledger wallet to the IoTeX Hub you'll be able to check your wallet address, balance as well as manage your assets and interact with Dapps available on the Hub Portal:

• Check your assets at https://hub.iotex.io/assets

• Manage your Staking IOTX at https://hub.iotex.io/staking#delegate-list

• Trade your tokens at https://hub.iotex.io/trade

Discover more on the IoTeX Hub Portal!

Prerequisites

Adding IoTeX to MetaMask

After MetaMask is installed in your browser, it comes pre-configured to connect to the Ethereum blockchain. However, you can easily add configurations for additional blockchains to use it across multiple networks, including IoTeX. You can do this either by entering the blockchain network configuration details manually or by using the links provided on the IoTeX Developer Portal.

Automatic Configuration

For a simpler and error-free setup, you can automatically configure MetaMask to add the IoTeX network:

Manual Configuration

Follow these steps to manually add the IoTeX network to MetaMask:

1. Open MetaMask: Launch the MetaMask extension or app.

2. Access Network Selection: Click on the network dropdown menu at the top of the app (defaulted to Ethereum Mainnet).

3. Add Network: Select "Add Network" or "Custom RPC" at the bottom of the network list.

1. Enter IoTeX Network Details: Input the following network configuration details:

   • Network Name: IoTeX Mainnet

   • New RPC URL: https://babel-api.mainnet.iotex.io

   • Chain ID: 4689

   • Currency Symbol: IOTX

   • Block Explorer URL: https://iotexscan.io

2. Save: Click "Save" to add the IoTeX network to your MetaMask wallet.

Using a Ledger Hardware wallet in conjunction with Metamask or a similar Ethereum-compatible software is a seamless and secure way to manage your native IOTX tokens, ERC20 tokens, or your staking on the IoTeX blockchain.

The process mirrors the experience of using Ledger with Ethereum blockchain, with a few additional steps to ensure Metamask compatibility with the IoTeX network.

Prerequisites

• Ledger Hardware Wallet

• Latest version of Ethereum app installed on your Ledger device

Configuration Guide

Step 1: Connect Your Ledger to Metamask

1. Open Metamask on your browser.

2. Connect your Ledger Hardware Wallet to your computer using the USB cable.

3. Enter your Ledger PIN to unlock the device.

Step 2: Unlock the Ethereum App on Ledger

1. Navigate through the apps on your Ledger device to find the Ethereum app.

2. Open the Ethereum app (e.g., by by pressing both buttons on the Ledger device simultaneously).

Step 3: Configure Metamask for the IoTeX Blockchain

Step 4: Connect Metamask to the IoTeX Blockchain

With the IoTeX network added to your wallet, you can now:

1. Select the IoTeX network from the network dropdown menu in Metamask.

2. Perform transactions as usual. Your transactions will now be executed on the IoTeX blockchain.

In the world of blockchain and cryptocurrencies, keeping track of your digital assets is crucial. Wallets like Metamask and ioPay not only display your native token balance on the selected blockchain, but also enable you to monitor other assets, like "ERC20 tokens." or "NFT Tokens".

This guide will walk you through the process of adding ERC20 tokens to your wallet, ensuring that you have complete visibility over your digital portfolio.

Adding ERC20 Tokens to Metamask

1. Accessing the Token Section:

   • Open Metamask and navigate to the "Tokens" tab.

   • At the bottom of this tab, you'll find the "+ Import Token" option. Click on it to proceed.

2. Locating the Token Address:

   • To add a specific token, such as CIOTX, first locate its contract address. A reliable way to do this is by using a blockchain explorer like etherscan.io.

   • Go to etherscan.io and use the search bar to enter "CIOTX".

   • Select "CIOTX (Crosschain IOTX)" from the search results to view its dedicated page.

3. Importing the Token:

   • On the CIOTX token page in Etherscan, you have two options:

     • Manually copy the contract address and paste it into the Metamask token import field.

     • Use the "More" dropdown menu and select "Add Token to Metamask". This automates the process, adding that token to your Metamask token balances.

Adding ERC20 Tokens to ioPay

1. Selecting the Token:

   • Open your ioPay wallet.

   • Look for the (+) button in the tokens panel below the native balance section.

   • Tap the (+) button and select the tokens that you want to show in the list.

HD derivation path means hierarchical deterministic wallet derivation path. It is a way to derive multiple accounts from the same mnemonic seed.

IoTeX uses m/44'/304 as its HD path. You can view all HD paths for all coins here: https://github.com/satoshilabs/slips/blob/master/slip-0044.md

If you use mnemonic seed and HD to derive wallets, m/44'/304'/0'/0 is the 0-th wallet for IoTeX Wallet and m/44'/304'/0'/1 is the 1st wallet.

A full HD path is usually like this

m / purpose' / coin_type' / account' / change / address_index

Using this HD path, you can manually derive your private keys from mnemonic seed. A tool you can do that is https://iancoleman.io/bip39/.

A tutorial of using the tool with IoTeX wallet is https://community.iotex.io/t/migrate-your-iotex-wallet-from-trust-wallet-to-iopay/2352

Sometimes, it may be necessary to abandon a wallet account, such as when you suspect that your current wallet has been compromised or when rotating addresses for security purposes. In these situations, it’s crucial to ensure that all your assets are successfully migrated to your new wallet.

1. Identify the destination wallet

Identify the new wallet you want to transfer your assets to. If it's a hardware wallet, connect it to Metamask and identify the wallet address.

2. Transfer your Tokens

• Transfer ERC20 Tokens

• Transfer all your NFT Tokens, they'll include:

  • Staking IOTX as NFT Buckets

  • DePIN Devices that you own

  • IoTeX Name Service (INS) domain names

  • Any other type of NFT

3. Transfer your Staking

4. Transfer your DeFi assets

Liquidity pools

Other DeFi protocols may also work with the same principle: please do your research and identify the correct steps to migrate your liquidity to a different address.

Liquid Staking

Other similar liquid staking protocols you may have used may also work with the same principle: please do your research and identify the correct steps to migrate your liquidity to a different address.

5. Other Protocol Assets

Other DeFi protocols like borrowing/lending, or gaming apps, or any othe Dapp might require you to withdraw your deposits in order to transfer them to a different wallet. Please do your research and identify the correct steps to migrate your assets from these protocols to a different address.

6. Transfer your Delegate Profile

7. Transfer your IOTX tokens

As a last step, once you transferred all your other assets, you can transfer all your IOTX tokens to the new address.

If you are an investors interested in purchasing the IoTeX (IOTX) token, in this document we aim to provide you with a clear and detailed overview of all available options for acquiring IOTX. Here, you'll find insights about each option, ensuring you can make an informed decision.

Buy on Centralised Exchanges (CEXs)

IOTX, the native token of the IoTeX Blockchain, is a cryptocurrency token that can be bought on various cryptocurrency exchanges. It be found on exchanges such as:

Buy on decentralized Exchanges (DEXs)

In addition to centralised exchanges, decentralised Exchanges are also a popular choice for trading cryptocurrencies like IoTeX (IOTX). You may find the IOTX token on DEXs that operate on the networks compatible with IoTeX. Some popular DEX options include:

Buying with a Credit Card

Learn More

What is IoTeX Staking

A core part of decentralized governance in the IoTeX Network is staking, where token holders deposit ("stake") IOTX in the IoTeX blockchain to facilitate network operations, consensus, and governance. By staking, token holders earn rewards, contributing to an attractive passive income stream. Additionally, staking strengthens the IoTeX network security and stability, as it supports the decentralization of block production.

By participating in staking, you also gain a voice in IoTeX governance, allowing you to influence key decisions and the future direction of IoTeX. Overall, staking in IoTeX is not just a financial endeavor; it's an opportunity to be an integral part of a growing blockchain ecosystem.

↗ Explore all IoTeX Delegates

↗ Go to the Staking Guide

Native staking happens by interacting with a dedicated, protocol-level staking mechanism, which means it operates at the core layer of the blockchain without the need for additional smart contracts.

Why Choose Native Staking?

This option offers complete flexibility concerning the amount you choose to stake, the lock time, and the Stake-Lock options. Additionally, it allows you to increase the deposit of existing stakes at a later time, and it incurs a lower fee for any staking action

Staking as NFT introduces Non-Fungible Tokens (NFTs) to represent your staking deposits. In this mechanism, when you stake your tokens, you receive an NFT that signifies ownership and details of the staked amount and lock options.

Why Choose Staking as NFT?

Staking as NFT offers several benefits over native staking:

1. It enables participation in Liquid Staking or other DeFi applications and unlocks the potential to earn additional passive income.

Convert Native Staking to NFT

What are IoTeX Improvement Proposals

An IoTeX Improvement Proposal (or "IIP") is a design document providing information to the IoTeX community, or describing a new feature for IoTeX, its processes, or its environment.

IIPs are intended to be the primary mechanisms for proposing new features, collecting community input on an issue, and documenting the design decisions that have been implemented in the IoTeX ecosystem.

Because IIPs are maintained as text files in a versioned repository, their revision history also represents the historical record of the feature proposal itself.

Submitting an IIP

Anyone can submit an IIP: A proposal should provide a concise technical specification and a rationale for the new feature. The IIP author is responsible for building consensus within the community and documenting dissenting opinions.

You can read more about IoTeX IIPs, browse past proposals and submit a new one by sending a pull request to the GitHub repository:

↗ Browse and Submit Improvement Proposals

The Governance Portal

The IoTeX Governance Portal is powered by Snapshot, a no-fee governance tool based on IPFS that makes it simple for decentralized networks to run open votes, polls, and referendums. Follow the link below to browse through or vote on existing proposals, as well as create a new one.

↗ IoTeX Governance Portal

The Governance Forum

Check out our governance forum, if you'd like to meet the community and discuss new proposals:

↗ Governance Proposals on the IoTeX Forum

Feel free to checkout this blog article if you'd like to learn more about decentralized governance in the IoTeX ecosystem.

Configure a Wallet

To begin staking IOTX, you will need a compatible wallet. Use ioPay if you prefer to manage your stakes on a mobile phone, or MetaMask for managing your stake from a desktop.

Acquire IOTX Tokens

To start, purchase IOTX tokens from a cryptocurrency exchange. Then, transfer them to your chosen wallet. For detailed guidance on funding your wallet, follow this link:

IoTeX Staking Portal

This can be done directly through the ioPay app's in-built browser or via a Metamask-enabled web browser. Once you reach the staking portal, you will be prompted to choose between two staking methods: 'Native Staking' or 'Stake as NFT'.

In the first screen of the Staking process, you can browse the list of IoTeX Validators and choose one to delegate your IOTX tokens to. At any time you will be able to redirect your votes to a different delegate without the need to unstake your IOTX.

Choose a Delegate

Delegates all have unique reward plans to cover costs, donate to funds, and re-distribute rewards to their voters. Think of it as Delegates charging a service fee to stake your token.

Create a diverse voting portfolio that is representative of your vision for the future of IoTeX.

• Community: If you want IoTeX to prioritize community, vote for an IoTeX Ambassador!

• DApps: If you want to prioritize dApp development, vote for a Dev Group!

• Enterprise: If you want enterprise to be a priority, vote for a delegate founded by an investor.

Decide the amount of IOTX

When selecting the amount of IOTX to stake, consider your investment goals and risk tolerance. Here are a few tips:

• Minimum Stake: Ensure you stake at least 100 IOTX, as this is the minimum requirement.

• Transaction Fees: Do not try to stake your entire balance: leave some IOTX in your wallet for transaction fees.

Understand the Staking Duration (Lock-up Period)

The staking duration setting allows you to specify how long you wish to lock your IOTX tokens for staking. Here are some key points to consider when selecting a duration:

1. Short-term vs Long-term: Shorter durations provide more flexibility but typically offer lower rewards. Longer durations can offer higher rewards but keep in mind that the extra rewards decrease exponentially so it many not be worth locking for very long periods.

4. Goal Alignment: Choose a duration that aligns with your investment goals and liquidity needs.

Understand Stake-Lock

StakeLock is a feature that, when enabled, prevents the countdown of your staking duration from progressing. This means that your IOTX tokens remain locked for the specified duration, and the lock period does not decrease until you disable StakeLock. Once disabled, the countdown will begin, and you'll need to wait for the lock period to expire before you can unstake your tokens. It's useful when your staking duration is short and you don't want to keep renewing it manually each time it expires.

Earn Rewards

When staking for an Hermes Delegate, you can always check your reward distribution transactions on the Hermes website:

Participate in Governance

As a staker, you may have the right to participate in IoTeX governance decisions, contributing to the future direction of the network.

Unstaking

Unstaking IOTX involves a few key steps:

1. Disable StakeLock: If StakeLock is enabled, you first need to disable it. This will start the countdown of your staking duration, allowing the lock period to expire.

2. Wait for Lock Period: Wait for the lock period to count down to zero.

3. Initiate Unstaking: After the lock period expires, you can initiate the unstaking process.

4. Cooldown Period: Once you start unstaking, there is a mandatory 3-day cooldown period.

5. Withdraw: After the cooldown period, you can withdraw your IOTX back to your wallet.

Introduction

Sending IOTX Tokens

Withdrawing from an Exchange to a Personal Wallet

1. Log into your exchange account

2. Navigate to the withdrawal section.

3. Select IOTX as the token to withdraw.

4. Enter the address of your personal wallet.

5. If required, select IoTeX as the destination network

Depositing from Personal Wallet to Exchange

1. Log into your exchange account and obtain the deposit address for IOTX.

2. Make sure your exchange accepts IOTX deposits on the IoTeX Network for that deposit address.

3. Initiating the Transfer:

   • Open your personal wallet (Metamask, ioPay, etc.).

   • Select your IoTeX wallet and click "Send".

   • Enter the exchange's deposit address as the recipient.

   • Confirm the transaction details and complete the transfer.

Receiving IOTX Tokens

1. Locate and copy your wallet's address.

2. Provide your wallet's address to the sender.

3. Confirm that the sender uses the correct token and blockchain network.

Special Considerations for Coinbase Users

Conclusion

Transferring IOTX tokens can be a seamless process with the right information. Whether you are moving tokens from an exchange to a personal wallet or vice versa, always ensure you are using compatible wallets and networks. For specific needs like staking, the iotube dApp provides a decentralized solution to swap your IOTX tokens on ethereum to the native IoTeX blockchain.

This specification provides a comprehensive overview of the ioID system, detailing its methods, workflows, and security considerations for effective deployment in DePIN applications.

On-Device DID Generation

DePIN devices and network nodes can generate a DID and the corresponding DID document by means of SDKs, CLIs or other tools.

ioID Registration and Binding

A DePIN device owners and node operators can onboard their devices via a the following steps

1. Generate/obtain the device's DID and DID document (e.g. use a CLI for nodes, or obtain it via the serial port for embedded devices).

2. Store the DID document on a selected storage layer (e.g. AWS S3, IPFS, etc...)

3. Invoke the device registry contract with the device's DID, DID document hash, and URI.

Upon successful onboarding, an ioID NFT representing on-chain ownership of the device is minted in the owner's blockchain wallet.

Secure Machine-to-Machine Interactions

Once registered on-chain, a DePIN entities can authenticate each other and establish secure off-chain communications with other entities in the network using DID-based protocols.

ioID Specification

did:io Method

DIDs in ioID conform to the Generic DID Scheme described in the DID specification. They follow the format did:io:io-specific-idstring, where io-specific-idstring is generated by:

1. Creating a private/public key pair over the elliptic curve secp256k1.

2. Converting the public key to an Ethereum address.

Example of an ioID DID:

did:io:0x5576E95935366Ebd2637D9171E4C92e60598be10

DID Document for a DePIN Device

A sample DID document:

{
    "@context": [
        "https://www.w3.org/ns/did/v1",
        "https://w3id.org/security/suites/ed25519-2018/v1"
    ],
    "id": "did:io:0x123456789abcdefghi",
    "verificationMethod": [{
        "type": "Ed25519VerificationKey2018",
        "id": "did:io:0x123456789abcdefghi#key-1",
        "publicKeyBase58": "......"
    }],
    "authentication": [
        "did:io:0x123456789abcdefghi#key-1"
    ],
    "service": [{
        "id": "did:io:0x123456789abcdefghi#mqtt",
        "type": "MqttEndpoint",
        "serviceEndpoint": "broker.example.mqtt.com"
    },
    {
        "id": "did:io:0x123456789abcdefghi#http",
        "type": "HttpEndpoint",
        "serviceEndpoint": "example.com"
    }]
}

DePIN Node Onboarding

To onboard a server within a specific layer of a DePIN modular stack (e.g., a sequencer node), a node operator needs to:

1. Log into the DePIN node using their server credentials.

2. Generate a DID and DID document (e.g. using a CLI)

3. Upload the DID document to a storage provider and take note of the URI.

4. Using the operator's blockchain account, invoke the ioID on-chain registry to perform a Device Registration for the node, with the node DID, DID document hash, and URI.

5. The ioID device registry is updated with the new information and a "device NFT" is minted to the node operator's blockchain address.

DePIN Device Onboarding

To onboard a device (e.g., a 5G Cellular Antenna) that belongs to a certain DePIN project, a device owner needs to:

1. Retrieve the device's DID and DID document (e.g. via a usb tool paired with an embedded SDK installed on the device).

2. Upload the DID document to a storage provider and get the URI.

3. Register the device with its DID, DID document hash, and URI.

4. Using the owner's blockchain account, invoke the ioID on-chain registry to perform a Device Registration with the device DID, DID document hash, and URI.

5. The ioID device registry is updated with the new information and a "device NFT" is minted to the owner's blockchain address.

DePIN Node Discovery

Once DePIN nodes and devices are registered in the ioID device registry, a DePIN device will rely on a bootstrapping node to discover the service endpoint(s) of a DePIN application.

1. A DePIN device sends a project descriptor (e.g., a project ID) to a bootstrapping node.

2. The bootstrapping node uses the project descriptor to retrieve the project configuration URL from the project registry on the blockchain.

3. The bootstrapping node uses the URI to read the project configuration file from the storage.

4. The bootstrapping node parses the project configuration file to obtain the service endpoint(s) of the DePIN project.

5. The bootstrapping node returns the service endpoint(s) to the device.

6. The device stores the service endpoint(s) in its flash.

Such a DePIN node discovery protocol might need to run periodically to handle potential changes in DePIN nodes within the network.

DePIN Machine-to-Machine Communication

With the service endpoint available, a DePIN device can interact with a DePIN node in a secure manner. To this end, a number of DID-based sub-protocols need to be performed.

4.1 Mutual Authentication

A DID-based mutual authentication protocol enables secure communication between devices and nodes.

4.2 VC Issuance

Optionally, DePIN devices receive a VC from an issuer to exchange for a W3bstream access token.

4.3 VC Presentation

Optionally, Devices present the VC to obtain an access token.

4.4 Data Upload

Devices upload data to a node via a DID-based encrypted channel.

This document will guide you through the prerequisites and setup required to start using ioID on the IoTeX testnet. By following these steps, you'll be able to configure your development environment and begin interacting with the ioID Module infrastructure.

Prerequisites

curl https://raw.githubusercontent.com/iotexproject/iotex-core/master/install-cli.sh | sh

The first step for any DePIN project intending to integrate with ioID identities is to register the project on the IoTeX blockchain to obtain a Project ID.

Here’s how to register your project:

Using the IoTeX CLI (ioctl)

ioctl ioid register "My DePIN Project"

Registerd ioID project id is 41

Once the transaction is completed you will receive a Project NFT with a certain Token ID, representing your DePIN Project ID on the IoTeX blockchain.

Contract Call

Contract: ProjectRegistry

Function Call: register() external payable returns (uint256)

Example:

let tx = await projectRegistry.registerProject();

This guide will walk you through the process of integrating the IoTeX token ($IOTX) on your exchange. Since IoTeX is fully Ethereum-compatible, most integration steps will resemble those of any EVM blockchain. Below are the detailed steps, requirements, and resources necessary for seamless integration.

If you require further assistance, please don’t hesitate to reach out to our support team.

1. Overview of IoTeX and $IOTX Token

IoTeX is a leading decentralized layer-1 blockchain, focused on enabling decentralized physical infrastructure networks (DePIN). The IoTeX native token, $IOTX, powers the IoTeX ecosystem by facilitating blockchain transactions, staking, governance, as well as data computing and identities management for DePINs.

• Token Name: IoTeX

• Ticker Symbol: IOTX

• Blockchain: IoTeX Mainnet

• Standard: Native Protocol Token

2. Blockchain Basics and Compatibility

IoTeX Mainnet Information

• Network Name: IoTeX Mainnet

• Chain ID: 4689

• Symbol: IOTX

• RPC URL: https://babel-api.mainnet.iotex.io (see more endpoints)

• Explorer URL: https://iotexscan.io

IoTeX Testnet Information

• Network Name: IoTeX Testnet

• Chain ID: 4690

• Symbol: IOTX

• RPC URL: https://babel-api.testnet.iotex.io (see more endpoints)

• Explorer URL: https://testnet.iotexscan.io

3. Wallet Integration

To support deposits and withdrawals for $IOTX, exchanges need to implement wallet integration. As IoTeX is fully Ethereum-compatible, most Ethereum-compatible wallets (such as MetaMask, Trust Wallet, and hardware wallets like Ledger) will work seamlessly for managing $IOTX tokens.

To integrate $IOTX into your platform’s wallet

• Use Ethereum-compatible libraries like Web3.js or Ethers.js to interact with the IoTeX blockchain.

• Set the correct RPC endpoint to ensure interaction with the IoTeX blockchain.

Example:

const Web3 = require('web3');
const web3 = new Web3('https://babel-api.mainnet.iotex.io');

// Query the balance of an address
web3.eth.getBalance('0x4d8a5c5b52f45fcfd2ce7eea58390b214909ef24').then(console.log);

4. Node Setup and API Endpoints

Exchanges can either use public RPC endpoints for convenience, or set up their own IoTeX nodes for higher reliability and security.

Full Node Setup

If you prefer to run your own full node, you can follow the IoTeX full node setup guide.

Public RPC Endpoints

• IoTeX Mainnet: https://babel-api.mainnet.iotex.io (see more endpoints)

• IoTeX Testnet: https://babel-api.testnet.iotex.io (see more endpoints)

5. Deposits and Withdrawal

Deposit Flow

Withdrawal Flow

To integrate $IOTX withdrawals:

Example transaction code (using Web3.js):

const Tx = require('ethereumjs-tx').Transaction;
const privateKey = Buffer.from('your_private_key', 'hex');

const txData = {
  nonce: web3.utils.toHex(txCount),
  gasLimit: web3.utils.toHex(21000),
  gasPrice: web3.utils.toHex(web3.utils.toWei('10', 'gwei')),
  to: 'recipient_address',
  value: web3.utils.toHex(web3.utils.toWei('1', 'ether')),
  chainId: 4689, // IoTeX Mainnet Chain ID
};

const tx = new Tx(txData);
tx.sign(privateKey);

const serializedTx = tx.serialize();
const rawTx = '0x' + serializedTx.toString('hex');
web3.eth.sendSignedTransaction(rawTx)
  .on('receipt', console.log);

6. Trading and Smart Contract Integration

Smart Contract Compatibility

Since IoTeX is EVM-compatible, it supports all Ethereum smart contracts, including those written in Solidity. If your exchange supports Ethereum-based trading, you can use the same mechanisms to enable $IOTX trading.

7. Listing $IOTX

To list $IOTX, use the following token details:

• Symbol: IOTX

• Decimals: 18

8. Security Considerations

• Private Key Management: Ensure private keys are stored securely (e.g., using HSMs, cold storage, or other secure key management systems).

• Multi-Sig Wallets: Implement multi-signature wallets for withdrawals to minimize the risk of unauthorized transactions.

• Monitoring and Alerts: Set up monitoring for large transactions, unusual activity, and sudden spikes in gas fees.

8. Support and Contact

For any issues or further questions regarding the $IOTX integration, feel free to contact the IoTeX team:

• Email: developers@iotex.io

• Official Documentation: https://docs.iotex.io

• Developer Resources: IoTeX Developer Portal

As a general-purpose identity system, ioID could be utilized in different layers of the DePIN modular infrastructure, as shown in the figure below:

The ioID Module is IoTeX's comprehensive decentralized identity solution based on the IoTeX blockchain and the ioID specification. It is an essential module for developers aiming to integrate decentralized identity verification into their DePIN applications.

The IoTeX ioID module comprises four main components:

1. ioID Smart Contracts

2. DID-based secure communication protocol

3. Client-side tools and SDK

4. DID Resolver Service

Together, these components facilitate the robust management of both on-chain and off-chain identities for smart devices, users, and nodes within a decentralized network.

High-Level Architecture Overview

This document provides a high-level overview of the architecture of the ioID module and it's components.

ioID Contracts

The ioID smart contracts provide a secure and decentralized framework for managing the identities of DePIN projects, users, devices, and nodes based on the IoTeX Blockchain.

-> Learn more about ioID Contracts

Secure DID-based communication

Unlike traditional centralized IoT clouds that rely on secret certificates, ioConnect enables devices to use Decentralized Identifiers (DIDs) for establishing secure communication channels.

-> Learn more about ioID Contracts

Client tools and SDK

Several client tools are provided to interact with ioID both for DEPIN Builders, device manufacturers, and device owners. ioConnect SDK includes a dedicated API to implement the secure DID communication between devices and servers. The IoTeX CLI ioctl facilitates interactions for DEPIN Builders, while wallet.iotex.io implements the device owner experience.

-> Learn more about ioConnect SDK for ioID

-> Learn more about ioctl for ioID

-> Learn more about wallet.iotex.io for device owners

DID Resolver Service

The DID Resolver is an essential service for enabling DID-based communications within a DePIN project. It serves the critical function of resolving Decentralized Identifiers (DIDs) to their corresponding DID Documents, which contain the necessary metadata and public keys required for secure interactions.

-> Learn more about the DID Resolver

The ioID suite of smart contracts provides a robust framework for decentralized identity management on the IoTeX blockchain. These contracts collectively provide a robust framework for identity management and interaction within the IoTeX ecosystem.

Here’s a brief overview of each contract and its main functions.

DePIN Projects Registry

ProjectRegistry.sol

The DePIN Project Registry is an NFT-based registry that manages all DePIN projects. It ensures that each project is uniquely identified and authenticated within the network.

ioID NFT

ioID.sol

The ioID NFT contract is an essential part of the ioID framework for decentralized identity management on the IoTeX blockchain. It's directly managed by the Project Registry and is in charge for creating and assigning unique ioID tokens for devices. This involves linking devices to project IDs and owners, and generating associated wallet addresses according to the ERC6551 standard.

ioID Store

ioIDStore.sol

The ioID Store is responsible for managing the application and activation of ioID across all projects. It handles the lifecycle of identity management applications, ensuring that identities are correctly set up and maintained.

ioID Registry

ioIDRegistry.sol

The ioID Registry contract is used for registering devices on-chain and activating their ioID. It also serves as a DID resolver, providing a reliable means for verifying device identities across different projects.

After binding a Device NFT contract to a DePIN project and requesting a specific number of ioIDs for the project, physical devices can be registered in the ioIDRegistry contract, effectively "activating" the ioID.

This activation process must be carried out by the device owner and involves minting an ioID NFT to the device owner's account. During the minting process the ioID is associated with a specific Device NFT token, where the device's DID (Decentralized Identifier) serves as the token's ID.

Contract Call

Contract: ioIDRegistry

Function Call: function register(address deviceContract, uint256 tokenId, address device, bytes32 hash, string calldata uri, uint8 v, bytes32 r, bytes32 s ) external

Example:

Please refer to this code to clarify the meaning of the method call arguments:

You can check the project status and details using the ioctl command below:

Output Explanation:

• projectContarctAddress represents the NFT token contract address for registered projects (add it to your wallet app to check your project IDs and manage ownership).

• deviceNFT represents the Device NFT contract address you have set for your depin project

• appliedIoIDs: is the number of ioIDs you have applied, consequently the number of devices that can be activated for your project

• activatedIoIDs: is the number of ioIDs activated and assigned to registered devices

The DePIN Verification Problem

Decentralized Physical Infrastructure Networks (DePIN) face unique challenges in verifying and processing physical device data while ensuring trust. On-device verification methods, such as using trusted execution environments in conjunction with blockchain-based identity management, can help solve data provenance verification. However, trusted processing of data is often overlooked by DePIN builders due to the lack of dedicated off-chain verifiable compute protocols suitable for DePINs.

As a result, the core logic of DePIN projects, specifically the logic that triggers on-chain token economies, is not verifiable by anyone and thus not trusted.

W3bstream: Off-Chain Verification for DePIN

W3bstream is an off-chain verifiable compute protocol designed by IoTeX to address the verification challenges in DePIN. Based on multi-prover technology, W3bstream ensures flexible and scalable verification of off-chain computations, mitigating risks like self-dealing, lazy providers, and malicious responses.

Using the IoTeX CLI (ioctl)

After the transaction, the requested number of ioIDs will be reserved to your Project ID.

Contract Call

Contract: ioIDStore

Function Call: applyIoIDs(uint256 _projectId, uint256 _amount) external payable

Example:

After registering a DePIN project, the next step is to set the Device NFT contract for that project. This contract must be set before any user attempts to register a device ioID for your project.

Your Device NFT contract must be linked to your Project ID and only users who own a valid device NFT for a DePIN project are entitled to register a new ioID identity for a physical device for that project and bind it to their blockchain wallet.

While the Device token contract could be a plain NFT721, below is an example for a typical customization that can be used as a Device NFT by a DePIN project.

Bind the Device NFT using IoTeX CLI (ioctl)

Contract Call

Contarct: ioIDStore

Function Call: setDeviceContract(uint256 _projectId, address _contract) external

Example:

This section is dedicated to the process of registering identities within the IoTeX ecosystem, particularly for DePIN (Decentralized Physical Infrastructure Networks) projects and devices.

Register a DePIN Project

To initiate a DePIN project and register device identities, you must first register your project with the IoTeX network. This process involves:

• Providing a project name.

• Referencing your "Device NFT" contract.

• Receiving a "Project ID" in the form of an NFT.

Register Devices

For devices to interact with the IoTeX blockchain, they must be assigned to a DePIN project, registered, and verified. This ensures that all devices and their data are verifiable across all layers of the DePIN architecture. The process involves:

• Requesting a number of ioIDs for a DePIN project.

• Activating these ioIDs through a device registration and owner binding process.

W3bstream is a blockchain-orchestrated protocol, which aims to harness the power of a global-scale network of provers to execute the logic of emerging DePIN applications. In a nutshell, W3bstream is a decentralized off-chain computing network that is composed of heterogeneous nodes performing verifiable computations, as illustrated in the figure below:

The proofs generated by W3bstream nodes are verified by dedicated verifier contracts on-chain and then consumed by DePIN Dapps. Depending on each DePIN project configuration, W3bstream provers are run by the community and are rewarded for providing their computational resources to process blocks of data for DePIN projects.

Types of W3bstream Provers

Several techniques have been developed in the past to attest integrity of data processing and allow public verifiability, including zero-knowledge proofs (ZKPs), trusted execution environments (TEEs), and secure multi-party computations (SMPCs).

Zero-Knowledge Proof (ZKP) Provers

W3bstream will gradually support the leading zkVM/zkWASM projects (e.g., Risc0, Succinct SP1, Nexus, etc.) as well as popular DSLs (e.g., Circom, Halo2, ZoKrates, Noir, Cairo, etc.) for building customized zk circuits.

Halo2: The Halo2 ZK prover executes Halo2 circuits.

Risc Zero: The Risc Zero prover executes code in a Risc Zero zkVM.

zkWASM: The zkWASM prover executes WASM modules in a zkWASM VM.

Trusted Execution Environment (TEE) Provers

The TEE prover facilitates DePIN developers to utilize state-of-the-art confidential computing technology for performing privacy-preserving off-chain computing. W3bstream will gradually support the development flow of the leading TEE-based hardware platforms such as Intel SGX, Intel TDX, AMD SEV, AMD SEV-SNP, AWS Nitro, Arm CCA, etc.

Secure Multi-Party Computation (SMPC) Prover

An SMPC prover can be realized by following the general development flow of a specific SMPC protocol (e.g., SPDZ). However, efficiently achieving public verifiability is still an ongoing research direction. The SMPC prover allows DePIN developers to employ several nodes in the network to conduct collaborative privacy-preserving off-chain computing in a distributed manner.

Bring Your Own Prover (BYOP)

The BYOP type of prover offers great flexibility for DePIN developers deploying optimized provers that are tailored to specific DePIN projects or exploring new efficient verifiable computation techniques in the context of DePIN.

Overview

The default DePIN configuration provided with the W3bstream release offers the essential stack needed to stream data messages from a DePIN device and process them in W3bstream, generating a validity proof that can be written and verified on-chain.

The Sequencer service provided in this configuration is a reference implementation for a DePIN data sequencer, supporting both ioID and W3bstream. While suitable for development purposes, this demo service however is best used as a reference or starting point for your own sequencer implementation.

Below, we explore some configuration options for the data sequencer that can be useful during development of your W3bstream project.

Data Aggregation

In a DePIN application, the data sequencer, whether centralized or decentralized, typically authenticates devices, validates, filters, and sorts their data. Each data message processed by the Sequencer is usually appended to a W3bstream Task until the expected "aggregation value" is reached. In the provided demo sequencer, the default aggregation value is set to 1, meaning each message sent to the sequencer is immediately wrapped in a W3bstream Task, stored in the Postgres DB, and fetched by W3bstream for processing.

You can change the data aggregation amount in the Sequencer configuration of docker-compose.yaml like shown below:

# ...
sequencer:
  # ...
  command: 
    - "coordinatorAddress"
    - "coordinator:9001"
    - "databaseDSN"
    - "postgres://test_user:test_passwd@postgres:5432/test?sslmode=disable"
    - "aggregationAmount"
    - "10" # Increase this value to aggregate more messages in a W3bstream Task

Run W3bstream Locally

The W3bstream GitHub repository includes a developer-friendly setup to facilitate DePIN builders building W3bstream provers for their verifiable off-chain computing.

The setup includes the following services:

• A reference implementation for a DePIN data sequencer

• A Postgres DB as the Data Availability service

• A W3bstream coordinator and a prover as a single-node W3bstream configuration

Download demo provers

Let's start by first downloading some ready-made W3bstream project files that implement a basic "range prover" using different ZK technologies:

mkdir w3bstream && cd w3bstream
mkdir -p test/project

# Fetch the latest W3bstream release number
export RELEASE=$(curl --silent "https://api.github.com/repos/iotexproject/w3bstream/releases/latest" | jq -r .tag_name)

# Download the Risc Zero demo prover
curl -L -o test/project/10000 https://raw.githubusercontent.com/iotexproject/w3bstream/$RELEASE/test/project/10000
# Download the Halo2 demo prover
curl -L -o test/project/10001 https://raw.githubusercontent.com/iotexproject/w3bstream/$RELEASE/test/project/10001
# Download the zkWASM demo prover
curl -L -o test/project/10002 https://raw.githubusercontent.com/iotexproject/w3bstream/$RELEASE/test/project/10002

With the demo projects in place, we can proceed by fetching the docker-compose.yaml file and running W3bstream locally:

Start the W3bstream Dev Setup

# Fetch the latest docker-compose.yaml
curl https://raw.githubusercontent.com/iotexproject/w3bstream/$RELEASE/docker-compose.yaml > docker-compose.yaml

# Run the configuration
docker compose up -d 

# Log the sequencer, coordinator, and prover
docker compose logs -f sequencer coordinator prover

Test the setup

Now that we have a basic DePIN stack running, including a data sequencer, a data availability service, and a minimal W3bstream network, let's test the setup by sending a data message targeting one of the three demo projects.

In a new terminal, type the following command to send a data message to the sequencer targeting one of the example projects:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "projectID": 10000,
    "projectVersion": "0.1",
    "data": "{\"private_input\":\"14\", \"public_input\":\"3,34\", \"receipt_type\":\"Snark\"}"
  }' \
  localhost:9000/message

w3bstream-sequencer    | 200 |   42.968375ms |    192.168.65.1 | POST     "/message"
w3bstream-coordinator  | msg="dispatched a task" project_id=10000 task_id=27
w3bstream-prover       | msg="get a new task" project_id=10000 task_id=27
w3bstream-prover       | msg="acquire vm instance success" vm_type=risc0
w3bstream-coordinator  | msg=stdout proof="{\"Snark\":{\"snark\":{\"a\":[[13,51,248,201,29,8,75,18,133,175,224,43,153,182,18,76,116,108,72,18,95,83,150,181,238,149,60,82,162,242,202,144],[12,175,37,4,26,25,67,209,3,240,63,121,58,84,186,151,17,115,150,37,124,105,91,165,42,121,183,217,131,16,203,210]],\"b\":[[[34,33,95,242,250,124,78,175,229,146,174,12,184,28,240,133,228,90,88,209,196,2,235,47,121,225,159,104,237,152,210,182],[29,175,79,126,19,96,201,151,4,181,4,238,150,139,165,172,133,237,156,92,223,86,25,143,46,208,51,188,171,20,76,62]],[[12,87,52,171,230,179,182,56,194,172,191,150,227,40,164,204,200,238,82,222,83,112,138,149,134,56,14,178,165,237,81,137],[44,149,186,174,109,232,219,73,234,193,62,238,165,249,132,201,206,217,68,57,151,45,105,165,154,60,111,134,31,62,25,253]]],\"c\":[[7,96,9,209,79,91,0,232,113,87,32,163,146,113,134,97,216,33,194,78,150,160,222,150,123,88,202,228,236,171,207,84],[24,35,80,218,45,162,14,142,79,158,53,50,121,190,131,213,93,167,137,57,199,76,147,158,230,19,101,211,85,123,193,94]]},\"post_state_digest\":[163,172,194,113,23,65,137,150,52,11,132,229,169,15,62,244,196,157,34,199,158,68,170,216,34,236,156,49,62,30,184,226],\"journal\":[81,0,0,0,73,32,107,110,111,119,32,121,111,117,114,32,112,114,105,118,97,116,101,32,105,110,112,117,116,32,105,115,32,103,114,101,97,116,101,114,32,116,104,97,110,32,51,32,97,110,100,32,108,101,115,115,32,116,104,97,110,32,51,52,44,32,97,110,100,32,73,32,99,97,110,32,112,114,111,118,101,32,105,116,33,0,0,0]}}"
w3bstream-coordinator  | time=2024-06-25T17:14:58.088Z level=INFO msg="task finished" project_id=10000 task_id=27

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "projectID": 10001,
    "projectVersion": "0.1",
    "data": "{\"private_a\":3, \"private_b\":4 }"
  }' \
  localhost:9000/message
  

w3bstream-sequencer    | 200 |   15.621291ms |    192.168.65.1 | POST     "/message"
w3bstream-coordinator  | msg="dispatched a task" project_id=10001 task_id=29
w3bstream-prover       | msg="get a new task" project_id=10001 task_id=29
w3bstream-prover       | msg="acquire vm instance success" vm_type=halo2
w3bstream-coordinator  | msg=stdout proof=2c24ca70a6aef9655ed0626c4e6821abfee6a1b7569e2bc536f219d44b62cace22d31b906c7bf61a52dbb9a6cccb02b5e78d77ced622cf1477f276d25857ac09153bb58c1892b41aa7e99a5e2da023901a43e95785c52922db0983ea112dd30715a5f5ec4b609c30d7e410a9fd6fec23317f15a8ca30b2997c9cdddf207f0aeb162dd6c40b1dc440e9b34d9324f1c93c30cf72a47c043b46f27d26814908a58e0ef7b939e722a808bd6ecee2022eebd66fc2864b450dcf0b38e187d26c65229816db198b048b99a828d57b80306018816a0e257dd9d1d4c8ce1a25be66d9fa7d28d08acbdb02f7f929a9a7f10a7490b2701930d026429bd4387c03f707c3a712193c0381c41a744eec42ecdbb3d8a1ab04d2a5e03509cc59d274c0e7d1f7785f0568740ba807d7f6aef522fa01e393319ef3010bcb01d17b906ed0a1c2bb18072059efea92c5dc6523e5886ba334e8b734a085d4d800ea1c741bb62b661828480d2e90d65020c3a5e47a31d815e68a8ce5d2a0caf350f36b42587436fd16e5aa2070228b51ac58c197c16db4e9a6a8e2f41d76631c6e8268ccb1ac6d4c23c8b22eaf75f8a8a36a48561e342258f21a50fb1e2dc4519ba22de73d19a57f7129df0c5386fb9f6385d81e091ec0f65c6f5d74c02761e3d395bfab792afb5b5f30c22c4d10a854cd94c05f18fb56d34fb8c6abb68d7145165029d6a856b5518b58e51f7578055cfcd23315a3dff19938c75be23259347fd53447a0932981ee9732e912feed059f920689b9b289c77bf65b60a33b178f4787401b90da58d629f34c0017d2764fa0d8590508e753e097ba9157ea80ebeb7ee99e160617cb65ee4065721053522ab3899c8612db8317fd91b2a8828880359be34c2843f842bdf3b37ae81530eb544885a992a543e96e9408084c96f1c7d57da70543026e62fb96adf65905d6d0d2f21db313c6c37fc95dcdccb6b99e54b033729e7c34e028b7bb4cdff001a555a95bebdef533a9f53a3045a34d373da5dfdabc76f81d082f4c96964bdc12035ca90fe9dce6fcb77cae7d546c1532c5f9eb1bd45283a2e7acce174153d9234e6def14ee5ad2b2cda1889ec57bcba42985b4b1d023cbb891387e138d26ad06547e2a71824bb8f4f72bde760a6c41bf6d803a4a67c68de2930dc171557c422e7ae7d547101ef741421a9e14c05edd65173a9c616629f4bd534686dbb987c32a3b3e8b32ebfcf06aede25c541717452f7c1ff449b3b73477b113fbb915f293047c286c32a46b34cbd151cd8e4dfc2cc6e55dbfb7641af9686b8ea1d91b16c20303b0d2dc6725228bf239b5b263bae62030035481c297eccdee7b773be48b3e0c6b4f02ed95b2091f21bef9f2d44fff90d6ed08723a5bddd31d97c274a7db932f49470f32a44f13d362b7c74186b8d2d3261312f33e85e1e09fba3b56e32f4626481f135829a059e1124bc903620dbcdc85c8e8d5701c54fd1f12ac4fdb57361988622607509b6a5cfc3745231f7c67776c094283207618d35c63c53633a24926d9a9d13cd5e1e01c35d073af60470651701e6f0a5714ce8d2e8bba1415f85a1faf4818c226a82bb01efc9f8479bb5f333c02d20bec991217faf65e6844f6d7210379471ba1fd1b6772b0a6327b6611431a06fc34a4927c0c3610ebc278a575247055667c3bcb300c460975182525d4a12fa4c1c019bbc33b00b81bdca69c092af70597e5a0fb29e26d70030263c0d228fa4d5545f0e68671ba8828d3f45b622f8a81f908040a22a71e82adce9ca5b5a768fa911848fdc18c64fc8554cad3042ea15d6022343720f90c9d08b845e83f444f7fb36b72c6e212e4e5c75ac361260c817029d49988576e6905d65964cf9a5e93c43a8bcb0a6deca93fc8a2ee9f1b139c641abaa489251d4c265367285a5495e51e71d7a2250b0fc21d9d5e5a2cd81c24c38f0618b1a39cd9003c3a24b07ef7ea46e963055f05d7a6f8b0828981ae1b0390b33d71919e6d1281e8c10447ad007d4744ee1a958dd75e8e9b56ca795b
w3bstream-coordinator  | msg="task finished" project_id=10001 task_id=29

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "projectID": 10002,
    "projectVersion": "0.1",
    "data": "{\"private_input\":[1,1], \"public_input\":[2] }"
  }' \
  localhost:9000/message

w3bstream-sequencer    | 200 |   17.208166ms |    192.168.65.1 | POST     "/message"
w3bstream-coordinator  | msg="dispatched a task" project_id=10001 task_id=30
w3bstream-prover       | msg="get a new task" project_id=10001 task_id=30
w3bstream-prover       | msg="acquire vm instance success" vm_type=halo2
w3bstream-coordinator  | msg=stdout proof=217ffa4c45a9db91cf1da3d3b18de088eba825d5c129e42834ab496d02f9b15c2d64a74cdb8232be47667c49a3bf653070aa00ee7f9a3d3f70b046923cc9bfe82234fc2563878005f92c50b1e03c89f1da25b206f7c852769de5ccd21247a3c8084ef36cb92fa85d193482f840e040dbf57b82a80eaf9f1b839425aa6d61b10d1934580dbfd66526767792dc3554e7741975e971a5967678e37cd025202b13272ed46935d817514a36d1689e86a8fbaa68c272864eb39420d65844473dd8bd781d03b4cb0e25efb02ad388bb6ecacd6fec84c2fccac3b59fee23dc6cc0d2ded915a679691f88286bdd34a689828329d7fc6373ccdeb07f69ce3fa9000471a669290a4ad928111be9c0d4d5da80010d7e96d290a45d19921cd5706a5b26f886af175d4b03468215bc970a65cfc9e74e17b2b3458024d0f6b5de60e259e2d83a3b2c69746789436fc886c246315a2219e6c5105703d5d666f23fd0ad5082e9535c1a44d40a4778aadaedb9524b96741e24666ef2f477c78b61c5230cf7754c6ad92ed06df716bee115f58a3382c9344cf5f774b781252afb28f4552737586fd52f042bb58fb24eed3523f84afdf036076b4673e4ffb8a8cd6d9c2c0c1e4ca2dd3d2edeb6fdc31b912df4bb57de64166a67d5d9a427f565fdedc19021463e7b361e0ffcc559ba0dab834b21011510f3d959fc36970b3984adaaae92f5d2ac08c7c91d4eb94eb47e9d931722caa00aaf4fe9ef7c0903ed279f8468cd3753914f92151c50a2038f20590eefff8493eb7262f3c9df41adf145974c55e361d2e0c1cfd00b88747d57287b8bc105cbb9218f01c8411c994617218416a60889e37b48aa521a9f46867de0e594f98be08653f764cdf8d6a1a3785e674041ac6d444b0d531b05fc36ff99c92812c9bd0bb66d7801335c11b63ba05b3dceb750b84de4eec86a2b2144b2ebd6210d4d426d45ab6a6edb49754e5017b3a1c5a2b10a7ace9e02e61059da9844e8b5d3dd69be1e86bfea3f3f1d16a3570e38094e073e89d5877bce2930aa4e4932c2ce3595264c32a96b92c10f1a784f5e7da7788e2cf2b796b25e02ad46939a2ac1b606945767247b28b412dab85c15e28388f6ee952001304072282e4ed4ca4b80235bb182ca93a085592b9465e59fbba7ab13fc7e295fa957301a76f4d4cd12b1c60078b2ba96002228956d33c59f0cb92e46605355078b19590faf22ec7e1f780d06646486dd15ee12140dec6260434f516ee8aed1164ff477210b6714b7ec0f4854c37601975ccf3de170ab59164e8588cb245a8a21da681f1af3944f681c655b0c972ce390468d235116337e92483029aac0c1b064250218010fb5206e8d34596608ae76e32ab5e45d523a252cd55402f6310bd16c10ad5f168448ee150c467ce18b1c8f60e49bc7570a85ac89018f00995d8bf20d1753760769f24bf159d143ae259c340059068547c12de5e0acc64629c071718ff9bda41c50913ea98616a30d70b11e3372aafefc7e93dd0740b9caf86675db5f23efed296585ba4da466e4fb2f4227a948c06fca8884f2fc4ec2087b9642a7fa1b121202c7dc2735f92e45e72d271bf9ec1a1d7c5985407feca7fe0472576e26b9d49d2181a817d1635bd25153f8a33c444e87aaa65dc8d7d3c033122c6ea90b63fde907548bbcf2242dcf85daae8b36aa51961a84f5c42c9212180ee1ca3fd9f72ad020b79a583ba1de88241d6ba8c04a64496d521b1f268260bbf44e08dc70d582d323a860e92c131694004ab61989e75abbf048a29f2f806f6dc86b6a730ae7f3290b9aa31f631291cdfba8b166e421fafb21c4b47270cdd841f49397fd5b1ccfc52aa03d79cc9bab16bad32ab648cae6eb891b2fefb35e77df551aa6e55fe65a912079efabd25c0bb68f8a28cf0d228f3e794e41c1ef143bbad05b0b384d6a58b00a06ae78640abbd850b9c267c8102b9f83ed64b6a6ac0050ee9927d8bd28e70113b960e2e78a10a6418743d9d2958f059ecfabc6ded3f636b1380cda368c6804
w3bstream-coordinator  | msg="task finished" project_id=10001 task_id=30

By leveraging W3bstream, developers can efficiently process and validate device data before committing proofs of physical work to the blockchain, ensuring integrity of data processing and reducing on-chain computation costs.

This guide outlines the steps necessary to integrate W3bstream into your DePIN project, from setting up a local development environment to deploying your configuration on the IoTeX blockchain. To use W3bstream as the off-chain compute layer in a DePIN project, developers should follow these steps:

1. Run a local W3bstream node: Set up and run a W3bstream node on your local machine to facilitate the development and testing process.

2. Build the prover logic: Develop the logic that processes and verifies device data, ensuring it meets the necessary criteria before being sent to the blockchain.

3. Create a W3bstream configuration file: Compile a configuration file that includes your prover code, specifying how W3bstream should handle and process incoming data.

4. Test the W3bstream prover locally: Validate your prover logic and configuration file by running tests locally to ensure everything functions correctly.

5. Deploy the W3bstream configuration to the IoTeX blockchain: Once testing is complete, deploy your configuration to the IoTeX blockchain, enabling your DePIN project to leverage W3bstream's off-chain compute capabilities in a live environment.

Prerequisites

1. A coordinator node in the off-chain computing layer retrieves data from the data availability layer based on the configuration of a DePIN project;

2. The coordinator node feeds data to an idle prover node or a selected set of idle prover nodes in the off-chain computing layer;

3. The prover node(s) performs computation specified by the DePIN project and generates the computation result and corresponding validity proof;

4. The computation result and validity proof are returned to the coordinator node;

5. The coordinator node sends the computation result and validity proof to a smart contract for further processing.

npm install -g assemblyscript

Build the prover

Clone the W3bstream repository

Start by cloning the W3bstream repository, where you can start from a template example:

git clone https://github.com/iotexproject/w3bstream.git

Open the folder in a code editor and make the required modifications based on your actual data message and prover logic.

Build the Circuit

Enter the zkWASM circuit folder

cd examples/zkwasm-circuit/circuit

Build the prover with:

asc src/add.ts -O --noAssert -o zkwasm_demo.wasm

The prover binary will be saved in zkwasm_demo.wasm.

Verify a Proof Locally

Using Docker

1. Execute the docker run command for local verification. Note that the directory where the proof is located needs to be mounted into the image. It's simple, just input the proof file. You can also use the help command to check how to use it.

docker run -v /host/zkwasm-proof.json:/zkwasm-proof.json iotexdev/zkverifier /verifier/zkwasm-circuit verify -p /zkwasm-proof.json

Using the binary

Build the Verifier

Run the following command to build the verifier:

cargo build --release

After the command is successful, a zkwasm-circuit executable file will be generated in the target/release directory.

Verify

You can execute the binary file in the target/release directory. To verify a proof, simply provide the proof file as an argument. For more details on usage, you can use the help command.

target/release/zkwasm-circuit verify -p zkwasm-proof.json

To deploy your prover logic to the W3bstream network, you need to create a W3bstream project file. This file includes the binary code of the ZK Prover and the destination contract of the DePIN project that will receive the computation results and proof on the blockchain.

A W3bstream proof can be directed to various destinations, referred to as "Outputs." Each configuration in the W3bstream project file must have an output specified. Below is an example configuration structure:

{
  "defaultVersion": "0.1",
  "versions": [
    {
      "vmType": "halo2",
      "output": {
        "type": "..."
      },
      "version": "0.2",
      "code": "789cecb3bc5acda85509c609e9..."
    },
    {
      "vmType": "risc0",
      "output": {
        "type": "..."
      },
      "version": "0.1",
      "code": "789cecb3bc5acda85509c609e9..."
    }
  ]
}

Each output type has its own settings and parameters. Below are the supported output types and their respective configurations:

Standard Output

stdout is the default output for a configuration and is ideal during the development phase. It allows developers to retrieve the proof from the W3bstream node log for local verification without writing it to an actual destination. This simplifies debugging and testing:

"output": {
  "type": "stdout"
}

Explanation of Settings

• type: Specifies the output type. For standard output, this should be set to stdout.

By using the stdout output type, you can focus on ensuring that your proofs are generated correctly and efficiently before moving on to more complex output configurations.

Ethereum Contract

When you need the W3bstream proof to be written to your Dapp contract (e.g., to trigger your DePIN token economy), you should use the ethereumContract output type. This output currently supports the IoTeX blockchain and requires some additional settings:

"output": {
  "type": "ethereumContract",
  "ethereum": {
    "chainEndpoint": "https://babel-api.testnet.iotex.io",
    "contractAddress": "0xDea7f9b692cb90a2DF1860189BcAc428500c44f1",
    "receiverContract": "0x22D5B41b28E7f9739a3D0C984737174cC7e554dF",
    "contractMethod": "submitProof",
    "contractAbiJSON": "[{\"inputs\":[{\"internalType\":\"bytes\",\"name\":\"seal\",\"type\":\"bytes\"},{\"internalType\":\"bytes32\",\"name\":\"imageId\",\"type\":\"bytes32\"},{\"internalType\":\"bytes32\",\"name\":\"postStateDigest\",\"type\":\"bytes32\"},{\"internalType\":\"bytes\",\"name\":\"journal\",\"type\":\"bytes\"}],\"name\":\"submitProof\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]"
  }
}

Explanation of Settings

• type: Specifies the output type. For Ethereum contracts, this should be set to ethereumContract.

• chainEndpoint: The endpoint of the IoTeX blockchain where your Dapp operates.

• contractAddress: The address of the W3bstream router contract on the IoTeX blockchain.

• receiverContract: The address of your DePIN Dapp contract that is supposed to receive the W3bstream proofs.

• contractMethod: The method in the receiver contract that will handle the proof.

• contractAbiJSON: The ABI of the method in the receiver contract that will handle the proof.

By configuring the output as shown, you ensure that the proofs generated by W3bstream are correctly sent to your Dapp contract on the IoTeX blockchain, enabling your DePIN token economy to function as intended.

A closer Look at the W3bstream Project File

The W3bstream project file includes all the necessary code and configurations for a W3bstream node to correctly serve your DePIN project with data computation and on-chain proof submission. When deploying a W3bstream project you are in fact deploying a project file and linking it to your Project ID in the W3bstream contracts.

Below is an example of a W3bstream project file:

{
  "defaultVersion": "0.1",
  "versions": [
    {
      "vmType": "risc0",
      "output": {
        "type": "stdout",
        "ethereum": {
          "chainEndpoint": "https://babel-api.testnet.iotex.io",
          "contractAddress": "0xDea7f9b692cb90a2DF1860189BcAc428500c44f1",
          "receiverContract": "0x22D5B41b28E7f9739a3D0C984737174cC7e554dF",
          "contractMethod": "submitProof",
          "contractAbiJSON": "[{\"inputs\":[{\"internalType\":\"bytes\",\"name\":\"seal\",\"type\":\"bytes\"},{\"internalType\":\"bytes32\",\"name\":\"imageId\",\"type\":\"bytes32\"},{\"internalType\":\"bytes32\",\"name\":\"postStateDigest\",\"type\":\"bytes32\"},{\"internalType\":\"bytes\",\"name\":\"journal\",\"type\":\"bytes\"}],\"name\":\"submitProof\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]"
        }
      },
      "version": "0.1",
      "code": "789cecb3bc5acda85509c609e9..."
    }
  ]
}

Explanation

The W3bstream project file is in fact an array of configurations. Each configuration in the array allows you to define different settings for various provers and outputs, enabling flexibility in how W3bstream handles proofs and integrates with other components.

• defaultVersion: The default version of the configuration to be used.

• versions: An array of all available W3bstream configurations for the project. Each configuration includes:

  • vmType: The type of prover (e.g., halo2, risc0, zkwasm, with more types in the future).

  • output: Defines where the proof should be written.

  • version: The version number of this configuration.

  • code: The actual code of the prover if it's a ZK prover. Zlib compressed and hex encoded.

Create a configuration for your project

A W3bstream project file with a valid configuration can be easily generated using the ioctl CLI for various types of provers. After generation, the configuration can be manually finalized by adding receiver contract details, version numbers, and other necessary information.

Risc Zero provers

To generate a W3bstream project file for a Risc Zero prover using a Postgres database as the Data Availability (DA) Layer, use the following ioctl command:

ioctl ws project config \
    -t "risc0" \
    -s "postgres://test_user:test_passwd@localhost:5432/test?sslmode=disable" \
    -i "methods.rs" \
    -o "20000" \
    -e "{\"image_id\":\"RANGE_ID\", \"elf\":\"RANGE_ELF\"}"

Make sure to:

• Configure DA Layer Credentials: Ensure the Postgres database credentials are correct.

• Customize File Paths: Set the path to your methods.rs file appropriately.

• Customize Project File Name: Change the project file name (e.g., 10001) as needed.

• Match image_id and elf Fields: Ensure the image_id and elf fields in the command match the values in your methods.rs file.

Halo2 Provers

For a Halo2 prover, use the command below:

ioctl ws project config \
    -t "halo2" \
    -s "postgres://test_user:test_passwd@localhost:5432/test?sslmode=disable" \
    -i "pkg/halo2_simple_circuit_bg.wasm" \
    -c "20001"

zkWASM Provers

For a zkWASM prover, use the command below:

ioctl ws project config \
    -t "zkwasm" \
    -s "postgres://test_user:test_passwd@localhost:5432/test?sslmode=disable" \
    -i "zkwasm_demo.wasm" \
    -c "20002"

To utilize the proofs generated by W3bstream in your Dapp contract, it's essential to verify the receipt on-chain. In this section of the documentation, we will explore how smart contracts of DePIN projects can receive a W3bstream proof, verify it, and utilize the computation results to trigger token economies. For example, this might involve awarding crypto assets to device owners upon proving that certain "work" has been performed in the physical world by the DePIN device.

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Build the prover

Clone the W3bstream repository

Start by cloning the W3bstream repository, where you can start from a template example:

git clone https://github.com/iotexproject/w3bstream.git
cd examples/halo2-circuit/

Open the folder in a code editor and make the required modifications based on your actual data message.

Build the circuit

wasm-pack build --target nodejs --out-dir pkg

The circuit bytecode is saved in the file halo2_wasm_bg.wasm located under the pkg folder.

Build the circuit executable

The command below will create thasdfwefe circuit executable that can be used to generate and verify proofs locally, as well as generate the Solidity contract for on-chain verification of a proof:

cargo build --release

This section of the documentation explains how to create a W3bstream ZK prover using Risc Zero as the ZK framework.

rustc --version

cargo version

rustup update

cargo install cargo-risczero
cargo risczero install

Build the prover code

Clone the W3bstream repository

Start by cloning the W3bstream repository, where you can start from a template prover:

git clone https://github.com/iotexproject/w3bstream.git
cd examples/risc0-circuit/

Open the folder in a code editor and make the required modifications based on your actual data message.

Build the prover logic

cargo build --release

The prover bytecode is saved in a file named methods.rs inside the release folder. The correct path is logged at the end of the build:

warning: range-method@0.1.0: methods_path is: "/Users/simone/Source/GitHub/machinefi/sprout/examples/risc0-circuit/target/debug/build/range-method-2bec077ba5c1d7b6/out/methods.rs"

The method.rs file also includes the image ID of the prover that is needed by the verifier when verifying a proof:

pub const RANGE_ID: [u32; 8] = [512905798, 3876631256, 1803615688, 344980519, 987991463, 241449906, 813598757, 370978982];

When your W3bstream project file is ready, you need to deploy it to the IoTeX blockchain for it to become discoverable by the W3bstream network. Let's go through the stpes.

Prerequisites

Register your DePIN Project in W3bstream

Here is an example W3bstream project registration:

The output of the ioctl command will reveal the newly created W3bstream project's settings and status:

Set the W3bstream project file

With your project registered in W3bstream it's now possible to deploy your project file:

The output of the command will show the new status of the project:

The project file has been uploaded to IPFS and the uri along with the hash has been set for your project in the W3bstream registry.

The last thing to note is that your project is paused by default, which means W3bstream nodes will not process any task available on the DA Layer that targets your project until the project activity is resumed.

Start the project

As the owner of the project NFT, you have the ability to query and interact with your W3bstream project at any time. Below are the operations you can perform on your W3bstream project:

Start the Project

To start your project, use the following command:

Query the Project

To query the status or details of your project, use the following command:

Set Required Prover Amount for the Project

By default, the prover amount that processes the project's tasks is set to one. You can customize this amount using the following command:

Stop the Project

If you need to stop the project's task processing, use the following command:

Risc Zero Verifier Contract (Risc0)

If your W3bstream project generates Risc Zero proofs, you can verify it from your Dapp deployed on the IoTeX blockchain by calling the IoTeX pre-deployed verifier contract for Risc Zero.

Example W3bstream Dapp Contract

Generate the Verifier Contract

After the prover is built, a Solidity verifier contract can be generated with:

Just ensure you customize the halo2-simple-circuit executable name with your own prover name.

Example W3bstream Dapp (Halo2)

In this section of the documentation, we will review the steps required to create the prover code based on the proving technology your project requires. Currently W3bstream supports several ZK proving technologies. TEE and additional provers will be added in future releases.

The recommended method to run a W3bstream node is using official Docker images from IoTeX.

docker version

docker compose version

sudo apt install docker-compose-plugin

Instructions

1. Configure your blockchain account

To enable your node to send proofs to the blockchain, set up a funded account on the IoTeX Testnet:

export PRIVATE_KEY=<YOUR_DEV_WALLET_PRIVATE_KEY>