otp/plans/nostr_otp_partition_protocol.md

OTP Dynamic Partitioning & Rebalancing Protocol Plan

1. Core Design Principles

1. Strictly One .state File Per Pad (<chksum>.state):
   • Every app/device maintains a single <chksum>.state file alongside <chksum>.pad.
   • No .split.state files or device names/IDs are ever created.
2. All Splits Emit a Pure-OTP Grant Message (OTP-GRANT-V1):
   • Onboarding a brand-new device and rebalancing space to an existing device are the exact same operation (split).
   • When split runs, the donor device cuts its remaining unused [offset, end_offset) in half at mid (aligned to 256-byte chunks), updates its own <chksum>.state (end_offset=mid and peer_extent=mid:old_end) first (fsync), and outputs a 256-byte ASCII-armored Pure-OTP message (OTP-GRANT-V1) encrypted at offset mid.
   • Because the OTP-GRANT-V1 message is encrypted at mid (256 bytes), the recipient's usable partition starts at mid + 256 (Grant-Start: mid + 256), guaranteeing even the 256 bytes used to encrypt the grant itself are never reused!
3. Nameless, Byte-Range Partition Tracking (peer_extent=start:end):
   • Partitions are identified purely by their byte ranges start:end.
   • When a donor splits off [mid, old_end), it records peer_extent=mid+256:old_end in its <chksum>.state file.
   • Whenever any app decrypts a regular OTP message at Pad-Offset: P of length L (P + L), if P falls within a known peer_extent=start:end (start <= P < end), the app automatically updates that peer_extent to (P + L):end!
   • Thus, simply by exchanging normal OTP messages, an app passively sees how much space its peer partitions have left.

---

2. Single .state File Format

offset=10485760
end_offset=40000000
next_extent=95000000:120000000
peer_extent=40000256:65000000
peer_extent=70002048:95000000

• offset: Current write cursor for this app's active partition.
• end_offset: Exclusive upper bound of this app's active partition (defaults to pad_size if omitted in legacy .state files).
• next_extent: Zero or more start:end extents queued for this app (from received OTP-GRANT-V1 messages). Automatically popped into offset / end_offset when the active partition runs out.
• peer_extent: Zero or more start:end extents known to belong to other apps/devices. Automatically advanced when decrypting messages whose Pad-Offset falls inside [start, end).

---

3. Pure-OTP Grant Message Flow

sequenceDiagram
    participant AppA as App 1 - Donor
    participant AppB as App 2 - Recipient

    Note over AppA: Owns [offset, end_offset)
    AppA->>AppA: mid = align_256((offset + end_offset) / 2)
    AppA->>AppA: grant_start = mid + 256, grant_end = old_end
    AppA->>AppA: Save end_offset=mid & peer_extent=grant_start:grant_end to .state FIRST
    AppA->>AppA: Encrypt OTP-GRANT-V1(grant_start, grant_end) using 256B at mid
    AppA->>AppB: Send standard -----BEGIN OTP MESSAGE----- block
    AppB->>AppB: Decrypt message at mid -> parse OTP-GRANT-V1
    AppB->>AppB: Update single <chksum>.state with [grant_start, grant_end)