Skip to content

ADR-0005: Filesystem Participant Manager with Protocol

Status

Accepted

Date

2026-05-13

Context

Test execution needs to manage dataspace participant identities (BPNLs). Future requirements include database storage, issuer service integration, and user identification. Current need is simple persistence across test runs.

Options: (1) hardcoded participants, (2) in-memory only, (3) protocol-based with filesystem implementation.

Decision

Define a ParticipantManager Protocol/ABC with get_or_create(name) and get(name) methods. Implement FileSystemParticipantManager using JSON file storage. Generate deterministic BPNLs via SHA-256 hash of participant name (prefix BPNL, 12 hex characters, checksum suffix).

Consequences

Positive

  • Protocol enables future backends (database, issuer service) without changing consumers.
  • Deterministic BPNLs — same participant name produces the same BPNL across runs.
  • Simple JSON persistence requires no external dependencies.
  • Protocol enables easy dependency injection and mocking in tests.

Negative

  • Filesystem storage not suitable for concurrent multi-user access.
  • SHA-256 determinism means BPNL collisions are theoretically possible (practically negligible).

Neutral

  • JSON file location configurable via test configuration.
  • Participant data includes name, BPNL, and creation timestamp.