Architecture and implementation

The Surplus Exchange Protocol has three core components:

Matching Engine

Constructs a directed graph of offerings and needs, then uses cycle detection to find viable exchange chains.

Trust System

Calculates trust scores from identity verification, exchange history, and network position. Enforces graduated exposure for new participants.

Exchange Orchestration

Manages the lifecycle of exchange chains from proposal through completion, tracking confirmation status and satisfaction signals.

Graph Construction

Participants describe:

• Offerings: What they can provide (surplus capacity)
• Needs: What they would value receiving

Each offering-to-need match becomes a directed edge in the graph:

• Node: Participant
• Edge: Potential exchange (from provider to recipient)
• Weight: Match quality score across multiple dimensions (semantic fit, surplus urgency, timing, geographic and sector alignment, relationship diversity)

Cycle Detection

The core algorithm finds cycles — closed loops where value can flow:

A → B → C → D → A

Implementation uses a DFS-based approach with pruning:

• Minimum cycle length: 2 (direct swaps)
• Maximum cycle length: 6 (configurable)
• Edge weight threshold filters weak matches

Constraint Filtering

Before scoring, edges are filtered by hard constraints:

• Geographic exclusions (participant in a region the recipient won't accept)
• Provider experience requirements (minimum completed exchanges)
• Trust threshold (provider's trust score below recipient's minimum)

Filtered edges are eliminated before cycle detection, reducing the search space and ensuring all discovered chains are feasible.

Chain Ranking

Found cycles are ranked by:

1. Average edge weight (composite match quality across all scoring dimensions)
2. Participant trust scores
3. Surplus urgency (time-sensitive surplus prioritised)
4. Relationship diversity (new partner connections preferred)
5. Chain length (shorter preferred for coordination simplicity)
6. Timing feasibility

Key files:

• src/matching/graph.ts — Graph construction
• src/matching/scorer.ts — Multi-dimensional scoring
• src/matching/cycles.ts — Cycle detection
• src/matching/ranking.ts — Chain ranking

Three-Layer Model

Layer 1: Verifiable Identity

• Business registration verification
• Professional body membership
• Domain ownership
• Establishes baseline accountability

Layer 2: Network Position

• Exchange partner count
• Repeat partner rate
• Chain participation history
• Harder to fake than ratings

Layer 3: Mutual Satisfaction

• Satisfaction signals from both sides of each exchange
• Accumulated as track record
• Simple categories: satisfied / partially satisfied / not satisfied

Trust Tiers

Key files:

• src/trust/calculator.ts — Trust score calculation
• src/trust/tiers.ts — Tier classification
• schemas/trust-profile.schema.json — Trust data schema

Current: Human Participants

Phase 1 focuses on human-operated businesses:

• Organisations (LLP, Ltd, sole trader)
• Individuals operating professionally
• Human-initiated offerings and needs
• Human confirmation of exchanges

Future: Agent Integration

The protocol is designed to support AI agent participation:

Phase 2: Delegated Agents

• Agent acts on behalf of known participant
• Human retains authority over commitments
• Agent handles discovery and negotiation

Phase 3: Autonomous Agents

• Agents as first-class participants
• Autonomous offering of agent-native capabilities
• Trust profiles for agents (different signals)

Agent Boundary

SEP is not trying to be an agent protocol. It's an exchange protocol that agents can participate in.

The boundary:

• SEP handles: Matching, trust, exchange orchestration
• External agents handle: Capability execution, decision-making, negotiation style

This means SEP can integrate with MCP, A2A, or other agent protocols rather than competing with them.

Subjective Value Over Shared Currency

Decision: Each participant maintains their own sense of balance. No shared ledger, no network-wide currency.

Rationale: The surplus frame means baseline is "better than nothing." Eliminates valuation disputes while respecting contextual differences.

Trade-off: Harder to track network health metrics. Corporate accounting may need workarounds.

B2B Focus Over Consumer

Decision: Design primarily for business-to-business exchanges, particularly professional services.

Rationale: Businesses have predictable surplus, professional accountability, higher stakes per exchange. Historical evidence shows B2B systems survive where consumer systems fail.

Trade-off: Smaller initial addressable market.

Trust Through Track Record, Not Ratings

Decision: Trust is calculated from exchange history and network position, not user ratings.

Rationale: Ratings are easily gamed. Network position (partner count, repeat rate, chain participation) is harder to fake because it requires actual exchanges.

Trade-off: New participants face cold-start problem (addressed by vouching).

Cycles Over Direct Matching

Decision: Prioritise multi-party chains over direct swaps.

Rationale: Direct matches are rare. The algorithm's value is finding non-obvious paths across the network.

Trade-off: More complex coordination. Chains fail if any participant defaults.

The protocol defines JSON schemas for all data structures:

Schema	Purpose
participant.schema.json	Business identity and profile
capability-offering.schema.json	What a participant can provide
need.schema.json	What a participant wants to receive
exchange-chain.schema.json	A complete chain with edges and status
trust-profile.schema.json	Trust data for a participant
protocol-messages.schema.json	Messages between protocol components

Example: Capability Offering

{
  "id": "offering-001",
  "participant_id": "participant-abc",
  "capability": {
    "category": "professional_services",
    "description": "Contract review for standard commercial agreements",
    "constraints": {
      "max_hours": 8,
      "turnaround_days": 5
    }
  },
  "availability": {
    "valid_from": "2026-03-01",
    "valid_until": "2026-06-30"
  }
}

Repository Structure

surplus-exchange-protocol/
├── src/
│   ├── matching/     ← Start here for algorithm
│   ├── trust/        ← Start here for trust system
│   ├── capability/   ← Capability translation
│   ├── protocol/     ← Exchange lifecycle
│   ├── examples/     ← Runnable demo scripts
│   └── validation/   ← Schema validation
├── schemas/          ← JSON schemas
├── examples/         ← Example data files
└── docs/
    ├── design/       ← Design decisions
    └── specs/        ← Detailed specifications

Running the Demos

# Install dependencies
npm install

# Run matching algorithm demo
npm run match

# Run trust calculation demo
npm run trust

# Run chain tracing demo
npm run trace

# Run capability translation demo (offline, no API key needed)
npm run capability

# Interactive capability translation with AI
npm run capability:live

Key Entry Points

If you want to understand...	Start with...
How matching works	src/matching/cycles.ts
How trust is calculated	src/trust/calculator.ts
How capability translation works	src/capability/index.ts
The data model	schemas/*.schema.json
Design rationale	docs/design/decisions.md
What's still open	docs/design/open-questions.md

What's Working vs What's Open

Working:

• Matching algorithm (multi-dimensional scoring, constraint filtering, ranking)
• Trust calculation (4-tier model with exposure limits)
• Capability translation (offline and live modes)
• Schema validation
• Example data and demos

Open:

• Network deployment (no live infrastructure)
• Agent integration (human-only currently)
• Physical goods handling (schema support only)