diff --git a/content/docs/developer/architecture/security.mdx b/content/docs/developer/architecture/security.mdx index 6151e4c..1ba73d8 100644 --- a/content/docs/developer/architecture/security.mdx +++ b/content/docs/developer/architecture/security.mdx @@ -1,6 +1,6 @@ --- -title: Security -description: Security measures and mechanisms in Shardeum +title: Gas and Fee Model on Shardeum +description: This section explains how transaction fees work on Shardeum --- import { Callout } from 'fumadocs-ui/components/callout'; @@ -9,304 +9,77 @@ import { Callout } from 'fumadocs-ui/components/callout'; This page is getting updated -# Security +## Overview -Learn about the comprehensive security measures implemented in Shardeum to ensure network integrity, data consistency, and transaction security. +This page explains how transaction fees work on Shardeum and how developers can design applications with predictable and cost-efficient execution. -{/* -## Data Integrity and Consistency +### Gas Fundamentals -### 1. Overview +Shardeum uses the standard EVM gas model: -Data integrity and consistency are crucial for maintaining a secure and reliable blockchain network. In Shardeum, various mechanisms ensure that data remains accurate, consistent, and tamper-proof across all nodes. This section outlines how Shardeum maintains data consistency and integrity, with a focus on cryptographic methods. +- each operation has a defined gas cost, +- gas measures computational and state access effort, and +- transactions must specify a gas limit. -### 2. Dynamic State Sharding and Data Healing +This ensures compatibility with existing Ethereum tooling and mental models. -Shardeum's dynamic state sharding is designed to balance resource usage and prevent bottlenecks while maintaining data consistency across all shards. The network dynamically assigns transactions to shards based on load, ensuring efficient processing. Data integrity across shards is maintained through: +### Fee Denomination -* **Data Healing:** Nodes periodically compare their state against hashes of data held by other nodes. If discrepancies are detected, nodes request the correct data from their peers and update their state accordingly. This periodic comparison and correction process ensures that all nodes maintain a consistent and accurate view of the blockchain state. -* **Efficient Hashing:** Shardeum employs a custom hashing algorithm suitable for a sharded network, allowing efficient verification and repair of data across shards. This hashing ensures that data integrity is maintained even as transactions are distributed and processed across multiple shards. +All transaction fees on Shardeum are: -![Data Healing](/img/new/i55.png) +- denominated in SHM, the network’s native token, and +- paid by the transaction sender. -### 3. Cryptographic Hashing +Fees are deducted as part of transaction execution and distributed according to protocol rules. -Cryptographic hashing plays a fundamental role in ensuring data integrity in Shardeum. It ensures data remains unchanged and verifiable: +### Fee Calculation (High-Level) -* **Hash Generation:** Each piece of data and each transaction generates a cryptographic hash. This hash acts as a unique identifier for the data, ensuring its integrity. Even a minor alteration in the data results in a completely different hash, making tampering easily detectable. -* **Hash Verification:** During the validation process, validators use the cryptographic hash to verify the integrity of the data. The hash ensures that the data received by validators is exactly as intended, with no alterations or tampering. +At a high level, transaction fees depend on: +- the amount of gas consumed during execution, and +- the gas price specified in the transaction. -### 4. Timestamping +Actual gas usage is determined at runtime based on: +- contract logic, +- storage reads and writes, and +- execution complexity. -Timestamping is another essential measure for maintaining data integrity and consistency in Shardeum: +### Predictable Fee Behavior -* **Transaction Timestamp:** Each transaction is assigned a timestamp upon submission to the network. This timestamp records the exact time the transaction was created, ensuring the chronological order of transactions. -* **Order Verification:** Validators check the timestamps of transactions to ensure they are processed in the correct order. This prevents issues like double spending, where a user might attempt to spend the same funds multiple times. By verifying timestamps, validators ensure that only the first transaction is valid and subsequent attempts to spend the same funds are rejected. +Shardeum is designed to maintain predictable transaction costs under normal network conditions. -### 5. Consensus on State +Key characteristics include: -To maintain data consistency, Shardeum employs a robust consensus mechanism that requires agreement among participating nodes: +- stable fee behavior for common transaction types, +- minimal variance for simple transfers and standard contract calls, and +- reduced cost sensitivity for applications with frequent interactions. -* **Proof of Stake (PoS) and Byzantine Fault Tolerance (BFT):** Shardeum uses a hybrid consensus mechanism combining PoS and BFT. Validators are selected based on their stake and must collectively agree on the validity of transactions and state changes. This approach ensures that data consistency is maintained, as all changes to the blockchain state are agreed upon by a quorum of nodes. -* **Consensus on State Hashes:** Nodes share state hashes with each other periodically. These hashes represent the state of the blockchain data. By comparing these hashes, nodes can detect discrepancies and initiate data healing processes to correct any inconsistencies. +This predictability allows developers to: -### 6. Access Lists and Memory Management +- estimate user costs more accurately, and +- design UX flows without large fee uncertainty. -Shardeum uses access lists to manage and control memory access during transaction execution, ensuring data consistency and preventing unauthorized data manipulation: +### Gas Optimization Best Practices -* **Predictive Access Lists:** Transactions provide access lists indicating which parts of memory they will touch before execution. This helps schedule transactions and avoid conflicts by ensuring that no two transactions access the same memory simultaneously. -* **Runtime Verification:** During execution, if a transaction tries to access memory not listed in its access list, it is flagged and potentially rejected. This prevents unauthorized data access and manipulation, ensuring that transactions only affect the data they are supposed to. +Developers building on Shardeum can reduce costs by: +- minimizing unnecessary storage writes, +- batching related operations when possible, +- avoiding unbounded loops in smart contracts, and +- reusing well-tested contract patterns. -![Access Lists and Memory](/img/new/i56.png) +Standard Ethereum gas optimization techniques apply directly. -### 7. Cycle Records and Hashing +### Application Design Considerations -Each cycle in the network records data changes, with a cryptographic hash taken over this data. These hashes link to previous cycle records, creating a secure and immutable record of all changes across the network. +When designing applications: +- prefer simple, deterministic execution paths, +- surface fee estimates clearly to users, and +- handle transaction failures gracefully. -### 8. Deterministic Algorithms +For high-volume applications, careful contract design and RPC usage can significantly improve cost efficiency and user experience. -The deterministic algorithms guarantee every node processes transactions and maintains data in a consistent manner. +### What Developers Should Take Away -#### Data Synchronization and Validation +- Shardeum follows a familiar EVM gas model, lowering onboarding friction. +- Fees are SHM-denominated and designed to remain predictable. +- Existing Ethereum gas optimization strategies remain effective. -Nodes constantly synchronize and validate their data against other nodes. This way, whenever discrepancies occur, they will be identified and corrected promptly. This ongoing process helps maintain the overall consistency of the network data. - -![Access Lists and Memory](/img/new/i57.png) - -#### Networking and Gossip Protocol - -Shardeum uses a custom networking library and a gossip protocol to ensure efficient and secure communication between nodes, which is crucial for maintaining data consistency: - -* **Shardeum Net:** This internal protocol handles socket connections between nodes, optimizing performance and security. It ensures that messages and transaction data are securely transmitted across the network. -* **Gossip Protocol:** For broadcasting messages efficiently, Shardeum uses a gossip protocol where messages propagate quickly and redundantly across the network. This reduces the chance of missing critical information and ensures that all nodes receive transaction data promptly. - -![Networking & Gossip](/img/new/i58.png) - ---- - -## Node Security & Integrity - -### 1. Overview - -Node security and integrity are critical components of the Shardeum blockchain, ensuring that nodes operate correctly and the network remains secure against unauthorized or malicious activities. The following sections detail the comprehensive security measures implemented in Shardeum to prevent unauthorized or malicious behavior by nodes. - -### 2. Validator Security - -Shardeum employs a system where every active validator must know all other active validators. This control and visibility prevent unauthorized nodes from participating in the consensus process, ensuring only verified nodes can validate transactions. - -![Validator Security](/img/image4247.png) - -### 3. Permissioned Standby List - -Nodes in the standby list are permissioned, meaning their credentials and roles are pre-verified before they can become active validators. This ensures that the standby nodes meet all network security requirements before activation, preventing infiltration by malicious nodes. - -![Permissioned Standby List](/img/new/i44.png) - -### 4. Deterministic Lottery for Node Selection - -The transition from standby to active nodes is governed by a deterministic lottery system. This system is designed to be tamper-proof, making it impossible for standby nodes to manipulate their selection. The lottery is based on cryptographic principles that ensure fairness and randomness, preventing any single node from gaining an unfair advantage. - -### 5. Consensus Mechanism - -Shardeum employs a combination of Proof of Stake (PoS) and Byzantine Fault Tolerance (BFT) for its consensus mechanism. This hybrid approach ensures that nodes participating in the consensus process are both financially incentivized and cryptographically secured to act honestly. Validators are selected based on their stake, and BFT consensus ensures fast and secure transaction finality. This combination reduces the risk of Sybil attacks, where an attacker might create multiple fake nodes to gain control of the network. - -### 6. Slashing Mechanisms - -Shardeum has implemented robust slashing mechanisms to penalize nodes that exhibit malicious behavior or fail to perform their duties correctly. Key slashing rules and their enforcement include: - -* **Early Exit Slashing**: If a node leaves the network before completing its assigned tasks, it is subject to slashing. This ensures nodes remain active and fulfill their responsibilities. -* **Double Voting**: If a node sends conflicting votes for the same transaction (e.g., voting both for and against it), this indicates malicious behavior. Such actions are detected, and the node is slashed accordingly. -* **Lazy Node Detection**: Nodes that do not perform their required work but remain in the network to earn rewards are considered lazy. Shardeum employs various checks to detect such nodes. If a node is flagged as lazy and refutes the claim repeatedly without justification, it gets slashed incrementally until it is removed from the network. - -These slashing rules ensure that nodes operate honestly and contribute positively to the network's security and integrity. - -### 7. Lost Node Detection and Refutation - -To maintain network stability, Shardeum has a system to detect and handle lost nodes. A node is considered lost if it fails to respond to requests. The detection process involves: - -* **Stealth Checks**: Four deterministic nodes perform stealth checks by sending requests to the suspected lost node. These requests mimic regular traffic to avoid detection by malicious nodes. -* **Verification and Consensus**: If a sufficient number of these checking nodes confirm the node's unresponsiveness, it is marked as lost. The lost node is then removed from the network unless it refutes the claim. - -Refutation involves the node proving its activity and rejoining the network. Persistent failure to refute leads to penalties and eventual removal. - -### 8. Transaction Lifecycle and Nonce Handling - -Shardeum's transaction lifecycle includes several security features to prevent unauthorized transactions and replay attacks: - -* **Nonce Mechanism**: Each transaction includes a nonce, which is a sequential number to prevent replay attacks. Transactions with nonces out of order are held until the preceding transactions are processed. -* **Signature Verification**: Transactions must be signed with the sender's private key, ensuring that only authorized parties can initiate transactions from an account. - -### 9. Access Lists and Memory Management - -Shardeum uses access lists to manage and control memory access during transaction execution. This ensures that transactions do not interfere with each other, preventing unauthorized data manipulation: - -* **Predictive Access Lists**: Before execution, transactions provide access lists indicating which parts of memory they will touch. This helps schedule transactions and avoid conflicts. -* **Runtime Verification**: During execution, if a transaction tries to access memory not listed in its access list, it is flagged and potentially rejected. This prevents unauthorized data access and manipulation. - -### 10. Dynamic State Sharding and Data Healing - -Shardeum's dynamic state sharding ensures balanced resource usage and prevents bottlenecks. The network dynamically assigns transactions to shards based on load. Data integrity across shards is maintained through: - -* **Data Healing**: Nodes periodically compare their state against hashes of data held by other nodes. If discrepancies are detected, nodes request the correct data from their peers and update their state accordingly. -* **Efficient Hashing**: Shardeum employs a custom hashing algorithm suitable for a sharded network, allowing efficient verification and repair of data across shards. - -### 11. Node Lifecycle Management and Certificates - -The node lifecycle in Shardeum includes several steps to ensure only legitimate nodes participate in the network: - -* **Certificate-Based Staking**: Nodes must obtain certificates to join the network. This involves staking tokens, getting certificates from existing nodes, and passing readiness checks. -* **Standby and Active Modes**: Nodes join the network in standby mode and undergo a rigorous syncing process before becoming active. This includes syncing cycle data and account data, ensuring they are up-to-date and ready to participate in consensus. - -### 12. Networking and Gossip Protocol - -Shardeum uses a custom networking library and a gossip protocol to ensure efficient and secure communication between nodes: - -* **Shardeum Net**: This internal protocol handles socket connections between nodes, with optimizations for performance and security. -* **Gossip Protocol**: For broadcasting messages efficiently, Shardeum uses a gossip protocol where messages propagate quickly and redundantly across the network, reducing the chance of missing critical information. - -### 13. Periodic Patching and Consensus on State - -To maintain data consistency and integrity: - -* **Periodic Patching**: Nodes engage in periodic state checks using a tree structure to identify and correct discrepancies. -* **Consensus on State**: Nodes share state hashes with each other and repair any mismatches through efficient data requests, ensuring all nodes have the correct and consistent state data. - -### 14. Network Modes - -Shardeum uses various network modes to ensure stability and consistency throughout its lifecycle. The key network modes include: - -* **Forming:** The network allows nodes to join, sync, and go active until a minimum number of active nodes is achieved. -* **Processing:** The network processes application transactions. Nodes can be rotated. -* **Safety:** Only protocol transactions are processed. -* **Recovery:** The network stops processing application transactions and nodes stop syncing application data, but still handle protocol data. -* **Restart:** The network allows nodes to join without syncing or going active until a minimum total node count is reached. -* **Restore:** Nodes sync data from Archivers and other nodes, going active once synced. -* **Shutdown:** All transactions stop being processed and nodes exit the network after a short period. - ---- - -## Security in a Sharded Network - -### 1. Data Healing via Sharded Hash Tree (Advanced Security Mechanism) - -Shardeum uses a unique sharded hash tree (TRIE) to maintain data integrity. Nodes regularly exchange intermediate hashes to check for data consistency. When discrepancies are detected, nodes efficiently search the tree to locate and correct specific errors. - -If nodes in a transaction group find inconsistencies in transaction receipts or states, they can trigger a repair process. This involves requesting and validating the correct data from other nodes, ensuring the network stays synchronized and reliable. - -![Sharded Hashed Tree](/img/new/i59.png) - -Given that Shardeum functions as a sharded network, processing various transaction sets across its multiple shards, its security model diverges from non-sharded Layer 1 architectures. It must defend against both standard Layer 1 threats and those specific to sharded architectures. Below we will investigate the common attacks and how Shardeum mitigate them. - -### 2. Sybil Attacks - -* **Description:** Sybil attacks happen when attackers create numerous fake identities to gain control of the network, disrupting its security. - -![Sybil](/img/new/i60.png) - -* **Mitigations:** Shardeum tackles Sybil attacks by requiring each node to stake a certain amount of SHM tokens. This economic requirement makes it costly for attackers to create many fake nodes. Additionally, nodes that act maliciously are penalized and removed from the network, increasing the difficulty and cost of repeated attacks. - -### 3. Shard Takeover Attack - -* **Description:** This attack involves an adversary filling a shard with their own nodes to gain control. With 33% control, they can halt the shard; with 66%, they can forge transactions. -* **Mitigations:** Shardeum prevents this by randomly selecting and rotating nodes. Nodes can't choose their shard, and achieving 66% control would mean taking over the entire network, which is economically unfeasible due to staking requirements. - -### 4. Nothing at Stake - -* **Description:** In a network fork, validators might validate on both chains without incurring costs, unlike in PoW networks where resources prevent such behavior. -* **Mitigations:** Shardeum uses Proof of Quorum (PoQ) for consensus and Proof of Stake (PoS) as a deterrence against Sybil attacks. The network doesn't follow the longest-chain rule and penalizes double-signing, preventing such forks. - -### 5. Long Range Attacks - -* **Description:** Attackers create a fork from the genesis block to build a competing chain. -* **Mitigations:** Shardeum's PoQ and PoS mechanisms prevent such forks, ensuring the network only follows the legitimate chain. Digital signatures ensure transaction integrity, preventing long-range attacks. - -### 6. Censorship - -* **Description:** A validator may prevent certain transactions from being processed. -* **Mitigations:** Shardeum's architecture avoids this by not having blocks or leaders, meaning no single validator can control transaction inclusion. Effective censorship would require 33% control of a shard, which is countered by staking, node rotation, and random shard assignment. - -### 7. DoS or DDoS Attack - -* **Description:** These attacks knock nodes offline, disrupting network activity. -* **Mitigations:** Nodes should use ISPs with robust DDoS protection. Shardeum's design includes redundancy, allowing other nodes to validate transactions if some are down. New nodes can join the network each cycle, mitigating long-term impacts. - -### 8. Transaction Flooding - -* **Description:** Attackers flood the network with valid transactions to slow it down. -* **Mitigations:** Shardeum imposes SHM gas fees that, while affordable for normal use, make it expensive to flood the network. Additionally, excessively active accounts may face higher fees, deterring attackers without affecting regular users. - ---- - -## Transaction Security - -### 1. Overview - -Transaction security is paramount in Shardeum to ensure the validity, integrity, and authenticity of each transaction. This section outlines the various measures implemented in Shardeum to guarantee secure and valid transactions, including mechanisms like cryptographic hashing, timestamping, and nonce handling. - -### 2. Transaction Lifecycle and Nonce Handling - -Shardeum's transaction lifecycle includes several security features to prevent unauthorized transactions and replay attacks: - -* **Nonce Mechanism:** Each transaction includes a nonce, which is a sequential number associated with the sender's account. This mechanism ensures that each transaction is unique and prevents replay attacks, where an attacker might try to resubmit a transaction multiple times. Transactions with nonces that are out of order are held until the preceding transactions are processed, maintaining the correct sequence. -* **Signature Verification:** Transactions must be signed with the sender's private key. This cryptographic signature ensures that only the account holder can initiate transactions from their account, preventing unauthorized transactions. The signature is verified by validators before the transaction is processed, ensuring authenticity. - -![Nonce](/img/new/i48.png) - -### 3. Cryptographic Hashing - -Cryptographic hashing is a fundamental component of transaction security in Shardeum. It ensures data integrity and non-repudiation by producing a fixed-size hash value from the transaction data: - -* **Hash Generation:** When a transaction is created, a cryptographic hash of the transaction data is generated. This hash acts as a unique identifier for the transaction and is used to ensure that the data has not been altered. Even a small change in the transaction data will result in a completely different hash, making tampering easily detectable. -* **Hash Verification:** Validators use the transaction hash to verify the integrity of the transaction data during the validation process. The hash ensures that the transaction data received is exactly as the sender intended, with no alterations. - -### 4. Timestamping - -Timestamping is another crucial security measure in Shardeum, ensuring the chronological order of transactions and preventing double spending: - -* **Transaction Timestamp:** Each transaction is assigned a timestamp when it is submitted to the network. This timestamp records the exact time the transaction was created, helping to maintain the chronological order of transactions. -* **Order Verification:** Validators check the timestamps of transactions to ensure they are processed in the correct order. This prevents issues like double spending, where a user might attempt to spend the same funds multiple times. By verifying timestamps, validators can ensure that only the first transaction is valid and subsequent attempts to spend the same funds are rejected. - -### 5. Access Lists and Memory Management - -Shardeum uses access lists to manage and control memory access during transaction execution. This ensures that transactions do not interfere with each other, preventing unauthorized data manipulation: - -* **Predictive Access Lists:** Before execution, transactions provide access lists indicating which parts of memory they will touch. This helps schedule transactions and avoid conflicts by ensuring that no two transactions access the same memory at the same time. -* **Runtime Verification:** During execution, if a transaction tries to access memory not listed in its access list, it is flagged and potentially rejected. This prevents unauthorized data access and manipulation, ensuring that transactions only affect the data they are supposed to. - -![Access List](/img/new/i49.png) - -### 6. Dynamic State Sharding and Data Healing - -Shardeum's dynamic state sharding ensures balanced resource usage and prevents bottlenecks. Data integrity across shards is maintained through: - -* **Data Healing:** Nodes periodically compare their state against hashes of data held by other nodes. If discrepancies are detected, nodes request the correct data from their peers and update their state accordingly. This ensures that all nodes maintain a consistent and accurate view of the blockchain state. -* **Efficient Hashing:** Shardeum employs a custom hashing algorithm suitable for a sharded network, allowing efficient verification and repair of data across shards. This hashing ensures that data integrity is maintained even as transactions are distributed and processed across multiple shards. - -![State Healing](/img/new/i50.png) - -### 7. Networking and Gossip Protocol - -Shardeum uses a custom networking library and a gossip protocol to ensure efficient and secure communication between nodes: - -* **Shardeum Net:** This internal protocol handles socket connections between nodes, with optimizations for performance and security. It ensures that messages and transaction data are securely transmitted across the network. -* **Gossip Protocol:** For broadcasting messages efficiently, Shardeum uses a gossip protocol where messages propagate quickly and redundantly across the network. This reduces the chance of missing critical information and ensures that all nodes receive transaction data promptly. - -![Gossip](/img/new/i51.png) - -### 8. Transaction Validation - -Each transaction goes through strict validation rules before being confirmed on the network. This includes checks for transaction integrity, authenticity, and compliance with network rules. - -![Validation](/img/new/i54.png) - -### 9. Consensus on Transaction Validity - -Shardeum's architecture requires that all nodes participating in the consensus process agree on the validity of transactions, ensuring no single node can approve incorrect transactions. - -Shardeum uses a hybrid consensus mechanism combining Proof of Stake (PoS) and Proof of Quorum (PoQ). This approach ensures that transactions are validated by a quorum of nodes that must collectively agree on the transactions. Nodes participate in the consensus process by staking SHM, the native token, and can be penalized by losing their stake if they act maliciously. This staking requirement helps prevent Sybil attacks, where an attacker can flood the network with nodes under their control. - -Although Shardeum processes transactions individually, it still generates blocks at certain intervals to support compatibility with smart contracts. These blocks use timestamps to map transactions deterministically, adding an additional layer of temporal security to transaction processing. - -![Transaction Validity](/img/new/i53.png) - -*/}