SSIMPL Specification

Each signed object MUST include a signatureDocument with the following structure:

• message — The cryptographic hash of the canonical serialization of the data object. See §Canonicalization Rules.
• signature — Object containing the signature itself:
  • publicKey — Base64url-encoded public key corresponding to the signing private key.
  • algorithm — Signature algorithm used (e.g., EdDSA, ECDSA).
  • value — Base64url-encoded signature value.
• signer — DID of the entity producing the signature.

Example (in JSON for clarity):

{
  "message": "<hash-of-canonical-data>",
  "signature": {
    "publicKey": "<multibase-encoded public="" key="">",
    "algorithm": "<algorithm identifier="">",
    "value": "<multibase-encoded signature="">"
  },
  "signer": "<did of="" signer="">"
}

• Every signed object in SSIMPL, including LedgerEntry, VerifiableCredentialRoot, revocation entries, and delta updates, MUST include a signatureDocument.
• The message field MUST be derived from the canonical serialization of the associated data object, ensuring that identical logical objects produce identical hashes.
• This pattern guarantees interoperability, verifiability, and deterministic ordering for all signed objects across the network.

• Optional fields in the data object MUST NOT affect the canonical hash unless explicitly defined in the canonicalization rules.
• Implementations MUST reject signatures if the hash does not match the canonicalized data object.
• Adherence to this pattern is mandatory to ensure correct ledger validation, delta verification, and revocation processing.

This canonical signature object pattern provides a single, consistent approach for proving authorship and integrity across all SSIMPL objects.

---

Relay Peers are discoverable via a canonical hostname scheme:

• Hostnames are deterministic, e.g., 0.ssimpl.org … 9999.ssimpl.org.
• Each Relay Peer implements a fixed set of endpoints defined by the SSIMPL specification.
• Peers attempt to connect sequentially or via pseudo-randomized probing across the deterministic range.

Rationale: Deterministic hostnames avoid the need for a centralized list, while still enabling Peers to discover Relay Peers without prior trust assumptions.

1. Connection: Peer attempts a connection to a candidate Relay Peer.
2. Metadata Exchange: Relay Peer returns:
   • last_epoch (latest ledger epoch)
   • root_hash (canonical ledger root)
   • Timestamp
   • signature_document - Signature over the metadata using the Relay Peer’s DID key
3. Validation: Peer verifies:
   • root_hash corresponds to canonical ledger rules
   • Timestamp is within an acceptable window
   • Signature is valid and matches the DID key
4. Challenge-Response (Optional):
   • Peer sends a nonce to the Relay Peer
   • Relay Peer signs the nonce and returns the signature
   • Peer validates the signature to ensure possession of the claimed DID key
5. Trust Establishment: Peer marks Relay Peer as verified if all checks pass; otherwise, the peer discards the candidate.

• Peers iterate through deterministic hostnames.
• Temporarily unreachable hosts are retried after a backoff period.
• Optionally, a seed CID on IPFS may provide an initial snapshot of active Relay Peers to bootstrap discovery.

• Deterministic discovery combined with cryptographic verification ensures that peers cannot be misled by malicious Relay Peers.
• Relay Peers are auditable: any failure to implement endpoints correctly or return invalid data can be detected.
• Peers remain authoritative for ledger validation; Relay Peers are relays, not arbiters.

Summary:
This protocol allows new Peers to bootstrap without centralized coordination, ensures Relay Peers can be trusted, and maintains the integrity and decentralization of the SSIMPL ledger.

• Leaves: Hashes of canonical ledger entries.
• Branches: Hashes of concatenated child nodes.
• Root: root_hash representing the current canonical ledger state.

1. New ledger entries are appended as leaves.
2. The affected branches are rehashed up to the root.
3. Pruning does not delete nodes; the canonical ledger for the current epoch defines which entries are considered valid.

• To prove inclusion of a DID xyz, a peer can provide the leaf hash and the branch hashes up to root_hash.
• Other peers can recompute the root from the proof and verify it matches the canonical root_hash.

• Checkpoints store a root_hash for a specific epoch.
• Peers can verify their ledger or deltas by starting from the latest checkpoint and applying updates.

A Merkle checkpoint is a snapshot of the canonical ledger at a given epoch, containing:

• epoch — The deterministic epoch number of the snapshot
• root_hash — The canonical ledger Merkle root at that epoch
• metadata (optional) — Any additional information, such as total entry count, checkpoint creator DID, or a reference timestamp

Merkle checkpoints serve three main purposes:

1. Anchoring history — They provide a trusted reference point for peers to verify that their current ledger is an extension of a previous canonical state.
2. Fork detection — Peers can detect divergence by comparing their checkpointed root hash with peers’ reported checkpoints.
3. Efficient synchronization — When a peer joins the network or recovers from offline mode, it can request deltas starting from the latest known checkpoint rather than from the genesis ledger.

• Peers MAY create checkpoints at deterministic intervals (e.g., end of each epoch).
• Relay Peers SHOULD store checkpoints for availability, enabling efficient delta requests for mobile peers.
• Checkpoints themselves are immutable; once created, they cannot be modified or deleted.

To verify a ledger using a checkpoint:

1. Obtain the checkpoint for the target epoch (epoch, root_hash).
2. Compute the canonical ledger state from the checkpoint epoch to the current state.
3. Recompute the Merkle root for the resulting ledger.
4. Confirm that the recomputed root matches the current root_hash.

A mismatch indicates ledger tampering or divergence, and the peer MUST reject the inconsistent entries.

• Checkpoints older than a configurable retention window MAY be pruned to reduce storage overhead.
• Retention policies SHOULD be deterministic and consistent across peers to maintain canonical verification paths.

• Checkpoint integrity — Checkpoints must be signed by the creating peer using their DID key.
• Fork prevention — Peers must reject any checkpoint that does not extend a known valid previous checkpoint.
• Replay attacks — Timestamps and epoch numbers help prevent replay of stale checkpoints.

POST /ledger/delta

Purpose: Allows a Peer to request ledger entries that are newer than a given epoch, if the peer is out of sync.

Request payload (LedgerDeltaRequest):

Example:

{
  "lastEpoch": 42,
  "rootHash": "abcdef1234567890"
}

Response payload (LedgerDeltaResponse):

Field Type Description currentEpoch integer Current epoch of the relay peer ledger authoritativeRootHash string Merkle root hash after applying returned entries array Ordered ledger entries newer than lastEpoch

Example:

{
  "currentEpoch": 43,
  "authoritativeRootHash": "1234abcd5678ef90",
  "entries": [
    {
      "data": {
        "verifiableCredentialRoot": {
          ...
        },
        "proof": {
          ...
        }
      },
      "signatureDocument": {
        ...
      }
    }
  ]
}

⸻

Register a DID

POST /ledger

Purpose: Register a new DID on the ledger.

Request payload: LedgerEntry object

Example:

{
  "data": {
    "verifiableCredentialRoot": {
      ...
    },
    "proof": {
      ...
    }
  },
  "signatureDocument": {
    ...
  }
}

Response: 200 OK on success.

⸻

Revoke a DID

PUT /ledger

Purpose: Revoke a DID by submitting a revocation payload.

Request payload: LedgerEntryRevocation object

Example:

{
  "data": {
    "did": "did:key:z6Mkw...example"
  },
  "signatureDocument": {
    ...
  }
}

Response: 200 OK on success.

⸻

Shared Object Schemas