diff --git a/docs/learn/blockchain-basics.md b/docs/learn/blockchain-basics.md new file mode 100644 index 0000000..9c10c08 --- /dev/null +++ b/docs/learn/blockchain-basics.md @@ -0,0 +1,172 @@ +# Blockchain Basics + +This guide introduces fundamental blockchain concepts for newcomers. If you're already familiar with blockchain technology, skip to [XDC Architecture](xdc-architecture.md). + +## What is Blockchain? + +A blockchain is a **distributed digital ledger** that records transactions across many computers. Think of it as a shared spreadsheet that: + +- Everyone can read +- No single person controls +- Cannot be altered once written +- Automatically stays synchronized + +```mermaid +flowchart LR + A[Transaction] --> B[Verification] + B --> C[Block Created] + C --> D[Added to Chain] + D --> E[Distributed to Network] +``` + +## Key Concepts + +### 1. Decentralization + +Instead of one central server (like a bank), blockchain uses many computers (nodes) worldwide: + +| Centralized | Decentralized | +|-------------|---------------| +| Single point of failure | No single point of failure | +| Trust the institution | Trust the protocol | +| Can be censored | Censorship resistant | +| Institution controls data | Users control data | + +### 2. Blocks + +Transactions are grouped into **blocks**. Each block contains: + +- **Transactions**: The actual data being recorded +- **Timestamp**: When the block was created +- **Previous Block Hash**: Links to the prior block +- **Block Hash**: Unique identifier for this block + +``` +┌─────────────────────────────────┐ +│ Block #100 │ +├─────────────────────────────────┤ +│ Previous Hash: 0x7a8b... │ +│ Timestamp: 2024-01-27 10:00:00 │ +│ Transactions: │ +│ - Alice → Bob: 10 XDC │ +│ - Carol → Dave: 5 XDC │ +│ Block Hash: 0x9f3c... │ +└─────────────────────────────────┘ + ↓ +┌─────────────────────────────────┐ +│ Block #101 │ +├─────────────────────────────────┤ +│ Previous Hash: 0x9f3c... │ +│ ... │ +└─────────────────────────────────┘ +``` + +### 3. Cryptographic Hashing + +A **hash** is a unique fingerprint of data. Even a tiny change creates a completely different hash: + +``` +"Hello World" → 0x7f83b... +"Hello World!" → 0x5d41a... (completely different!) +``` + +This makes tampering detectable—changing any transaction would change all subsequent hashes. + +### 4. Consensus + +How do all nodes agree on the "true" state of the blockchain? Through **consensus mechanisms**: + +| Mechanism | How It Works | Example | +|-----------|--------------|---------| +| Proof of Work (PoW) | Solve complex puzzles | Bitcoin | +| Proof of Stake (PoS) | Stake tokens as collateral | Ethereum | +| Delegated PoS (DPoS) | Elected validators | XDC Network | + +XDC uses **XDPoS** (XinFin Delegated Proof of Stake) - more on this in [XDPoS Explained](xdpos-explained.md). + +### 5. Smart Contracts + +**Smart contracts** are programs that run on the blockchain. They: + +- Execute automatically when conditions are met +- Cannot be changed once deployed +- Are transparent and verifiable + +Example: An escrow smart contract that automatically releases payment when goods are delivered. + +```solidity +// Simple smart contract example +contract Escrow { + address buyer; + address seller; + + function releaseFunds() public { + require(goodsDelivered == true); + seller.transfer(amount); + } +} +``` + +### 6. Wallets & Addresses + +A **wallet** stores your private keys. An **address** is your public identifier (like an email address for crypto): + +- **Private Key**: Secret! Never share. Used to sign transactions. +- **Public Key**: Derived from private key. +- **Address**: Derived from public key. Safe to share. + +``` +Private Key → Public Key → Address +(secret) (derived) (share this) + +XDC Address Example: xdc71C7656EC7ab88b098defB751B7401B5f6d8976F +``` + +## Types of Blockchains + +### Public Blockchains +- Anyone can participate +- Fully transparent +- Examples: Bitcoin, Ethereum, XDC Mainnet + +### Private Blockchains +- Permissioned access +- Controlled by organization +- Examples: XDC Private Subnets + +### Consortium Blockchains +- Multiple organizations share control +- Semi-private +- Example: Trade finance networks on XDC + +## Why XDC Network? + +XDC Network combines the best of both worlds: + +| Feature | Benefit | +|---------|---------| +| **Hybrid Architecture** | Public transparency + private options | +| **Enterprise Focus** | Built for trade finance and business | +| **EVM Compatible** | Use existing Ethereum tools | +| **Fast & Cheap** | 2s blocks, < $0.0001 fees | +| **Energy Efficient** | PoS uses 99.9% less energy than PoW | + +## Getting Started + +Ready to explore XDC Network? + +1. **Get a Wallet**: [Set up XDCPay](../xdcchain/developers/wallet-configuration.md) +2. **Get Test XDC**: [Faucet](https://faucet.blocksscan.io) +3. **Explore**: [Block Explorer](https://xdc.blocksscan.io) +4. **Build**: [Developer Quick Start](../xdcchain/developers/quick-guide.md) + +## Next Steps + +- [XDC Architecture](xdc-architecture.md) - Deep dive into XDC's design +- [XDPoS Consensus](xdpos-explained.md) - How XDC achieves consensus +- [Gas & Fees](gas-fees.md) - Understanding transaction costs + +--- + +!!! question "Still have questions?" + Check our [FAQ](faq.md) or ask in [Discord](https://discord.gg/xdc). diff --git a/docs/learn/gas-fees.md b/docs/learn/gas-fees.md new file mode 100644 index 0000000..bd9b85f --- /dev/null +++ b/docs/learn/gas-fees.md @@ -0,0 +1,222 @@ +# Gas & Fees on XDC Network + +Understanding how transaction fees work on XDC Network. + +## Overview + +XDC Network uses a **gas model** similar to Ethereum, but with significantly lower costs. Gas is a unit measuring the computational effort required to execute transactions. + +## Key Concepts + +### Gas vs Gas Price vs Transaction Fee + +``` +Transaction Fee = Gas Used × Gas Price +``` + +| Term | Description | Example | +|------|-------------|---------| +| **Gas** | Computational units required | 21,000 (simple transfer) | +| **Gas Price** | Cost per gas unit (in Gwei) | 0.25 Gwei | +| **Gas Limit** | Max gas you're willing to spend | 100,000 | +| **Transaction Fee** | Actual cost in XDC | 0.00000525 XDC | + +## XDC Network Fee Advantages + +| Metric | XDC Network | Ethereum | Savings | +|--------|-------------|----------|---------| +| Avg Gas Price | 0.25 Gwei | 20-100 Gwei | 80-400x cheaper | +| Simple Transfer | ~$0.00004 | $1-5 | 99%+ | +| Token Transfer | ~$0.0001 | $5-20 | 99%+ | +| Contract Deploy | ~$0.01-0.10 | $50-500 | 99%+ | + +## Gas Costs by Operation + +### Common Operations + +| Operation | Gas Used | Cost (0.25 Gwei) | +|-----------|----------|------------------| +| XDC Transfer | 21,000 | ~$0.00004 | +| XRC20 Transfer | 65,000 | ~$0.00012 | +| XRC20 Approve | 45,000 | ~$0.00008 | +| NFT Transfer | 85,000 | ~$0.00015 | +| Contract Deploy | 500,000-3,000,000 | ~$0.001-0.05 | +| Swap (DEX) | 150,000-300,000 | ~$0.0003-0.0006 | + +### EVM Opcode Costs + +| Opcode | Gas | Description | +|--------|-----|-------------| +| ADD | 3 | Addition | +| MUL | 5 | Multiplication | +| SSTORE (new) | 20,000 | Store new value | +| SSTORE (update) | 5,000 | Update existing value | +| SLOAD | 800 | Load from storage | +| CALL | 700+ | External contract call | +| CREATE | 32,000 | Deploy contract | + +## Setting Gas Price + +### Recommended Gas Prices + +| Speed | Gas Price | Confirmation | +|-------|-----------|--------------| +| 🐢 Low | 0.1 Gwei | ~30 seconds | +| 🚶 Standard | 0.25 Gwei | ~2-4 seconds | +| 🏃 Fast | 0.5 Gwei | ~2 seconds | + +### In Code + +=== "JavaScript (Web3.js)" + ```javascript + const Xdc3 = require('xdc3'); + const xdc3 = new Xdc3('https://rpc.xinfin.network'); + + // Get current gas price + const gasPrice = await xdc3.eth.getGasPrice(); + console.log('Current gas price:', xdc3.utils.fromWei(gasPrice, 'gwei'), 'Gwei'); + + // Send transaction with custom gas price + const tx = await xdc3.eth.sendTransaction({ + from: '0x...', + to: '0x...', + value: xdc3.utils.toWei('1', 'ether'), + gasPrice: xdc3.utils.toWei('0.25', 'gwei'), + gas: 21000 + }); + ``` + +=== "JavaScript (Ethers.js)" + ```javascript + const { ethers } = require('ethers'); + const provider = new ethers.JsonRpcProvider('https://rpc.xinfin.network'); + + // Get fee data + const feeData = await provider.getFeeData(); + console.log('Gas Price:', ethers.formatUnits(feeData.gasPrice, 'gwei'), 'Gwei'); + + // Send transaction + const tx = await wallet.sendTransaction({ + to: '0x...', + value: ethers.parseEther('1'), + gasPrice: ethers.parseUnits('0.25', 'gwei') + }); + ``` + +## Estimating Gas + +Always estimate gas before sending transactions: + +```javascript +// Estimate gas for a transaction +const gasEstimate = await xdc3.eth.estimateGas({ + from: '0x...', + to: contractAddress, + data: contract.methods.transfer(recipient, amount).encodeABI() +}); + +// Add 20% buffer for safety +const gasLimit = Math.ceil(gasEstimate * 1.2); + +console.log('Estimated gas:', gasEstimate); +console.log('Gas limit (with buffer):', gasLimit); +``` + +## Gas Optimization Tips + +### For Users + +1. **Set appropriate gas price**: 0.25 Gwei is usually sufficient +2. **Don't overpay**: XDC has consistent low fees +3. **Batch transactions**: Combine multiple operations when possible +4. **Off-peak times**: Fees are consistently low, but network is fastest during low activity + +### For Developers + +1. **Minimize storage writes** + ```solidity + // Bad: Multiple storage writes + balances[user] = balances[user] + amount; + totalSupply = totalSupply + amount; + + // Good: Batch operations + function batchUpdate(address user, uint256 amount) internal { + balances[user] += amount; + totalSupply += amount; + } + ``` + +2. **Use events instead of storage for historical data** + ```solidity + // Instead of storing all historical values + event Transfer(address indexed from, address indexed to, uint256 value); + ``` + +3. **Pack storage variables** + ```solidity + // Bad: Uses 3 storage slots + uint256 a; + uint256 b; + uint256 c; + + // Good: Pack into fewer slots + uint128 a; + uint128 b; + uint256 c; // 2 slots total + ``` + +4. **Use `calldata` for read-only function parameters** + ```solidity + // Bad + function process(string memory data) public { } + + // Good + function process(string calldata data) public { } + ``` + +## Failed Transactions + +If a transaction fails: + +- Gas used up to the failure point is **still charged** +- Set appropriate gas limits to minimize losses +- Common failure reasons: + - Out of gas + - Contract revert + - Invalid parameters + +```javascript +try { + const tx = await contract.methods.riskyOperation().send({ + from: account, + gas: 500000, + gasPrice: xdc3.utils.toWei('0.25', 'gwei') + }); +} catch (error) { + console.log('Transaction failed:', error.message); + // Gas is still consumed up to failure point +} +``` + +## Network Comparison + +| Network | Avg Tx Fee | TPS | Block Time | +|---------|-----------|-----|------------| +| **XDC Network** | **~$0.00004** | **2,000+** | **2s** | +| Ethereum | $1-50+ | 15-30 | 12s | +| Polygon | ~$0.01 | 7,000 | 2s | +| BSC | ~$0.10 | 160 | 3s | +| Solana | ~$0.00025 | 65,000 | 0.4s | + +## Summary + +- XDC Network offers **99%+ cheaper** fees than Ethereum +- Standard gas price: **0.25 Gwei** +- Simple transfer: **~$0.00004** +- Always estimate gas before sending +- Optimize contracts to minimize gas usage + +--- + +!!! tip "Calculate Your Costs" + Use the [XDC Gas Station](https://xdc.blocksscan.io/gastracker) to check current network gas prices. diff --git a/docs/learn/glossary.md b/docs/learn/glossary.md new file mode 100644 index 0000000..152aa18 --- /dev/null +++ b/docs/learn/glossary.md @@ -0,0 +1,253 @@ +# Glossary + +A comprehensive glossary of terms used in XDC Network documentation. + +## A + +### Address +A unique identifier on the blockchain, derived from a public key. XDC addresses can be displayed in two formats: +- **0x format**: `0x71C7656EC7ab88b098defB751B7401B5f6d8976F` +- **xdc format**: `xdc71C7656EC7ab88b098defB751B7401B5f6d8976F` + +### ABI (Application Binary Interface) +A JSON specification that defines how to interact with a smart contract's functions and data structures. + +### Apothem +The primary testnet for XDC Network. Used for development and testing before mainnet deployment. + +### Archive Node +A full node that stores all historical blockchain states, not just the latest state. + +## B + +### Block +A collection of transactions that are bundled together and added to the blockchain. + +### Block Explorer +A web application that allows users to view blockchain data including transactions, addresses, and blocks. Examples: BlocksScan, XDCScan. + +### Block Height +The number of blocks in the chain from the genesis block to the current block. + +### Block Time +The average time between new blocks. XDC has a ~2 second block time. + +### BFT (Byzantine Fault Tolerant) +A consensus property ensuring the network functions correctly even if some nodes are malicious or faulty. + +## C + +### Chain ID +A unique identifier for a blockchain network. XDC Mainnet is 50, Apothem is 51. + +### Checkpoint +A snapshot of subnet state that is anchored to the XDC mainnet for security. + +### Consensus +The mechanism by which nodes agree on the current state of the blockchain. + +### Contract Address +The address where a smart contract is deployed on the blockchain. + +## D + +### DApp (Decentralized Application) +An application that runs on a decentralized blockchain network rather than centralized servers. + +### DeFi (Decentralized Finance) +Financial services built on blockchain technology without traditional intermediaries. + +### Delegated Proof of Stake (DPoS) +A consensus mechanism where token holders vote for validators to secure the network. + +## E + +### Epoch +A fixed period of blocks (900 blocks on XDC) after which validator sets may change. + +### EVM (Ethereum Virtual Machine) +The runtime environment for smart contracts. XDC is EVM-compatible. + +## F + +### Finality +The guarantee that a transaction cannot be reversed. XDC achieves instant finality through BFT consensus. + +### Fork +A change in blockchain protocol or a split in the chain history. + +### Full Node +A node that stores the complete blockchain and validates all transactions. + +## G + +### Gas +A unit measuring computational effort required to execute operations on the blockchain. + +### Gas Limit +The maximum amount of gas a user is willing to spend on a transaction. + +### Gas Price +The amount of XDC (in Gwei) paid per unit of gas. Determines transaction priority. + +### Genesis Block +The first block in a blockchain (block 0). + +### Gwei +A denomination of XDC. 1 XDC = 1,000,000,000 Gwei. + +## H + +### Hash +A fixed-length cryptographic fingerprint of data. Used extensively in blockchain for security. + +### Hot Wallet +A wallet connected to the internet, used for frequent transactions. + +## I + +### ISO 20022 +An international standard for financial messaging that XDC Network supports. + +## K + +### KYC (Know Your Customer) +Identity verification process required for regulatory compliance. + +## L + +### Layer 1 (L1) +The base blockchain network. XDC Mainnet is a Layer 1. + +### Layer 2 (L2) +Solutions built on top of L1 to improve scalability. XDC Subnets can function as L2. + +### Liquidity +The ease with which an asset can be bought or sold without affecting its price. + +## M + +### Mainnet +The primary public XDC blockchain network where real transactions occur. + +### Masternode +A validator node on XDC Network that requires 10M XDC stake and participates in consensus. + +### Mempool +A waiting area for unconfirmed transactions before they're included in a block. + +### Mnemonic / Seed Phrase +A series of words (usually 12 or 24) that can recover a wallet's private keys. + +## N + +### Node +A computer running blockchain software that maintains a copy of the ledger. + +### Nonce +A number used once in transaction ordering to prevent replay attacks. + +## O + +### Oracle +A service that provides external data to smart contracts. + +## P + +### Private Key +A secret cryptographic key that proves ownership of an address. Never share this! + +### Proof of Stake (PoS) +A consensus mechanism where validators are chosen based on their token stake. + +### Protocol +The rules governing how the blockchain operates. + +### Public Key +A cryptographic key derived from the private key, used to generate addresses. + +## R + +### RPC (Remote Procedure Call) +An API protocol for interacting with blockchain nodes. + +### RWA (Real-World Assets) +Physical or financial assets tokenized on the blockchain. + +## S + +### Slashing +Penalty mechanism that reduces a validator's stake for misbehavior. + +### Smart Contract +Self-executing code deployed on the blockchain that runs when conditions are met. + +### Solidity +The primary programming language for EVM smart contracts. + +### Staking +Locking tokens to participate in network security and earn rewards. + +### Standby Node +A node ready to become a Masternode if an active one fails. + +### Subnet +A separate blockchain network connected to XDC mainnet. + +## T + +### Testnet +A blockchain network for testing, using valueless tokens. + +### Token +A digital asset created on a blockchain using smart contracts (e.g., XRC20 tokens). + +### Transaction +A signed message that transfers value or interacts with a smart contract. + +### Transaction Fee +The cost paid in XDC to execute a transaction. + +### TVL (Total Value Locked) +The total value of assets deposited in DeFi protocols. + +### TPS (Transactions Per Second) +A measure of blockchain throughput. XDC supports 2,000+ TPS. + +## V + +### Validator +A node that participates in consensus by proposing and validating blocks. + +## W + +### Wallet +Software or hardware that stores private keys and allows interaction with the blockchain. + +### Web3 +The concept of a decentralized internet built on blockchain technology. + +### Wei +The smallest denomination of XDC. 1 XDC = 10^18 Wei. + +## X + +### XDC +The native token of XDC Network, used for transactions, staking, and governance. + +### XDPoS +XinFin Delegated Proof of Stake - XDC Network's consensus mechanism. + +### XRC20 +XDC's fungible token standard, equivalent to Ethereum's ERC20. + +### XRC721 +XDC's non-fungible token (NFT) standard, equivalent to Ethereum's ERC721. + +### XDC Zero +Cross-chain bridge technology connecting XDC mainnet with subnets. + +--- + +!!! note "Missing a term?" + Suggest additions by editing this page on [GitHub](https://github.com/XinFinOrg/Docs/edit/main/docs/learn/glossary.md). diff --git a/docs/learn/index.md b/docs/learn/index.md new file mode 100644 index 0000000..35f4b61 --- /dev/null +++ b/docs/learn/index.md @@ -0,0 +1,104 @@ +# Learn XDC Network + +Welcome to the XDC Network learning center! Whether you're new to blockchain or an experienced developer, this section will help you understand XDC Network's technology and capabilities. + +## Learning Paths + +
+ +- :material-school:{ .lg .middle } **Blockchain Beginner** + + --- + + New to blockchain? Start here to understand the fundamentals. + + [:octicons-arrow-right-24: Blockchain Basics](blockchain-basics.md) + +- :material-developer-board:{ .lg .middle } **Developer** + + --- + + Ready to build? Learn XDC architecture and start coding. + + [:octicons-arrow-right-24: XDC Architecture](xdc-architecture.md) + +- :material-server:{ .lg .middle } **Node Operator** + + --- + + Want to run infrastructure? Understand consensus and nodes. + + [:octicons-arrow-right-24: XDPoS Consensus](xdpos-explained.md) + +- :material-briefcase:{ .lg .middle } **Enterprise** + + --- + + Evaluating XDC for business? Learn about enterprise features. + + [:octicons-arrow-right-24: Enterprise Overview](../enterprise/index.md) + +
+ +## Quick Facts + +| Metric | Value | +|--------|-------| +| **Consensus** | XDPoS 2.0 (Delegated Proof of Stake) | +| **Block Time** | ~2 seconds | +| **Finality** | Instant (1-2 blocks) | +| **TPS** | 2,000+ transactions per second | +| **Transaction Cost** | < $0.0001 | +| **EVM Compatible** | Yes (Solidity, Web3, Ethers.js) | +| **Token Standard** | XRC20, XRC721, XRC1155 | +| **Mainnet Launch** | 2019 | + +## Topics + +### Fundamentals +- [Blockchain Basics](blockchain-basics.md) - What is blockchain and how does it work? +- [XDC Architecture](xdc-architecture.md) - How XDC Network is designed +- [XDPoS Consensus](xdpos-explained.md) - Understanding XDC's consensus mechanism + +### Economics +- [Gas & Fees](gas-fees.md) - How transaction costs work on XDC +- [Tokenomics](tokenomics.md) - XDC token distribution and economics + +### Technical +- [Security Model](security.md) - How XDC secures the network +- [Glossary](glossary.md) - Key terms and definitions + +### Help +- [FAQ](faq.md) - Frequently asked questions + +## XDC vs Other Blockchains + +| Feature | XDC | Ethereum | Solana | Polygon | +|---------|-----|----------|--------|---------| +| TPS | 2,000+ | ~15-30 | ~65,000 | ~7,000 | +| Block Time | 2s | ~12s | ~0.4s | ~2s | +| Tx Cost | < $0.0001 | $1-50+ | ~$0.00025 | ~$0.01 | +| Finality | Instant | ~12 min | ~12s | ~2 min | +| EVM Compatible | ✅ | ✅ | ❌ | ✅ | +| Enterprise Focus | ✅ | ❌ | ❌ | ⚠️ | +| ISO 20022 | ✅ | ❌ | ❌ | ❌ | + +## Video Tutorials + +!!! info "Coming Soon" + Video tutorials are being developed. In the meantime, check out: + + - [XDC Network YouTube](https://youtube.com/@xaboratory) + - [Developer Workshops](https://xdc.dev) + +## Community Resources + +- **Discord**: [Join XDC Discord](https://discord.gg/xdc) +- **Telegram**: [XDC Talk](https://t.me/xinfintalk) +- **Forum**: [XDC.dev](https://xdc.dev) +- **Reddit**: [r/xinfin](https://reddit.com/r/xinfin) + +--- + +!!! tip "Stuck?" + Can't find what you're looking for? Ask in our [Discord](https://discord.gg/xdc) or check the [FAQ](faq.md). diff --git a/docs/learn/xdc-architecture.md b/docs/learn/xdc-architecture.md new file mode 100644 index 0000000..f7a8257 --- /dev/null +++ b/docs/learn/xdc-architecture.md @@ -0,0 +1,258 @@ +# XDC Network Architecture + +This document explains the technical architecture of XDC Network, including its hybrid design, consensus mechanism, and key components. + +## Overview + +XDC Network is an **enterprise-grade hybrid blockchain** that combines: + +- **Public Network**: Open, permissionless mainnet +- **Private Subnets**: Permissioned networks for enterprises +- **Interoperability**: Cross-chain communication between networks + +```mermaid +flowchart TB + subgraph "XDC Ecosystem" + subgraph "Public Layer" + A[XDC Mainnet] + B[108 Masternodes] + end + + subgraph "Private Layer" + C[Enterprise Subnet 1] + D[Enterprise Subnet 2] + end + + subgraph "Bridge Layer" + E[XDC Zero] + F[Checkpoint Contract] + end + end + + B --> A + C --> F + D --> F + F --> A + E --> A + E --> C + E --> D +``` + +## Network Layers + +### Layer 1: XDC Mainnet + +The public XDC mainnet is the foundation: + +| Component | Description | +|-----------|-------------| +| **Chain ID** | 50 (Mainnet), 51 (Apothem Testnet) | +| **Consensus** | XDPoS 2.0 | +| **Block Time** | ~2 seconds | +| **Validators** | 108 Masternodes | +| **EVM Version** | Shanghai (latest) | + +### Layer 2: Private Subnets + +Enterprise-specific chains with: + +- Custom consensus parameters +- Permissioned access +- Data privacy +- Mainnet checkpointing + +### Bridge Layer + +- **XDC Zero**: Cross-chain asset transfers +- **Checkpoint Contract**: Subnet state anchoring + +## Consensus: XDPoS 2.0 + +XDC uses **XinFin Delegated Proof of Stake (XDPoS)** version 2.0: + +### How It Works + +1. **Token Holders** stake XDC to vote for Masternode candidates +2. **Top 108 Candidates** become active Masternodes +3. **Masternodes** take turns proposing blocks (round-robin) +4. **Validators** sign blocks to confirm +5. **Rewards** distributed to Masternodes and voters + +### Key Features + +```mermaid +flowchart LR + A[XDPoS 2.0] --> B[BFT Finality] + A --> C[Forensic Monitoring] + A --> D[Penalty Mechanism] + + B --> E[Instant Finality] + C --> F[Detect Misbehavior] + D --> G[Slash Bad Actors] +``` + +| Feature | Description | +|---------|-------------| +| **BFT Finality** | Byzantine Fault Tolerant consensus for instant finality | +| **Forensic Monitoring** | Detects and records malicious validator behavior | +| **Slashing** | Penalties for misbehaving validators | +| **Epoch System** | 900-block epochs for validator rotation | + +### Validator Requirements + +| Requirement | Mainnet | Testnet | +|-------------|---------|---------| +| Minimum Stake | 10,000,000 XDC | 10,000 XDC | +| Hardware | 16GB RAM, 500GB SSD | 8GB RAM, 100GB SSD | +| Bandwidth | 100 Mbps | 50 Mbps | +| Uptime | 99.9%+ expected | - | + +## Node Types + +### Masternode (Validator) +- Proposes and validates blocks +- Requires 10M XDC stake +- Earns block rewards + +### Standby Node +- Ready to become Masternode +- Maintains full chain state +- Can be promoted if Masternode fails + +### Full Node +- Stores complete blockchain +- Serves RPC requests +- No staking required + +### Archive Node +- Stores all historical states +- Required for block explorers +- Higher storage requirements + +## EVM Compatibility + +XDC is fully **Ethereum Virtual Machine (EVM) compatible**: + +### Supported Tools + +| Category | Tools | +|----------|-------| +| **Languages** | Solidity, Vyper | +| **Frameworks** | Hardhat, Truffle, Foundry | +| **Libraries** | Web3.js, Ethers.js, xdc3.js | +| **Wallets** | MetaMask, XDCPay | +| **IDEs** | Remix, VS Code | + +### Migration from Ethereum + +```javascript +// Ethereum code works on XDC with minimal changes + +// Change 1: RPC endpoint +const web3 = new Web3('https://rpc.xinfin.network'); // XDC mainnet + +// Change 2: Address format (optional) +// Ethereum: 0x71C765... +// XDC: xdc71C765... (just prefix change) + +// Everything else works the same! +const contract = new web3.eth.Contract(ABI, address); +``` + +## Transaction Lifecycle + +```mermaid +sequenceDiagram + participant User + participant Node + participant Mempool + participant Validator + participant Network + + User->>Node: Submit Transaction + Node->>Node: Validate Tx + Node->>Mempool: Add to Mempool + Validator->>Mempool: Select Transactions + Validator->>Validator: Create Block + Validator->>Network: Propose Block + Network->>Network: Validate & Sign + Network->>User: Transaction Confirmed (~2s) +``` + +### Transaction Finality + +| Stage | Time | Description | +|-------|------|-------------| +| Submitted | 0s | Tx sent to node | +| Pending | 0-2s | In mempool, awaiting inclusion | +| Included | 2s | In a block | +| **Final** | 2-4s | BFT finality achieved | + +## Smart Contract Execution + +### Gas Model + +XDC uses a gas model similar to Ethereum: + +``` +Transaction Cost = Gas Used × Gas Price + +Example: +- Simple transfer: 21,000 gas +- Gas price: 0.25 Gwei +- Cost: 21,000 × 0.25 Gwei = 5,250 Gwei ≈ $0.00004 +``` + +### Contract Limits + +| Parameter | Value | +|-----------|-------| +| Block Gas Limit | 420,000,000 | +| Max Contract Size | 24 KB | +| Max Call Depth | 1024 | + +## Security Model + +### Network Security + +- **108 Validators**: Distributed consensus +- **10M XDC Stake**: Economic security +- **Slashing**: Penalties for misbehavior +- **Forensic Monitoring**: Behavior tracking + +### Cryptography + +- **Signing**: ECDSA (secp256k1) +- **Hashing**: Keccak-256 +- **Addresses**: 20-byte derived from public key + +## Network Parameters + +### Mainnet + +| Parameter | Value | +|-----------|-------| +| Chain ID | 50 | +| Native Token | XDC | +| Block Time | ~2 seconds | +| Epoch Length | 900 blocks | +| RPC | https://rpc.xinfin.network | +| Explorer | https://xdc.blocksscan.io | + +### Apothem Testnet + +| Parameter | Value | +|-----------|-------| +| Chain ID | 51 | +| Native Token | TXDC (test) | +| Block Time | ~2 seconds | +| RPC | https://rpc.apothem.network | +| Explorer | https://apothem.blocksscan.io | +| Faucet | https://faucet.blocksscan.io | + +## Next Steps + +- [XDPoS Consensus Deep Dive](xdpos-explained.md) +- [Gas & Fees](gas-fees.md) +- [Run a Node](../xdcchain/developers/node_operators/masternode.md) +- [Deploy Smart Contracts](../smartcontract/deployment-verification.md)