# Meridian Protocol

**The Monetary Operating System for Programmable Money**

Meridian is a protocol standard, compliance engine, and programmable settlement network that enables any regulated entity to issue their own token, denominated in any sovereign currency, backed by their own reserves, and interoperable with every other token in the network.

## Overview

Think of Meridian as "Visa for programmable money." Visa doesn't issue every card — it sets the rules that card issuers follow. Meridian doesn't issue every token — it sets the standard that token issuers meet.

### The Stack

- **Layer 0**: Amitis Network (live L1 blockchain)
- **Layer 1**: MeridianToken Standard (ERC-20 base with compliance)
- **Layer 2**: Compliance Engine (KYC, sanctions, AML)
- **Layer 3**: ReserveAggregator (multi-custodian attestation)
- **Layer 4**: Cross-Currency Settlement (atomic swaps)
- **Layer 5**: Programmable Logic Layer (conditional payments)

## Key Features

### 🏛️ Multi-Custodian Reserve Proof
- **Tier-1 Banks**: Chainlink PoR integration
- **Crypto Custodians**: On-chain push attestation
- **Fund Administrators**: Signed oracle attestation
- **102% minimum collateralization** enforced on-chain

### 🛡️ Built-in Compliance
- **KYC Whitelisting**: 3-tier system (Basic/Enhanced/Institutional)
- **Real-time Sanctions Screening**: OFAC/EU/UN lists
- **AML Velocity Limits**: Daily/monthly transaction caps
- **Automatic Reporting**: CTR/SAR threshold triggers

### 🌐 Interoperable Ecosystem
- **meridian.gbp** ↔ **meridian.usd** atomic swaps
- **Cross-chain deployment** (Amitis + Ethereum)
- **5bps swap fees** via Amitis native DEX

## Contract Architecture

```
MeridianToken.sol
├── Compliance.sol (KYC/AML/Sanctions)
├── ReserveAggregator.sol (Multi-custodian proof)
└── Interfaces/
    ├── ICompliance.sol
    └── IReserveAggregator.sol
```

### Core Contracts

#### MeridianToken
The base ERC-20 token implementing the Meridian Protocol Standard:
- Mint/burn gated by N-of-M custodian signatures
- Reserve check on every mint via ReserveAggregator
- Compliance checks on every transfer
- Daily mint/burn limits with admin controls

#### ReserveAggregator
Multi-custodian reserve attestation system:
- Supports 3 custodian types (bank/crypto/fund admin)
- Staleness checks with configurable heartbeat
- Live collateralization ratio calculation
- Chainlink PoR integration for institutional custodians

#### Compliance
KYC, sanctions, and AML enforcement:
- 3-tier KYC system with automatic limit assignment
- Real-time sanctions list updates
- Velocity tracking with automatic resets
- AML reporting threshold monitoring

## Installation

```bash
# Clone repository
git clone https://gittea.979labs.com/amitis55/Meridian.git
cd Meridian

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your API keys and private keys

# Compile contracts
npm run compile

# Run tests
npm run test
```

## Deployment

### Local Development
```bash
# Start Hardhat node
npx hardhat node

# Deploy to localhost
npm run deploy
```

### Testnet Deployment
```bash
# Deploy to Sepolia
npm run deploy:sepolia

# Deploy to Amitis testnet
npm run deploy:amitis
```

### Mainnet Deployment
```bash
# Deploy to Ethereum mainnet
npm run deploy:mainnet

# Deploy to Amitis mainnet
npm run deploy:amitis
```

## Usage Examples

### Issuing a New Token

```javascript
// Deploy core contracts
const compliance = await Compliance.deploy(admin);
const reserveAggregator = await ReserveAggregator.deploy(admin);

// Deploy meridian.usd token
const musd = await MeridianToken.deploy(
    "Meridian USD",
    "MUSD", 
    "USD",
    "HSBC Bank",
    reserveAggregator.address,
    compliance.address,
    admin
);
```

### Adding Custodians

```javascript
// Add Anchorage as crypto custodian
const custodianId = ethers.utils.keccak256(ethers.utils.toUtf8Bytes("anchorage-usd"));
await reserveAggregator.addCustodian(
    custodianId,
    "Anchorage Digital USD",
    anchorageOracleAddress,
    3600, // 1 hour heartbeat
    1     // crypto custodian type
);

// Add Bank of America as bank custodian (Chainlink PoR)
await reserveAggregator.addCustodian(
    bankCustodianId,
    "Bank of America USD",
    chainlinkPorFeedAddress,
    86400, // 24 hour heartbeat
    0      // bank custodian type
);
```

### Minting Tokens

```javascript
// Whitelist recipient
await compliance.whitelistAddress(recipient, 2, "US", 0);

// Attest reserves first
await reserveAggregator.attestReserves(
    custodianId,
    ethers.utils.parseEther("1020000"), // $1.02M reserves
    documentHash
);

// Mint $1M tokens (102% collateralized)
await musd.mint(
    recipient,
    ethers.utils.parseEther("1000000"),
    attestationHash
);
```

### Cross-Currency Swaps

```javascript
// Atomic swap MGBP → MUSD via Amitis DEX
const amountIn = ethers.utils.parseEther("1000"); // 1,000 GBP
const amountOutMin = ethers.utils.parseEther("1200"); // ~1,200 USD

await amitisRouter.swapExactTokensForTokens(
    amountIn,
    amountOutMin,
    [mgbp.address, musd.address],
    recipient,
    deadline
);
```

## Fee Structure

| Operation | Fee | Notes |
|-----------|-----|-------|
| Initial mint | 1.00% | One-time onboarding |
| Subsequent mints | 50bps | ~30bps net after custody |
| Reserve maintenance | 30bps/year | On outstanding supply |
| Cross-currency swap | 5bps | Via Amitis DEX |
| Protocol licence | $25K-$20M/year | By issuer tier |

## Regulatory Framework

### Entity Structure
- **Meridian Protocol Foundation** (Cayman) — IP, governance
- **Meridian EMI Ltd** (UK) — FCA EMI authorised
- **Meridian MENA Ltd** (ADGM) — FSRA regulated
- **Meridian Asia Pte Ltd** (Singapore) — MAS MPI

### Custody Partners
- **US**: Anchorage Digital Bank (OCC Charter)
- **UK**: Barclays / HSBC (FCA authorised)
- **EU**: Fireblocks + EU bank (MiCA CASP)
- **UAE**: Copper / ADGM bank (FSRA)
- **Singapore**: BitGo (MAS licensed)
- **Japan**: SBI Digital Asset Holdings (FSA)

## Development Roadmap

### Phase 1: Foundation (Q1 2026)
- [x] Core contract development
- [x] Testnet deployment
- [ ] Chainlink PoR integration
- [ ] Initial custodian onboarding

### Phase 2: Launch (Q2 2026)
- [ ] FCA EMI licence approval
- [ ] meridian.gbp mainnet launch
- [ ] Anchorage partnership
- [ ] Reserve dashboard

### Phase 3: Expansion (Q3-Q4 2026)
- [ ] meridian.usd launch
- [ ] MiCA passport activation
- [ ] Third-party issuer onboarding
- [ ] Cross-chain bridges

## Security

### Audits
- [ ] Code4rena audit (planned Q1 2026)
- [ ] Trail of Bits security review (planned Q1 2026)
- [ ] Quantstamp formal verification (planned Q2 2026)

### Access Controls
- **Multi-sig required** for all admin functions
- **Time delays** on critical parameter changes
- **Emergency pause** capability
- **Role-based permissions** with least privilege

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Testing

```bash
# Run all tests
npm run test

# Run specific test suite
npx hardhat test test/MeridianToken.test.js

# Run with coverage
npx hardhat coverage
```

## Documentation

- **Whitepaper**: [Meridian Protocol v2.0](docs/whitepaper.pdf)
- **Technical Docs**: [Architecture Overview](docs/architecture.md)
- **API Reference**: [Contract Documentation](docs/api.md)

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contact

- **Email**: tech@meridian.network
- **Twitter**: [@MeridianMoney](https://twitter.com/meridianmoney)
- **Discord**: [Meridian Community](https://discord.gg/meridian)
- **Website**: [meridian.network](https://meridian.network)

---

**The future of money is programmable. The future of programmable money is Meridian.**