# ebbflow

**Repository Path**: Yi_con/ebbflow

## Basic Information

- **Project Name**: ebbflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ADKR Protocol - Go Implementation

## Overview

This is a Go implementation of the ADKR (Asynchronous Distributed Key Refresh) protocol, providing semantic equivalence with the Python reference implementation. The ADKR protocol enables secure distributed key refresh in asynchronous networks with Byzantine fault tolerance.

## Features

- **Semantic Equivalence**: Fully equivalent to Python reference implementation
- **High Performance**: Optimized Go implementation with concurrent processing
- **Comprehensive Testing**: Extensive test suite including equivalence tests
- **Production Ready**: Complete operational tooling and deployment automation
- **Metrics & Monitoring**: Built-in performance metrics and monitoring capabilities

## Quick Start

### Prerequisites

- Go 1.19 or later
- Linux/macOS environment
- Network connectivity for distributed deployment

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd adkr

# Build the project
go build ./cmd/adkr_node
go build ./cmd/adkr_bench
go build ./cmd/bls_gen
go build ./cmd/config_validator

# Or use the operations manager
./scripts/ops_manager.sh setup
```

### Basic Usage

```bash
# Generate keys for 4 nodes with threshold 3
./scripts/ops_manager.sh generate-keys -n 4 -t 3 -c ./keys

# Validate configuration
./scripts/ops_manager.sh validate -c ./keys

# Run performance benchmark
./scripts/ops_manager.sh benchmark -f -n 4

# Run equivalence tests
./scripts/ops_manager.sh test
```

## Architecture

The ADKR protocol consists of several key components:

- **ACSS (Asynchronous Complete Secret Sharing)**: Secure secret sharing protocol
- **RBC (Reliable Broadcast)**: Reliable message broadcast with multiple variants
- **MVBA (Multi-Valued Byzantine Agreement)**: Consensus protocol for value agreement
- **ABA (Asynchronous Binary Agreement)**: Binary consensus with coin-driven decisions
- **Threshold Common Coin**: Cryptographic coin protocol using BLS threshold signatures
- **Key Refresh**: Distributed key refresh mechanism

## Configuration

### BLS Keys

Generate threshold BLS keys for your deployment:

```bash
./bls_gen -n 4 -t 3 -output ./keys
```

### Hosts Configuration

Configure node network addresses:

```bash
# Template format
0 localhost 8000
1 localhost 8001
2 localhost 8002
3 localhost 8003

# Or JSON format
{
  "hosts": [
    {"node_id": 0, "host": "localhost", "port": 8000},
    {"node_id": 1, "host": "localhost", "port": 8001},
    {"node_id": 2, "host": "localhost", "port": 8002},
    {"node_id": 3, "host": "localhost", "port": 8003}
  ]
}
```

## Deployment

### Single Node Testing

```bash
# Run a single node for testing
./adkr_node -pid 0 -hosts ./keys/hosts.template -key ./keys/bls_keys_node_0.json
```

### Distributed Deployment

```bash
# Deploy all nodes
./scripts/ops_manager.sh deploy -c ./keys

# Start all nodes
./scripts/ops_manager.sh start -c ./keys

# Check status
./scripts/ops_manager.sh status

# Stop all nodes
./scripts/ops_manager.sh stop
```

## Performance Benchmarking

```bash
# Fast mode benchmark (recommended for testing)
./adkr_bench -n 4 -f 1 -fast

# Real mode benchmark (full cryptography)
./adkr_bench -n 4 -f 1

# Custom configuration
./adkr_bench -n 4 -f 1 -mvba-strong-predicate -aba-evidence -rbc-mode dual
```

## Monitoring & Metrics

The implementation provides comprehensive metrics:

- **End-to-end latency**: Total protocol execution time
- **Phase durations**: Time spent in each protocol phase
- **Message counts**: Messages sent and received
- **Timeout statistics**: Retry and timeout information
- **Coin metrics**: Threshold coin protocol performance

Metrics are exported in JSON format for easy integration with monitoring systems.

## Testing

### Equivalence Tests

Verify semantic equivalence with Python implementation:

```bash
# Run simplified parity tests
./parity_simple -output parity_results.json

# Analyze results
python3 parity_analysis.py parity_results.json
```

### Unit Tests

```bash
# Run all tests
go test ./...

# Run specific test packages
go test ./pkg/adkr/...
go test ./pkg/crypto/...
```

## Python Equivalence

This Go implementation maintains semantic equivalence with the Python reference implementation:

- **Protocol Behavior**: Identical protocol execution and decision-making
- **Cryptographic Operations**: Equivalent cryptographic primitives and operations
- **Message Formats**: Compatible message serialization and deserialization
- **Configuration**: Equivalent configuration options and parameters
- **Performance**: Comparable performance characteristics

See [Python Equivalence Guide](docs/PYTHON_EQUIVALENCE.md) for detailed comparison.

## Documentation

- [Python→Go Module Mapping](docs/MODULE_MAPPING.md)
- [Running Instructions](docs/RUNNING_GUIDE.md)
- [Equivalence & Metrics](docs/EQUIVALENCE_METRICS.md)
- [Operations Guide](docs/OPERATIONS_GUIDE.md)
- [API Reference](docs/API_REFERENCE.md)

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run equivalence tests to ensure Python compatibility
6. Submit a pull request

## License

[License information]

## Support

For questions and support:
- Create an issue in the repository
- Check the documentation in the `docs/` directory
- Review the test cases for usage examples