Documentation Dependency Framework

FURPS+ Requirements with Executable Specifications

A comprehensive guide to specification-driven documentation for decentralized systems

Overview

This framework integrates two powerful approaches to technical specification:

FURPS+ — A structured requirements classification ensuring comprehensive coverage
Executable Specifications — Code-as-specification enabling precise behavior definition and automated test generation

Together, they create a documentation ecosystem where specifications are simultaneously complete (covering all requirement domains), precise (expressed as runnable code), testable (generating verification fixtures), and traceable (linking requirements through to compliance evidence).

Framework Structure

Requirements Layer (FURPS+)

These categories ensure no requirement domain is overlooked:

Document	Description
Functionality	Core protocol operations, features, security mechanisms
Usability	Developer experience, API ergonomics, error clarity
Reliability	Availability, recovery, safety guarantees, liveness
Performance	Throughput, latency, gas costs, finality time
Supportability	Upgradability, monitoring, fork management
Constraints (+)	Consensus, decentralization, interface requirements

Canonical Specification Layer

The dual-specification model that enables both human understanding and machine precision:

Document	Description
Prose Specification	Human-readable requirements with rationale and FURPS+ structure
Executable Specification	Code-as-spec defining exact behavior, generating tests

Generated Artifacts Layer

Artifacts produced directly from the executable specification:

Document	Description
Test Fixtures	JSON test vectors generated from executable spec
Reference Implementation	Canonical implementation derived from executable spec

Implementation Layer

Multiple independent implementations achieving consensus through shared specification:

Document	Description
Client Implementations	Independent clients deriving from executable spec

Integration Layer

Documents enabling system integration per specification:

Document	Description
API Documentation	Programmatic interfaces from spec-defined contracts
Protocol Documentation	Wire formats and communication contracts
Data Schemas	Formal structure definitions (SSZ, RLP, etc.)

Consumer Layer

Documents helping developers build on the system:

Document	Description
SDK Guides	Language-specific bindings for spec-defined interfaces
Developer Guides	Task-oriented guidance for building applications
Tutorials	Hands-on learning experiences
Reference Manuals	Comprehensive lookup with spec traceability

Validation Layer

Documents verifying and evidencing specification compliance:

Document	Description
Conformance Tests	Executable verification against spec-generated fixtures
Compliance Matrix	Systematic mapping of requirements to verification
Audit Trails	Evidence of compliance over time

Community Layer

Documents governing participation and evolution:

Document	Description
EIPs and RFCs	Proposals with executable spec implementations
Contribution Guidelines	How to participate while maintaining compliance
Changelogs	Fork history and specification evolution

The Dependency Flow

┌─────────────────────────────────────────────────────────────┐
│                    FURPS+ REQUIREMENTS                       │
│  Functionality │ Usability │ Reliability │ Performance │ +  │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              CANONICAL SPECIFICATION LAYER                   │
│                                                              │
│   ┌─────────────────┐         ┌─────────────────┐           │
│   │  PROSE SPEC     │◄───────►│ EXECUTABLE SPEC │           │
│   │  Requirements   │         │  Python Code    │           │
│   │  Rationale      │         │  State Machines │           │
│   │  Constraints    │         │  Fork Snapshots │           │
│   └─────────────────┘         └────────┬────────┘           │
└────────────────────────────────────────┼────────────────────┘
                                         │
                    ┌────────────────────┼────────────────────┐
                    │                    │                    │
                    ▼                    ▼                    ▼
             ┌───────────┐        ┌───────────┐        ┌───────────┐
             │   Test    │        │ Reference │        │  Client   │
             │ Fixtures  │        │   Impl    │        │  Impls    │
             └─────┬─────┘        └───────────┘        └───────────┘
                   │                                         ▲
                   └──────────── validates ──────────────────┘

Key Principles

Dual Specification: Prose for humans, executable for machines—kept in sync
Generated Tests: Test fixtures flow from executable spec, not written manually
Multi-Client Consensus: Multiple implementations validate against same fixtures
FURPS+ Completeness: Structured categories prevent requirement blindspots
Blockchain Augmentation: Safety, liveness, finality, consensus as first-class concerns
Proposal = Implementation: EIPs/RFCs require executable spec code, not just prose

Explorer