Especificación Técnica

Resumen Ejecutivo

KodeChain es una blockchain post-cuántica de capa 1 con consenso dual (DPoS/PBFT), máquina virtual completa y criptografía ML-DSA-65. Diseñada para transacciones de alta velocidad y registros críticos inmutables.

Especificaciones Core

Blockchain

Network Name:        KodeChain
Native Currency:     KodeCoin (KDC)
Decimals:            18
Max Supply:          50,000,000 KDC
Block Time (DPoS):   3 seconds
Block Time (PBFT):   Variable (consensus-driven)
TPS Estimated:       ~300 (DPoS), ~50 (PBFT)
Finality:            Immediate (PBFT), Probabilistic (DPoS)

Consensus

DPoS Parameters

Active Delegates:    21 (production) / 7 (development)
Round Length:        21 blocks (63 seconds)
Block Time:          3 seconds
Election Method:     Weighted score (reliability 40%, votes 30%, blocks 20%, stake 10%)
Minimum Stake:       10 KDC
Unbonding Period:    7 days

PBFT Parameters

Consensus Type:      Byzantine Fault Tolerance
Fault Tolerance:     f < n/3
Phases:              Pre-Prepare, Prepare, Commit
View Changes:        Automatic on timeout
Checkpoint Interval: 100 sequences
Timeout:             10 seconds per phase

Cryptography

Signature Algorithm:   ML-DSA-65 (Dilithium3)
Security Level:        NIST Level 3
Classical Security:    ~192 bits
Quantum Security:      ~96 bits
Hash Algorithm:        SHA-256
Public Key Size:       1,952 bytes
Private Key Size:      4,016 bytes
Signature Size:        3,293 bytes

Virtual Machine

Type:                Stack Machine
Word Size:           256 bits
Max Stack Depth:     1024
Max Memory:          16 MB
Max Code Size:       24 KB
Gas Limit (default): 10,000,000
Opcodes:             60+ implemented
ABI Encoding:        Custom (SHA-256 selectors)

Network

P2P Protocol:        Custom over TCP/UDP
DHT:                 Kademlia (k=16, 20 buckets)
NAT Traversal:       Pion ICE + UPnP
Discovery:           UDP broadcasts
Default Ports:
  - P2P TCP:         30303
  - P2P UDP:         30303
  - Discovery UDP:   30301
  - HTTP API:        8545

Estructuras de Datos

Block

type Block struct {
    Index            uint64            // Block height
    Timestamp        string            // RFC3339 format
    Type             BlockType         // DPOS or PBFT
    Transactions     []*Transaction    // List of transactions
    CriticalProcesses []*CriticalProcess // PBFT only
    PreviousHash     string            // SHA-256 hash
    Hash             string            // SHA-256 hash
    Nonce            uint64            // For mining (unused in DPoS/PBFT)
    Signature        string            // ML-DSA-65 signature
    Validator        string            // Validator address
    TotalFees        float64           // Sum of transaction fees
    MerkleRoot       string            // Merkle tree root
    StateRoot        string            // World state root
    Difficulty       int               // Fixed at 1 for DPoS/PBFT
}

Transaction

type Transaction struct {
    Hash      string          // SHA-256 hash
    Type      string          // TRANSFER, DEPLOY_CONTRACT, etc.
    Data      json.RawMessage // Type-specific data
    Timestamp FlexTimestamp   // Unix timestamp or RFC3339
    Signature string          // ML-DSA-65 signature (hex)
    GasLimit  uint64          // Max gas allowed
}

Transaction Types

const (
    TxTransfer          = "TRANSFER"
    TxDeployContract    = "DEPLOY_CONTRACT"
    TxCallContract      = "CALL_CONTRACT"
    TxStake             = "STAKE"
    TxUnstake           = "UNSTAKE"
    TxRegisterValidator = "REGISTER_VALIDATOR"
    TxDelegate          = "DELEGATE"
    TxUndelegate        = "UNDELEGATE"
    TxCriticalRecord    = "CRITICAL_RECORD"  // PBFT only
)

World State

type WorldState struct {
    Accounts   map[string]*Account      // Address → Account
    Contracts  map[string]*Contract     // Address → Contract
    Staking    *StakingState           // Staking info
    Validators *ValidatorSet           // Active validators
    Governance *GovernanceState        // Governance data
    stateRoot  string                  // Merkle Patricia root
}

type Account struct {
    Address  string
    Balance  *big.Int
    Nonce    uint64
    CodeHash string    // For contract accounts
}

Merkle Patricia Trie

type Node interface {
    Hash() string
    Serialize() []byte
}

type LeafNode struct {
    Path  []byte
    Value []byte
}

type ExtensionNode struct {
    SharedNibbles []byte
    Next          Node
}

type BranchNode struct {
    Branches [16]Node  // 16 branches (0-F)
    Value    []byte    // Optional value
}

Consensus Algorithms

DPoS Flow

1. Validators register with 10 KDC stake
   ↓
2. 24-hour activation period
   ↓
3. Selection of 21 active delegates
   ↓
4. Round-robin block production (3s blocks)
   ↓
5. Rewards distribution every round (21 blocks)
   ↓
6. Re-selection every 100 blocks

PBFT Flow

1. Client submits transaction to primary
   ↓
2. Primary broadcasts PRE-PREPARE
   ↓
3. Replicas send PREPARE (need 2f+1)
   ↓
4. Replicas send COMMIT (need 2f+1)
   ↓
5. Execute transaction and update state
   ↓
6. Reply to client

Fee Structure

Transaction Fees

Total Fee = Gas Used × Gas Price

Distribution:
├── Validator: 70% - Burn Rate
├── Development: 30%
└── Burn: 1-10% (dynamic)

Burn Rate

func calculateBurnRate(supply uint64) float64 {
    if supply > 40_000_000 {
        return 0.10  // 10% aggressive
    } else if supply > 20_000_000 {
        return 0.05  // 5% moderate
    } else {
        return 0.01  // 1% minimal
    }
}

Gas Costs

Operation	Gas Cost	Category
ADD, SUB	3	Arithmetic
MUL, DIV	5	Arithmetic
PUSH	3	Stack
POP	2	Stack
MLOAD, MSTORE	3	Memory
SLOAD	800	Storage
SSTORE	20,000	Storage
LOG0	375	Events
LOG1	750	Events
CREATE	32,000	Contract Creation

Storage

LevelDB Schema

Keys:
├── block:[height] → Block JSON
├── tx:[hash] → Transaction JSON
├── state:[address] → Account JSON
├── contract:[address] → Contract Code
├── storage:[contract]:[key] → Storage Value
└── validator:[address] → Validator Info

State Management

// State trie root calculation
root = merklePatriciaTrie.Root()

// Stored in block
block.StateRoot = root

// State verification
if block.StateRoot != calculatedRoot {
    return ErrInvalidStateRoot
}

API Specification

REST Endpoints

Blockchain

GET  /api/blockchain/status
GET  /api/blockchain/blocks
GET  /api/blockchain/blocks/:height
GET  /api/blockchain/latest
GET  /api/blockchain/balance/:address

Transactions

POST /api/transactions/send
GET  /api/transactions/:hash
GET  /api/transactions/pending
POST /api/transactions/estimate-gas

Contracts

POST /api/contracts/deploy
POST /api/contracts/call
GET  /api/contracts/:address
GET  /api/contracts/events/:address

Staking

POST /api/validator/register
POST /api/staking/activate
GET  /api/staking/validators
GET  /api/staking/status/:address
POST /api/staking/delegate

WebSocket Events

ws://localhost:8545/ws

Events:
- new_block
- new_transaction
- validator_update
- delegation_update

Performance Metrics

Expected Performance

TPS (DPoS):              ~300 transactions/second
TPS (PBFT):              ~50 transactions/second
Block Time (DPoS):       3 seconds
Finality (DPoS):         ~30 seconds (10 blocks)
Finality (PBFT):         Immediate (1 block)
Sync Time:               ~30 minutes (full blockchain)
Memory Usage:            ~2 GB (full node)
Disk Usage:              ~10 GB/year (estimated)

Scalability

Current:
├── Single chain
├── ~300 TPS (DPoS)
└── ~50 TPS (PBFT)

Roadmap (Sharding):
├── 10 shards
├── ~3,000 TPS (DPoS)
└── ~500 TPS (PBFT)

Security Considerations

Attack Vectors

1. 51% Attack

• Mitigation: 21 delegates, weighted selection, penalties

2. Double Spending

• Mitigation: PBFT finality, signature verification

3. Sybil Attack

• Mitigation: Stake requirement, reputation system

4. Quantum Attack

• Mitigation: ML-DSA-65 signatures

Penalty System

Minor Offense (0.1% slash):
- Miss 1-3 blocks
- Slow response

Severe Offense (0.3% slash):
- Miss 4-10 blocks
- Invalid transactions

Critical Offense (0.5% slash + ejection):
- Double signing
- Long downtime (> 6 hours)

Upgrade Mechanism

Hard Fork Process

1. KIP Proposal
   ↓
2. Community Discussion (14 days)
   ↓
3. Validator Vote (7 days)
   ↓
4. Implementation (if approved)
   ↓
5. Testnet Deployment
   ↓
6. Mainnet Activation (coordinated)

Soft Fork Process

1. Backward-compatible change
   ↓
2. Deploy to subset of validators
   ↓
3. Monitor for issues
   ↓
4. Gradual rollout

Compliance

Data Privacy

On-Chain Data:      Public
Off-Chain Data:     Optional (IPFS/private storage)
GDPR Compliance:    "Right to be forgotten" via off-chain storage

Regulatory

AML/KYC:            Optional (validator/exchange level)
Securities Law:     Utility token (not security)
Tax Compliance:     Transparent transaction history

References

Standards

• NIST PQC: Post-Quantum Cryptography
• EIP-1559: Fee market (inspiration)
• BIP-32: HD Wallets (roadmap)

Papers

• DPoS: BitShares/EOS whitepapers
• PBFT: "Practical Byzantine Fault Tolerance" (Castro & Liskov, 1999)
• Kademlia: "Kademlia: A Peer-to-peer Information System Based on the XOR Metric" (Maymounkov & Mazières, 2002)

---

KodeChain: Especificación técnica completa v1.0