Gravity Core Contracts

On-chain infrastructure for the Gravity blockchain — a layered smart contract architecture for staking, governance, and consensus coordination.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         EXTERNAL SYSTEMS                        │
│               (Consensus Engine, VM Runtime, Users)             │
└───────────────────────────────┬─────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Governance  │       │    Oracle     │       │    Blocker    │
│   (Layer 5)   │       │   (Layer 6)   │       │   (Layer 4)   │
└───────┬───────┘       └───────────────┘       └───────┬───────┘
        │                                               │
        └───────────────────────┬───────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│               Staking & Validator Management (L2-3)             │
└───────────────────────────────┬─────────────────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Runtime (Layer 1)                        │
│           Timestamp · Configs · DKG · Epoch Management          │
└───────────────────────────────┬─────────────────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Foundation (Layer 0)                       │
│          SystemAddresses · Types · Errors · AccessControl       │
└─────────────────────────────────────────────────────────────────┘

Quick Start

# Build
forge build

# Test
forge test

# Test with verbosity
forge test -vvv

# Generate genesis.json
./scripts/generate_genesis.sh

Genesis Generation

The genesis-tool generates a complete genesis configuration for the Gravity Chain.

Multi-Node (4 validators)

# Default settings (4 nodes, 2-hour epoch interval)
./scripts/generate_genesis.sh

# Custom epoch interval (e.g., 4 hours)
./scripts/generate_genesis.sh -i 4

# Help
./scripts/generate_genesis.sh --help

Single-Node (1 validator)

# Single node genesis (for local testing)
./scripts/generate_genesis_single.sh

# Single node with custom epoch interval
./scripts/generate_genesis_single.sh -i 1

Options

Option	Description
-i, --interval HOURS	Set epoch interval in hours (default: 2)
-c, --config FILE	Use custom config file
-h, --help	Show help message

Configuration Files

File	Description
genesis-tool/config/genesis_config.json	4-node configuration
genesis-tool/config/genesis_config_single.json	Single-node configuration

Generated files:

• genesis.json — Main genesis file
• output/genesis_accounts.json — Account states
• output/genesis_contracts.json — Contract bytecodes

Documentation

Specification	Description
Overview	Architecture overview and design principles
Foundation	Layer 0: System addresses, types, errors
Runtime	Layer 1: Timestamp, configs, DKG
Staking	Layer 2: StakePool factory, bucket withdrawals
Validator Management	Layer 3: Validator lifecycle, epoch transitions
Blocker	Layer 4: Epoch orchestration, block prologue
Governance	Layer 5: Proposals, voting, execution
Oracle	Layer 6: Cross-chain data, consensus-gated updates
Randomness	VRF configuration and DKG coordination

Project Structure

src/
├── foundation/     # Layer 0: Core types and addresses
├── runtime/        # Layer 1: Timestamp, configs, DKG
├── staking/        # Layer 2: Staking and StakePool
├── blocker/        # Layer 4: Epoch and block management
├── governance/     # Layer 5: On-chain governance
└── oracle/         # Layer 6: External data oracle

genesis-tool/       # Genesis generation tool (Rust)
├── src/            # Rust source code
└── config/         # Genesis configuration files

scripts/
├── generate_genesis.sh  # Genesis generation script
└── helpers/             # Python helper scripts

test/
├── unit/           # Unit tests
├── fuzz/           # Fuzz tests
└── invariant/      # Invariant tests

Design Principles

• Layered Dependencies — Higher layers depend only on lower layers
• Microsecond Time — All timestamps use uint64 microseconds
• Compile-time Addresses — System addresses inlined for gas efficiency
• Epoch-Boundary Updates — Sensitive config changes apply at epoch transitions
• Two-Role Separation — Owner (admin) vs Staker (funds) in StakePools
• Consensus-Gated — Critical state changes require validator consensus

License

See LICENSE for details.