POST /replicate

This endpoint processes write-behind differential state replication. It allows clients to push multiple client-encrypted block diffs in a single request, validates sizes, executes credit debits, checks for split-brain conflicts, and confirms persistence.

Request URL

POST /replicate

Request Body Schema

The body must be a JSON object with the following fields:

Chunk Object Schema

Example Request Body

{
  "chunks": [
    {
      "sequence_number": 10,
      "block_hash": "f5a2b3c4...",
      "ciphertext_b64": "SGVsbG8gV29ybGQ="
    }
  ],
  "merkle_root": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c"
}

Billing Costs

• Project Tokens (sov_proj_): Free tier ($0$ cost).
• Live API Keys (sov_live_): Charged at $0.045$ milli-cents ($0.00045$ credits) per byte of decoded ciphertext. Billed atomically using atomic_debit_credits_milli_v2. Failed transactions are fully refunded.

Idempotency & Split-Brain Conflict Detection

To ensure absolute recall integrity, the database prevents duplicate writes to the same (agent_id, sequence_number) pair:

1. Idempotent Retries: If the sequence number is already registered and the block_hash matches exactly, the endpoint returns a 200 OK indicating a successful idempotent replay.
2. Split-Brain Conflict: If the sequence number is already registered but the block_hash differs, the write is rejected as a split-brain condition (e.g. two client devices modifying state offline). The server returns 409 Conflict:

{
  "error": "split_brain_detected",
  "conflicts": [
    {
      "sequence_number": 10,
      "existing_block_hash": "f5a2b3c4...",
      "attempted_block_hash": "e3b0c442..."
    }
  ]
}

Response Schema (200 OK)

Standard Return

{
  "accepted": 1,
  "sequence_number": 10,
  "merkle_root": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c"
}

Idempotent Replay Return

{
  "idempotent": true
}