# Welcome
Ryoshi Layer 2 is a groundbreaking, community-driven Layer 2 solution built on the Polygon Chain Development Kit (CDK). It offers an Ethereum-compatible environment that brings together the best of scalability, security, and user experience, powered by zero-knowledge (ZK) technology. Ryoshi is dedicated to empowering the Shib Army, leveraging the beloved $SHIB token to fuel transactions within its ecosystem.
The Ryoshi network aims to be more than just a blockchain; it's a movement. Inspired by the spirit of the Shiba Inu community, Ryoshi envisions a decentralized future where the Shib Army leads innovations in crypto space. It's a platform where groundbreaking projects and novel ideas flourish, all powered by $SHIB.
# Solution Overview
Ryoshi is built using the Polygon CDK. Polygon Chain Development Kit (CDK) is a modular, open source software toolkit for blockchain developers which supports the installation and configuration of a variety of chain architectures. Polygon CDK empowers developers to launch new L2 chains running the Polygon zkEVM technology on Ethereum or, in the future, transition existing Layer 1 chains into ZK-EVM L2s.
Ryoshi is a decentralized Ethereum Layer 2 network that offers a secure and user-friendly blockchain experience to all, using advanced cryptographic zero-knowledge proofs to provide validity and near-instant finality to off-chain transaction computations.
# Relevant Terminologies
Block space
The capacity of each block. The amount of block space a blockchain has determines its throughput. Blockchains that suffer from high fees occur because the demand for block space exceeds supply.
Consensus
Consensus refers to a function of modular blockchains where the ordering of transactions is agreed upon by a set of validators. To agree on the order of transactions in a block, validators follow a consensus algorithm.
Data availability (DA)
Data availability answers the question of whether this data has been published. Specifically, a node will verify data availability when it receives a new block that is getting added to the chain. The node will attempt to download all the transaction data for the new block to verify availability. If the node can download all the transaction data, then it successfully verified data availability, proving that the block data was actually published to the network.
Data availability committee (DAC)
A data availability committee (DAC) is a permissioned group of nodes responsible for providing data availability to a blockchain.
Data availability sampling (DAS)
Data availability sampling is a mechanism for light nodes to verify data availability without having to download all data for a block. Data availability sampling (DAS) works by having light nodes conduct multiple rounds of random sampling for small portions of block data. As a light node completes more rounds of sampling for block data, it increases its confidence that data is available. Once the light node successfully reaches a predetermined confidence level (e.g. 99%) it will consider the block data as available.
# Key Components
zk (zero-knowledge)
Zero-knowledge proof technology can prove the validity of a batch of transactions through succinct proofs, ensuring computational trustworthiness and enabling scalability.
EVM (Ethereum Virtual Machine)
This is the smart contract execution environment within the Ethereum ecosystem. It empowers Ethereum to execute smart contracts and function as a worldwide computing network, distinguishing it from Bitcoin, which primarily operates as a digital currency and is often likened to a basic calculator. Additionally, EVM gives rise to the different types of zkEVMs, each implementing zero-knowledge proof technology to enhance Ethereum's capabilities.
Rollup
A rollup is a type of blockchain that offloads some work to a layer 1. Rollups host applications and process user transactions. Once those transactions get processed, they are then published to layer 1. It’s L1’s job to order those transactions and check that they are available. Over time, two primary designs emerged for rollups: optimistic and zk-rollups.
Lower fees
Ryoshi does not consume expensive gas (i.e., DA to store transaction data off-chain).
ZKP powered scalability
Ryoshi is not bounded by the amount of transaction data that can be published to Ethereum with ZK-validity proofs.
Ethereum security
Ryoshi natively inherits the security of Ethereum, securing user funds from malicious operators.
Near-instant finality
Ryoshi utilizes cryptographic security to ensure the integrity of transactions, achieving near-instant finality and robust security.
Portal to Web3
Enter the world of Web3 via MetaMask Wallet, built with compact infrastructure modules to create innovative DApps.
# Technical Architecture
Detailed breakdown of the Layer 2 architecture
The major components of Ryoshi are:
| Component | Type |
| ----------------- | --------------------------------- |
| Virtual Machine | zkEVM |
| Mode | Validium |
| Data Availability | Data Availability Committee (DAC) |
| Consensus | Ryoshi PoE contract `ZkEVM.sol` |
| Sequencer | Trusted |
| Gas token | SHIB |
Explanation of how transactions are processed and data is managed
# Transactions and Data Flow
The process of validating a specific transaction within the batch typically involves three steps:
1. **Trusted state**
This state is given by the trusted sequencer almost instantaneously. The state is updated on L2, but has not yet reached L1.
2. **Virtual state**
Batches have been sequenced and data is on L1. At this point, transactions and data can not be modified as the state is final, yet they are not yet proven and are available on L1 for anyone to prove.
3. **Verified state**
Zk-proof has been posted on L1, and the smart contract verifies the virtual state, allowing for the withdrawal of funds.
# Data flow in Ryoshi
Transactions on the Ryoshi network have a typical flow starting from the users' interactions with their wallet on Ryoshi, to how the transactions are batched, sequenced, and aggregated on Ethereum L1:
* Transactions are submitted to Ryoshi
* Transactions are executed almost instantly
* Transactions are batched together using data encryption methods
* Batches are sequenced and sent to Ethereum L1
* Consolidated finality is achieved on Ethereum L1 with the power of zk-proofs
# Flow Chart
1. **Submitting transactions**
As a user, you submit transactions by signing transactions and sending them through the JSON-RPC interface.
2. **Executing transactions**
The transactions are then stored in the pending transaction pool, where the sequencer node running the zkEVM software picks these transactions up and decides which ones it wants to process or discard. The sequencer will do a few of the following checks to see if the transaction should be discarded or processed:
* If the sender has sufficient funds to complete the transaction
* If the smart contract called actually exists and contains valid bytecode
* If the transaction is not a duplicate
* If the transaction does not involve a "double-spend", which means the sender's funds have not already been used in another transaction
Once the transaction is considered valid, the sequencer will update the Ryoshi state. Users will experience transactions going through almost instantly. From here onwards, the user remains engaged in the Ryoshi L2 state. Everything that follows involves sharing transaction data back to Ethereum L1, but this step is only important for users who wish to transfer their funds from Ryoshi L2 back to Ethereum L1.
3. **Batching transactions**
The sequencer combines multiple transactions into a single batch and sends them to the `zkEVM.sol` smart contract. This contract is stored on Ethereum mainnet and also has a separate version on the Ethereum Sepolia testnet. Batches are not necessarily validated or confirmed at this stage.
4. **Verifying transactions**
Using ZKPs, the `zkEVM.sol` smart contract acts as a verifier in verifying transactions. It verifies whether the batch just received is valid or not, through sending the batch to an aggregator node.
5. **Generating & verifying zk-proofs/validity proofs**
The zkEVM.sol smart contract sends the batch it just received to an aggregator node, which is a machine running zkEVM software that communicates with a zkProver. The flow is as follows:
* The aggregator receives the batch from the smart contract
* The aggregator sends the batch to the zkProver
* The zkProver creates multiple zk-STARKs -> a single zk-STARK -> a zk-SNARK
* The zk-SNARK (the validity proof) gets sent back to the aggregator
* The aggregator sends back the validity proof to the `zkEVM.sol` smart contract
* `zkEVM.sol` verifies the validity proof
* If the validity proof is valid, accept it
* If it is not valid, reject it
6. **Reading events on Ryoshi**
Finally, DApps read information from Ryoshi through the synchronizer. It reads events from the Ethereum smart contract(s), storing knowledge of both the zk-validity proofs from the aggregator, and the batches submitted from the sequencer. This way, DApps can easily get a view of the state of Ryoshi via JSON-RPC.
# Technical Rationales
Ryoshi Validium
Ryoshi is built with Polygon CDK, an advanced open-source framework designed for the rapid deployment of zk-powered layer 2 (L2) blockchains on Ethereum
Ryoshi adopts the validium mode, and implements a dedicated committee of sequencers, to maintain seamless interoperability with all other Polygon chains, delivering a high performance L2 scaling solution.
Since transaction data is not stored on the Ethereum mainnet, it is both executed and stored off-chain, which can lead to a massive enhancement in scalability. In the premise of ensuring security, Validium can reduce L1 gas storage costs, hence reducing transaction costs for users on L2, with a prominent enhancement in user privacy and user experience.
Similar to zero-knowledge rollups (ZK-rollups), Ryoshi confirms off-chain transactions on the Ethereum network. This approach prevents incorrect state changes and boosts the security of the Ryoshi network.
zkValidium vs. zkRollups
zkValidiums differ from Rollups and Sidechains because they only share the proof of validity, which confirms the results of the transactions with Ethereum, not the actual transaction data of the executed transactions. Here is how it operates: a verifier smart contract is deployed on Ethereum, and validium submits proof of validity to this contract. These proofs are zero knowledge in nature and contain transaction outcomes but not the specific transaction data.
The verifier smart contract assesses the validity of the proof. If it is found to be invalid, any batch submitted by the validium is rejected and not stored on Ethereum.
Consensus Contract
zkEVM.sol is the underlying protocol that guarantees the correctness of state changes through the use of validity proof. To confirm that specific predefined rules have been adhered to for permitting state transitions, the Consensus contract (zkEVM.sol, deployed on Ethereum layer 1) comes into play.
zkEVM.sol is responsible for verifying validity proofs to confirm that each transition has been executed correctly, utilizing zk-SNARK circuits for verification. To make this system work, two key processes are involved: transaction batching and transaction validation. To perform these procedures, Ryoshi involves two types of participants: sequencers and aggregators.
Sequencer: it is responsible for proposing transaction batches to the network, essentially grouping transaction requests and adding them to the zkEVM.sol.
Aggregator: it is responsible for reviewing the transaction batches' validity and providing the necessary proofs of validity. Any permissionless aggregator can submit these proofs to demonstrate the accuracy of the state transition computation.
Data Availability
Ryoshi operates in validium mode, where it integrates a secure data availability layer managed by a DAC. Below are the functionalities of DAC:
* Verifies the availability of data associated with specific blockchain blocks
* Ensures data robustness and computational efficiency of Ryoshi
Advantages of the DAC provided by Polygon CDK
The DAC primarily provides:
* Lower transaction fees: less computations leads to lower fees
* State privacy: maintaining a secure state change record to ensure data integrit
# Features and Benefits
Key features of the Layer 2 solution
1. **Modularity and sovereignty**
CDK offers a modular environment for ZK-powered L2 chain design. Developers can customize chains according to their needs.
2. **Scalability**
Ryoshi L2 enhances transaction speed and can be multiplied to achieve an elastically scalable ecosystem.
3. **Independent data availability**
With a dedicated data availability layer and a data availability committee, Ryoshi L2 provides robust off-chain data access and reliability. This structure, independent of Ethereum, ensures substantial data resilience and integrity.
4. **Interoperability (forthcoming)**
Through an in-development interop layer, CDK-developed chains can be seamlessly interoperable, meaning atomic L2 <> L2 transactions. Ryoshi L2 will have the opportunity to opt-in to the interop layer and tap unified liquidity.
5. **Near-instant finality**
Ryoshi L2 relies on cryptographic security, ensuring transaction integrity without the need of full nodes. This approach guarantees near-instant finality and robust security.
6. **Extensive Web3 support**
Ryoshi L2 leverages a comprehensive ecosystem with premium service providers offering essential tools for application integration, development, and deployment.
Advantages over existing solutions
1. As Polygon CDK offers a suite of tools, libraries, and documentation to streamline the development, testing, and deployment processes of DApps, this allows developers to build their applications more quickly and deploy them more easily on Ryoshi.
2. Ryoshi L2 is compatible with the Ethereum Virtual Machine (EVM), which means developers can use familiar Solidity language and tools to build smart contracts and decentralized applications (DApps) without needing to learn new programming languages or tools.
3. Ryoshi implements Gas token abstraction, this Layer 2 has customized Gas token.
# Getting Started
Welcome to Ryoshi developer documentation
Ryoshi is a zkEVM Layer 2 network built on Ethereum, powered by [Polygon CDK](https://wiki.polygon.technology/docs/cdk/) - a zkEVM stack for building Ethereum L2 scaling solutions. Developers can easily deploy their existing contracts on zkEVM, and users can move their assets from Ethereum and conduct transactions off-chain. These transactions are bundled into groups with a zero-knowledge proof to verify their validity.
## Mainnet Configuration
You can add Ryoshi by inputting the following network info: (Mainnet info TBC)
| Properties | Network Details |
| ----------------------- | --------------- |
| Network name | Ryoshi Network |
| RPC URL | |
| Chain ID | |
| Token symbol | SHIB |
| Block explorer URL | |
| Ethereum Smart Contract | |
You can also simply add Ryoshi to MetaMask
## Testnet Configuration
You can add Ryoshi Testnet by inputting the following network info:
| Properties | Network Details |
| ----------------------- | --------------------------------------------------------------------------------- |
| Network name | Ryoshi Testnet |
| RPC URL | |
| Chain ID | 117722 |
| Token symbol | SHIB |
| Block explorer URL | [https://explorer.ryoshiresearch.com]() |
| Ethereum Smart Contract | 0x6Ab9dF51b1B794f89da427317b5fb1d9Be610F8d |
# Developer Guide
API documentation
Ryoshi supports JSON-RPC methods that are compatible with Ethereum, and zkEVM RPC methods for zkEVM.
***
## Ethereum compatible RPC
Here you will find the list of all supported JSON RPC endpoints and the differences between them in comparison to the default behavior of an Ethereum node. If a specific endpoint is not in the list below, it means that this specific endpoint is not supported yet. You can find more details in [Ethereum's JSON-RPC doc](https://ethereum.org/en/developers/docs/apis/json-rpc/).
| Method | Namespace | Notes |
| ----------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `web3_clientVersion` | Web3 | Get the Web3 client version |
| `web3_sha3` | Web3 | Returns keccak-256 (not the standardized SHA3-256) of the given data |
| `net_version` | Net | Returns the current network ID |
| `eth_protocolVersion` | ETH | Response is always 'zero' |
| `eth_syncing` | ETH | Returns an object with data about the sync status or false |
| `eth_gasPrice` | ETH | Returns the current Gas price |
| `eth_blockNumber` | ETH | Returns the current block height |
| `eth_chainId` | ETH | Returns the chain's identifier in hex format |
| `eth_getBalance` | ETH | Returns the account balance for a given account address and block number |
| `eth_getStorageAt` | ETH | Returns the storage address for a given account address |
| `eth_getTransactionCount` | ETH | Returns the total transaction for a given account address and block number |
| `eth_getBlockTransactionCountByNumber` | ETH | Returns the total transaction count for a given block number |
| `eth_getBlockTransactionCountByHash` | ETH | Returns the total transaction count for a given block hash |
| `eth_getCode` | ETH | Returns the code for a given account address and block number |
| `eth_sign` | ETH | The sign method calculates an Ethereum specific signature |
| `eth_sendTransaction` | ETH | Sends transaction from given account to a given account |
| `eth_sendRawTransaction` | ETH | Creates a new message call transaction or a contract creation for signed transactions |
| `eth_call` | ETH | Executes a new message call immediately without creating a transaction on the blockchain |
| `eth_estimateGas` | ETH | Returns an estimated value of the Gas required to send the transaction |
| `eth_getBlockByNumber` | ETH | Returns information about a block by block number |
| `eth_getBlockByHash` | ETH | Returns the block info given the hash found in the command above and a bool |
| `eth_getTransactionByHash` | ETH | Returns transaction details from a transaction hash |
| `eth_getTransactionByBlockHashAndIndex` | ETH | Returns transaction details given the block hash and the transaction index |
| `eth_getTransactionReceipt` | ETH | Returns the receipt of a transaction by transaction hash |
| `eth_newFilter` | ETH | Creates a new filter using topics of some kind |
| `eth_newBlockFilter` | ETH | Creates a filter in the node, to notify when a new block arrives |
| `eth_uninstallFilter` | ETH | Removes the filter with the given filter ID |
| `eth_getFilterChanges` | ETH | Polling method for a filter, which returns an array of logs which occurred since the last poll |
| `eth_getLogs` | ETH | Returns an array of all logs matching a given filter object |
| `eth_getFilterLogs` | ETH | Returns an array of all logs matching filters with the given ID |
| `eth_getTransactionbyBlockNumberAndIndex` | ETH | Returns transaction details by block height and block index |
| `eth_getCompilers` | ETH | Response is always empty |
| `eth_getUncleCountByBlockHash` | ETH | Response is always empty |
| `eth_getUncleCountByBlockNumber` | ETH | Response is always empty |
| `eth_getUncleByBlockHashAndIndex` | ETH | Response is always empty |
| `eth_getUncleByBlockNumberAndIndex` | ETH | Response is always empty |
| `eth_subscribe` | WebSocket | Subscribe using JSON-RPC notifications |
| `eth_unsubscribe` | WebSocket | Unsubscribe from an event using the subscription ID |
| `debug_traceBlockByHash` | Debug | Returns the possible tracing result number by executing all transactions in the block specified by the block hash with a tracer |
| `debug_traceBlockByNumber` | Debug | Returns the tracing result by executing all transactions in the block specified by number with a tracer (trace mode required) |
| `debug_traceTransaction` | Debug | Returns all traces of a given transaction |
| `txpool_content` | Txpool | Response is always empty |
## zkEVM RPC
You can use the following RPC methods to execute specific zkEVM functionalities:
| Method | Summary |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `zkevm_batchNumber` | Returns the latest batch number |
| `zkevm_batchNumberByBlockNumber` | Returns the batch number connected to the block |
| `zkevm_consolidatedBlockNumber` | Returns the latest block number connected to the latest verified batch |
| `zkevm_getBatchByNumber` | Gets a batch for a given number |
| `zkevm_isBlockVirtualized` | Returns 'true' if the provided block number is already connected to a batch that was virtualized, otherwise false |
| `zkevm_isBlockConsolidated` | Returns true if the provided block number is already connected to a batch that was verified, otherwise false |
| `zkevm_virtualBatchNumber` | Returns the latest virtual batch number |
| `zkevm_verifiedBatchNumber` | Returns the latest verified batch number |
.png?alt=media&token=0d790096-0253-4092-be17-1c3689ae5c9e)