codila125/foedus-blockchain repository overview

⁠Foedus Blockchain

Immutable Contract Infrastructure

Features⁠ • Quick Start⁠ • API⁠ • Contracts⁠ • Deploy⁠

⁠Overview

Foedus is a production-ready blockchain platform enabling governments and enterprises to create, manage, and enforce immutable contracts. Built for legislative compliance and corporate accountability, it provides tamper-proof records with full audit trails.

Built for:

• 🏛️ Government Bodies enforcing legislative contracts and public agreements
• 🏢 Enterprises requiring legally binding, immutable contract records
• ⚖️ Regulatory Compliance with transparent, auditable contract histories
• 🤝 Public-Private Partnerships coordinating multi-party agreements

⁠Features

⁠📜 Immutable Contract Records

Every contract, amendment, and approval is permanently recorded on the blockchain. Once committed, records cannot be altered or deleted—ensuring absolute integrity for legal and regulatory purposes.

⁠🏛️ Multi-Party Governance

Support for multiple signatories including government agencies, corporate entities, and authorized representatives. All parties must cryptographically approve before contracts become active.

⁠📋 Milestone-Based Execution

Track contract fulfillment through defined milestones. Each completion requires evidence submission and multi-party approval, creating a verifiable chain of accountability.

⁠🔐 Cryptographic Security

Ed25519 digital signatures and SHA-256 hashing ensure non-repudiation. Every action is cryptographically signed, providing legally defensible proof of authorization.

⁠📊 Complete Audit Trail

Full transaction history accessible for regulatory audits, legal discovery, and compliance verification. Export complete blockchain records on demand.

⁠🚀 Enterprise Deployment

Production-ready Docker deployment with health monitoring, graceful shutdown, and persistent storage. Integrates with existing government and enterprise infrastructure via RESTful API.

⁠Quick Start

⁠Docker (Recommended)

# Pull and run
docker pull codila125/foedus-blockchain:latest
docker run -d -p 3008:3008 --name foedus codila125/foedus-blockchain:latest

# Verify it's running
curl http://localhost:3008/health
# {"status":"ok"}

⁠With Persistent Storage

docker volume create foedus-data
docker volume create foedus-logs

docker run -d \
  --name foedus \
  -p 3008:3008 \
  -p 3009:3009 \
  -p 3010:3010 \
  -v foedus-data:/app/data \
  -v foedus-logs:/var/log/foedus \
  codila125/foedus-blockchain:0.4.0

⁠Build from Source

git clone https://github.com/codila125/foedus-blockchain.git
cd foedus-blockchain
docker build -t foedus-blockchain .
docker run -d -p 3008:3008 --name foedus foedus-blockchain

⁠API Reference

Base URL: http://localhost:3008

⁠Health Check

GET /health

Returns {"status":"ok"} when service is operational.

⁠Wallet Operations

⁠Smart Contract Operations

⁠Blockchain Queries

⁠Smart Contracts

⁠Create a Contract

curl -X POST http://localhost:3008/blockchain/createcontract/{creator_address} \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Infrastructure Development Agreement",
    "description": "Public-private partnership for highway construction",
    "milestones": [
      {
        "title": "Phase 1: Land Acquisition",
        "description": "Complete land acquisition and permits",
        "value": 5000000,
        "due_date": 1762329600
      },
      {
        "title": "Phase 2: Construction",
        "description": "Complete primary construction",
        "value": 25000000,
        "due_date": 1793865600
      }
    ],
    "parties": [
      {"address": "{government_agency}", "role": "REGULATOR"},
      {"address": "{contractor}", "role": "CONTRACTOR"},
      {"address": "{oversight_body}", "role": "ARBITRATOR"}
    ],
    "terms": "Funds released upon milestone approval by all parties"
  }'

⁠Contract Lifecycle

DRAFT → ACTIVE → COMPLETED
   ↓       ↓
   └───────┴──→ CANCELLED

1. DRAFT: Contract proposed, awaiting party approvals
2. ACTIVE: All authorized signatories approved, milestones in progress
3. COMPLETED: All milestones fulfilled and verified
4. CANCELLED: Contract terminated with full audit record

⁠Use Cases

⁠Deployment

⁠Environment Variables

⁠Ports

⁠Health Checks

Docker health checks are built-in:

# Check container health
docker inspect --format='{{.State.Health.Status}}' foedus

⁠Logs

# View logs
docker logs -f foedus

# Access log files (if using volumes)
docker exec foedus cat /var/log/foedus/source.log

⁠Architecture

┌─────────────────────────────────────────────────────────┐
│                      HTTP API (Chi)                     │
│              GET/POST /blockchain/*                     │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────────┐
│                   Blockchain Core                       │
│     UTXO Model • Proof-of-Work • Smart Contracts        │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────────┐
│                   Infrastructure                        │
│       libp2p Network • PebbleDB • Ed25519 Crypto        │
└─────────────────────────────────────────────────────────┘

⁠Technical Specifications

⁠Module Documentation

⁠Testing

Foedus maintains a comprehensive test suite to ensure reliability, correctness, and performance. All tests are run using Go's native testing framework.

⁠Test Suite Summary

⁠Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detector
go test -race ./...

# Run benchmarks
go test -bench=. -benchmem ./...

⁠Test Coverage

⁠Performance Benchmarks

⁠Wallet Operations

⁠Database Operations

⁠Merkle Tree Operations

⁠Network Operations

⁠API Load Testing

Load tests were conducted with 10 concurrent clients over 5 seconds:

⁠Contract Confirmation Metrics

⁠Security Testing

• Race Condition Detection: All tests pass with -race flag enabled
• Cryptographic Validation: Ed25519 signatures and SHA-256 hashing verified
• Serialization Integrity: JSON/Protobuf round-trip tests pass
• Address Format Validation: Base58Check encoding verified

⁠CI/CD

Automated tests run on every push via GitHub Actions:

# .github/workflows/test.yml
- name: Run tests with race detector
  run: go test -race -v ./...
- name: Run benchmarks
  run: go test -bench=. -benchmem -run=^$ ./...

⁠Why Foedus?

⁠Speed: Orders of Magnitude Faster

Foedus achieves sub-millisecond contract confirmation, making it suitable for real-time applications.

⁠Purpose-Built for Contracts

Unlike general-purpose blockchains, Foedus is designed specifically for contract management:

⁠Built-in Milestone Workflow

Ethereum requires writing custom Solidity smart contracts for milestone-based agreements. Foedus provides this functionality out of the box:

DRAFT → ACTIVE → COMPLETED
   ↓       ↓
   └───────┴──→ CANCELLED

⁠ICCT: Incomplete Contract Tracking

Foedus includes a specialized index for fast lookup of active contracts—no full chain scan required.

⁠Hybrid Storage Architecture

⁠Predefined Contract Structure

vs Ethereum's Solidity:

• More secure: No arbitrary code execution
• Simpler: No gas optimization needed
• Predictable: No smart contract vulnerabilities

⁠Lightweight Deployment

Runs on minimal hardware—no mining farms required. Perfect for private/consortium networks.

⁠Support

• Documentation: GitHub Wiki⁠
• Issues: GitHub Issues⁠
• Docker Hub: codila125/foedus-blockchain⁠
• Enterprise Inquiries: Contact for dedicated support and custom deployments

⁠License

MIT License - see LICENSE⁠ for details.

Foedus v0.4.0 — Immutable Contract Infrastructure for Government & Enterprise