Interlock (IL) - Multi-Chain Non-Custodial Escrow

Interlock is a non-custodial escrow API using 2-of-3 threshold cryptography. Parties A and B collaborate with Interlock to lock, release, or refund funds on Bitcoin, Ethereum, and other chains — without any single party holding full custody.

Architecture

                     ┌──────────────┐
                     │   Frontend   │  React + Vite
                     │  (WebSocket) │
                     └──────┬───────┘
                            │
                     ┌──────▼───────┐
                     │   API (Go)   │  Gin HTTP + WebSocket
                     │   /api/v1    │
                     └──┬───┬───┬───┘
                        │   │   │
              ┌─────────┘   │   └─────────┐
              │             │             │
       ┌──────▼──┐   ┌─────▼────┐  ┌─────▼─────┐
       │ Postgres │   │  Redis   │  │   MinIO    │
       │  (data)  │   │ (cache)  │  │  (files)   │
       └─────────┘   └──────────┘  └───────────┘

Key components:

• Threshold Signing (TSS): 2-of-3 Shamir secret sharing for all escrow operations
• Event Sourcing: Full audit trail for every state transition
• Encrypted Messaging: End-to-end encrypted party communication via WebSocket
• Marketplace: Public listing and acceptance of escrow offers
• Webhook System: Event-driven notifications with retry logic

Prerequisites

• Go 1.21+
• Node.js 18+ (for frontend)
• Docker & Docker Compose
• PostgreSQL 15+, Redis 7+, MinIO (all included via Docker Compose)

Quick Start

# Clone and start infrastructure
git clone https://github.com/JeffNeff/interfacechain.git
cd interfacechain
cp .env.example .env          # Edit with your values
cp frontend/.env.example frontend/.env

# Start all services (Postgres, Redis, MinIO) and run migrations
make up

# Seed demo data (optional)
make seed

# Run the API server
make run

# In a separate terminal, run the frontend
make ui

The API will be available at http://localhost:8080 and Swagger docs at http://localhost:8080/swagger/index.html.

Development

make deps           # Download Go dependencies
make build          # Build API binary
make run            # Run API server
make ui             # Build WASM + run frontend dev server
make test           # Run all tests (excluding e2e)
make test-unit      # Run unit tests only
make test-e2e       # Run e2e tests (requires full stack)
make ci             # Run vet + fmt + unit tests
make lint           # Run vet + fmt
make docs           # Regenerate Swagger docs
make seed           # Populate database with demo data

Project Structure

cmd/api/            Main application entrypoint
api/
  handlers/         HTTP handler structs (escrow, auth, marketplace, swap, etc.)
  middleware/       CORS, rate limiting, auth middleware
  models/           Request/response models
internal/
  auth/             JWT token management
  crypto/           AES-256-GCM key encryption
  database/         Repository layer (Postgres)
  escrow/           DKG and signing services
  messaging/        WebSocket hub + file storage (MinIO)
  swap/             Order matching and price oracle
  tss/              Threshold signature ceremony coordinator
  webhook/          Webhook delivery service
  worker/           Background task queue (Redis)
pkg/threshold/      Shamir secret sharing + ECDSA threshold signing
frontend/           React + Vite + TypeScript
migrations/         PostgreSQL schema migrations (up + down)
tests/e2e/          End-to-end API tests
config/             YAML configuration

API Overview

All endpoints are under /api/v1. Authentication uses JWT Bearer tokens.

Method	Endpoint	Auth	Description
POST	/auth/register	No	Register new user
POST	/auth/login	No	Login and get tokens
POST	/auth/refresh	No	Refresh access token
GET	/auth/profile	Yes	Get current user profile
POST	/escrows	Yes	Create escrow (triggers DKG)
GET	/escrows/:id	Yes	Get escrow details
GET	/escrows	Yes	List escrows
POST	/escrows/:id/fund	Yes	Mark escrow as funded
POST	/escrows/:id/release	Yes	Release to Party B (threshold sign)
POST	/escrows/:id/refund	Yes	Refund to Party A (threshold sign)
POST	/escrows/:id/dispute	Yes	Raise a dispute
POST	/escrows/:id/resolve	Yes	Resolve dispute (Interlock admin only)
GET	/marketplace	No	List marketplace listings
POST	/marketplace/:id/accept	Yes	Accept a listing
GET	/swap/pairs	No	Available trading pairs
POST	/swap/create	Yes	Create a swap
GET	/chains	No	Supported blockchains
GET	/health	No	Health check
GET	/ready	No	Readiness check

Full API documentation with request/response schemas is available at /swagger/index.html when the server is running.

Configuration

Configuration is loaded from config/config.yaml with environment variable overrides. See .env.example for all available variables.

Key environment variables:

• JWT_SECRET — Secret for signing JWT tokens (change in production)
• DATABASE_* — PostgreSQL connection settings
• REDIS_* — Redis connection settings
• MINIO_* — MinIO/S3 object storage settings

Docker

# Start infrastructure only
docker compose up -d postgres redis minio

# Start full stack (API + frontend + infra)
docker compose up -d

# Run migrations
make migrate

License

See LICENSE for details.