Financial Data Protocol

Financial Data Protocol (FDP) is infrastructure for registering and tracing exact financial source materials across business systems.

FDP answers questions such as:

• What exact bytes were registered?
• Which business Artifact refers to those bytes?
• Which immutable Package Revision was used?
• Which system declared a transfer, disclosure, or use?
• Can the retrieved bytes still be verified against their registered identity?

FDP records structure, identity, integrity, provenance, visibility, and immutable history. The business system that declares a material remains responsible for its business meaning and truth.

Current deployment profile

The current FDP product provides Central FDP: a shared service with Registry Spaces, PostgreSQL Registry storage, S3-compatible Content custody, authenticated transports, and a typed client. The previously described Embedded/local warehouse profile is not part of the current product surface.

The Central capability milestones are incremental:

C0 protocol records and schemas
  -> C1 custody and transaction contract
  -> C2 durable Registry, object custody, and typed client
  -> C3 immutable finance handoffs
  -> C4 disclosure and evidence references
  -> C5 one-writer Space authority cutover
  -> C6 global physical Blob deduplication

See docs/central-capabilities.md for the implementation details of these milestones. Version history belongs in CHANGELOG.md.

Current Central interface

The current packaged command is fdp-central. Its commands are:

fdp-central serve
fdp-central init-db
fdp-central blob-sweep --month 2026-08

The Central HTTP service exposes health/readiness/version endpoints, Content staging and finalization, verified Content retrieval, Artifact and Package Revision registration, declarations, finance handoffs, disclosure operations, and authority operations.

Start the configured service with:

uv sync --locked --extra dev
uv run fdp-central init-db
uv run fdp-central serve

init-db initializes an empty configured MongoDB Registry or upgrades a canonical revision 6 Registry to revision 7. Collections whose names start with _ are ignored when checking an empty database; other unknown or inconsistent application collections are rejected. blob-sweep reconciles final Blob objects for one UTC month, for example --month 2026-08; it runs as a dry-run unless --apply is supplied.

The service reads the root config.yaml. Configure MongoDB, S3-compatible storage, HTTP settings, and the global admin identity there. Non-admin tokens are managed in the web console and stored in the Registry. Protect the configuration because it contains deployment credentials. Deployment prerequisites and examples are documented in docs/central-deployment.md.

The Docker image also builds and serves the Vue viewer. After starting the container, open the same HTTP origin at http://127.0.0.1:18080/; no separate frontend deployment is required.

Python client

CentralClient sends strict typed requests through a CentralTransport. For an in-process test, use deterministic in-memory custody implementations:

from financial_data_protocol import (
    CentralClient,
    CentralService,
    ContextSpaceAuthorizer,
    InMemoryContentCustody,
    InMemoryRegistryCustody,
    InProcessCentralTransport,
    StaticMachineTokenAuthenticator,
    StaticMachineTokenBinding,
)

transport = InProcessCentralTransport(
    CentralService(
        registry=InMemoryRegistryCustody(),
        content_custody=InMemoryContentCustody(),
        authorizer=ContextSpaceAuthorizer(),
    ),
    StaticMachineTokenAuthenticator((
        StaticMachineTokenBinding(
            "legal-api", "development-token", frozenset({"legal"})
        ),
    )),
)
client = CentralClient(
    transport,
    machine_token="development-token",
    caller_id="legal-api",
    registry_space_id="legal",
)

For a deployed service, use the same CentralClient API with HttpCentralTransport:

from financial_data_protocol import CentralClient, HttpCentralTransport

client = CentralClient(
    HttpCentralTransport("https://central.example", "machine-token", "legal-api"),
    machine_token="machine-token",
    caller_id="legal-api",
    registry_space_id="legal",
)

All writes require a stable idempotency key. Repeating the same canonical request replays its original result; reusing a key for a different request returns a conflict. Content uploads and retrievals verify the declared size and SHA-256.

Central schema revision 6 introduced separation between Space-local Content registration and global physical Blob custody. central_contents keeps each Space's Content identity, while content_blobs stores one physical object for each global (sha256, size_bytes) identity and tracks its reference count. The upload/finalize path performs Blob discovery internally, so clients never need cross-Space catalog access. Identical bytes registered in different Spaces share one object-store key:

central/<UTC creation date>/<blob_id>

Temporary staged objects are removed after successful finalization, and provisional Blob objects are removed if the Registry transaction rejects the finalize request. PostgreSQL and MongoDB both support the C6 model. Schema revision 7 adds durable scoped machine tokens and can upgrade a canonical revision 6 Registry. See the C6 section in docs/central-capabilities.md for the complete identity, idempotency, and migration semantics.

Scope

FDP does not decide whether a contract is approved or compliant, whether a payment is allowed, whether an invoice is valid, or whether an accounting entry is correct. It does not provide IAM, Registry federation, a queue, a general RAG system, or downstream workflow and output management. See docs/product-definition.md for the complete product boundary.

Documentation

• docs/central-capabilities.md: Central C0-C6 capability details and historical implementation notes.
• docs/api.md: Central HTTP API operations.
• docs/central-http-contract.md: frozen HTTP wire contract.
• docs/central-deployment.md: deployment and operations.
• docs/central-deployment-company-quickstart.md: company deployment quick start.
• docs/central-authority-cutover-runbook.md: C5 cutover and rollback procedure.
• docs/central-e2e-scenario.md: Central end-to-end scenario.
• docs/product-definition.md: product role, users, and boundaries.
• docs/roadmap.md: phased delivery roadmap.
• CHANGELOG.md: release and version history.

Development checks

uv sync --locked --extra dev
uv run python -m pytest -q
uv run python -m ruff check .
uv run python -m mypy
uv run python -m build