Add NIP-XX: Time Capsules specification
This NIP defines time-locked capsules: encrypted Nostr events that become readable only at/after a target timestamp or when a threshold of designated witnesses publish unlock shares. It includes specifications for event kinds, unlock modes, protocol flow, client behavior, security considerations, and examples.
This commit is contained in:
karim Hassan
GitHub
parent
fd9c627b36
commit
71ffba4494
|
|
@ -0,0 +1,317 @@
|
||||||
|
# NIP-XX: Time Capsules
|
||||||
|
|
||||||
|
`draft` `optional`
|
||||||
|
|
||||||
|
This NIP defines time-locked capsules: encrypted Nostr events that become readable only at/after a target timestamp or when a threshold of designated witnesses publish unlock shares. This enables delayed revelation, threshold cryptography, digital inheritance, and whistleblowing protection.
|
||||||
|
|
||||||
|
Time-locked capsules allow content to be:
|
||||||
|
|
||||||
|
- Released automatically after a specific timestamp
|
||||||
|
- Unlocked when multiple witnesses collaborate
|
||||||
|
- Made accessible after long periods for digital inheritance
|
||||||
|
- Protected with built-in delays for sensitive material
|
||||||
|
|
||||||
|
## Event Kinds
|
||||||
|
Permalink: Event Kinds
|
||||||
|
|
||||||
|
- `1990`: Time Capsule (regular)
|
||||||
|
- `30095`: Time Capsule (parameterized replaceable; keyed by `d` tag)
|
||||||
|
- `1991`: Time Capsule Unlock Share
|
||||||
|
- `1992`: Time Capsule Share Distribution
|
||||||
|
|
||||||
|
## Specification
|
||||||
|
Permalink: Specification
|
||||||
|
|
||||||
|
### Time Capsule Events (kinds `1990` and `30095`)
|
||||||
|
Permalink: Time Capsule Events
|
||||||
|
|
||||||
|
A time capsule event contains encrypted content and unlock conditions.
|
||||||
|
|
||||||
|
#### Required tags
|
||||||
|
|
||||||
|
- `u`: Unlock configuration in format `["u","<mode>","<param1>","<value1>",...]`
|
||||||
|
- `p`: Witness pubkeys (one or more) - `["p","<witness_pubkey_hex>"]`
|
||||||
|
- `w-commit`: Merkle root commitment - `["w-commit","<hex_merkle_root>"]`
|
||||||
|
- `enc`: Encryption method - `["enc","nip44:v2"]`
|
||||||
|
- `loc`: Storage location - `["loc","inline"|"https"|"blossom"|"ipfs"]`
|
||||||
|
|
||||||
|
#### Optional tags
|
||||||
|
|
||||||
|
- `d`: Identifier (required for kind `30095`) - `["d","<capsule-id>"]`
|
||||||
|
- `uri`: External content URI (required when `loc != "inline"`) - `["uri","<url>"]`
|
||||||
|
- `sha256`: Content integrity hash - `["sha256","<hex_hash>"]`
|
||||||
|
- `expiration`: Expiration timestamp per NIP-40 - `["expiration","<unix>"]`
|
||||||
|
- `alt`: Human-readable description - `["alt","<description>"]`
|
||||||
|
|
||||||
|
#### Content
|
||||||
|
|
||||||
|
The `content` field MUST contain a base64-encoded NIP-44 v2 encrypted payload. When `loc` is `"inline"`, the entire encrypted content is in this field. When `loc` is external, this field MAY be empty and the `uri` tag points to the encrypted content.
|
||||||
|
|
||||||
|
### Unlock Modes
|
||||||
|
Permalink: Unlock Modes
|
||||||
|
|
||||||
|
#### Threshold Mode
|
||||||
|
|
||||||
|
```plaintext
|
||||||
|
["u","threshold","t","<t>","n","<n>","T","<unix_unlock_time>"]
|
||||||
|
```
|
||||||
|
|
||||||
|
- **t**-of-**n** witnesses must provide shares at/after timestamp `T`
|
||||||
|
- Prevents unilateral early disclosure but not collusion of any `t` witnesses
|
||||||
|
|
||||||
|
#### Scheduled Mode
|
||||||
|
|
||||||
|
```plaintext
|
||||||
|
["u","scheduled","T","<unix_unlock_time>"]
|
||||||
|
```
|
||||||
|
|
||||||
|
- Indicates time-based operational release where witnesses or services intend to post shares after `T`
|
||||||
|
- This mode is not a cryptographic timelock; a future revision may define a VDF-based trustless mode
|
||||||
|
|
||||||
|
Implementations MUST parse unknown `u` modes conservatively and treat them as unsupported.
|
||||||
|
|
||||||
|
### Unlock Share Events (kind `1991`)
|
||||||
|
Permalink: Unlock Share Events
|
||||||
|
|
||||||
|
A witness posts one share after the unlock timestamp (with optional skew tolerance).
|
||||||
|
|
||||||
|
#### Required tags
|
||||||
|
|
||||||
|
- `e`: Capsule event reference - `["e","<capsule_event_id>"]`
|
||||||
|
- `a`: Addressable reference (if capsule is parameterized replaceable) - `["a","30095:<pubkey_hex>:<d>"]`
|
||||||
|
- `p`: Witness pubkey - `["p","<witness_pubkey_hex>"]`
|
||||||
|
- `T`: Unlock time from capsule - `["T","<unix_timestamp>"]`
|
||||||
|
|
||||||
|
#### Content
|
||||||
|
|
||||||
|
- Base64 Shamir share for threshold mode
|
||||||
|
- MAY be gift-wrapped (per NIP-59) to reduce metadata leakage
|
||||||
|
- Clients MUST access the plaintext share after timestamp `T`
|
||||||
|
|
||||||
|
### Share Distribution Events (kind `1992`)
|
||||||
|
Permalink: Share Distribution Events
|
||||||
|
|
||||||
|
Automates delivery of per-witness shares immediately after capsule creation.
|
||||||
|
|
||||||
|
#### Required tags
|
||||||
|
|
||||||
|
- `e`: Capsule event reference - `["e","<capsule_event_id>"]`
|
||||||
|
- `a`: Addressable reference (if capsule is parameterized replaceable) - `["a","30095:<pubkey_hex>:<d>"]`
|
||||||
|
- `p`: Recipient witness - `["p","<witness_pubkey_hex>"]`
|
||||||
|
- `share-idx`: Share index - `["share-idx","<0..n-1>"]`
|
||||||
|
- `enc`: Encryption method - `["enc","nip44:v2"]`
|
||||||
|
|
||||||
|
#### Content
|
||||||
|
|
||||||
|
NIP-44 v2 ciphertext containing the Shamir share destined for the witness. Only the intended witness can decrypt.
|
||||||
|
|
||||||
|
#### Validation Rules
|
||||||
|
|
||||||
|
- Event MUST be authored by the same pubkey as the capsule
|
||||||
|
- The target `p` MUST appear in the capsule's witness list
|
||||||
|
- `share-idx` MUST be within `[0, n-1]`
|
||||||
|
|
||||||
|
## Protocol Flow
|
||||||
|
Permalink: Protocol Flow
|
||||||
|
|
||||||
|
1. **Create Capsule** (kind `1990` or `30095`)
|
||||||
|
- Author generates random key `K` and encrypts payload with NIP-44 v2 → `C`
|
||||||
|
- Selects witnesses (p tags), sets threshold `t`, witness count `n`, unlock time `T`
|
||||||
|
- Computes `w-commit` over ordered witnesses
|
||||||
|
- Publishes capsule with `content=C`, unlock config, witness list, commitment, storage location
|
||||||
|
|
||||||
|
2. **Distribute Shares** (kind `1992`) *(recommended)*
|
||||||
|
- Split `K` using Shamir's Secret Sharing (t, n)
|
||||||
|
- For each witness, publish `1992` with NIP-44 encrypted share for that witness
|
||||||
|
- Include `share-idx` to maintain ordering
|
||||||
|
|
||||||
|
3. **Unlock** (kind `1991`)
|
||||||
|
- At/after timestamp `T` (± skew tolerance), witnesses publish `1991` with plaintext shares
|
||||||
|
- Clients collect any `t` valid shares, reconstruct `K`, and decrypt `C`
|
||||||
|
|
||||||
|
## Relay Behavior
|
||||||
|
Permalink: Relay Behavior
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Relays MUST:
|
||||||
|
|
||||||
|
- Ensure required tags exist and are well-formed
|
||||||
|
- For `1991`, reject shares where `now < T - skew` (recommended skew = 300 seconds)
|
||||||
|
- For `1992`, validate author matches capsule author and recipient witness is in capsule's witness list
|
||||||
|
|
||||||
|
### Indexing
|
||||||
|
|
||||||
|
Relays SHOULD:
|
||||||
|
|
||||||
|
- Index `p` tags (witnesses) and `e` tags (capsule references) for discovery
|
||||||
|
- Not rely on custom tag filters beyond NIP-01
|
||||||
|
|
||||||
|
### NIP-11 Capability Advertisement
|
||||||
|
Permalink: NIP-11 Capability Advertisement
|
||||||
|
|
||||||
|
Relays implementing this NIP SHOULD advertise their support in their NIP-11 document:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"supported_nips": [1, 11, ...],
|
||||||
|
"software": "...",
|
||||||
|
"version": "...",
|
||||||
|
"capsules": {
|
||||||
|
"v": "1",
|
||||||
|
"modes": ["threshold","scheduled"],
|
||||||
|
"max_inline_bytes": 131072
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
|
||||||
|
Early share rejection SHOULD use clear error messages per NIP-01 (e.g., `["OK", <event_id>, false, "invalid: too early"]`).
|
||||||
|
|
||||||
|
## Client Behavior
|
||||||
|
Permalink: Client Behavior
|
||||||
|
|
||||||
|
- **Creation**: Generate `K`, encrypt payload with NIP-44 v2, produce capsule event, compute `w-commit`, publish
|
||||||
|
- **Distribution**: Publish `1992` per witness with NIP-44 encrypted share; store local copy
|
||||||
|
- **Monitoring**: Track timestamp `T`, watch for `1991` from witnesses; tolerate skew ±300s
|
||||||
|
- **Reconstruction**: Verify witness membership via `w-commit`, collect any `t` valid shares, reconstruct `K`, decrypt content
|
||||||
|
- **Integrity**: When `loc != inline`, fetch `uri`, verify `sha256` hash before decryption
|
||||||
|
- **Discovery**: Use standard filters, e.g., witnesses look up:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "kinds": [1992], "#p": ["<witness_pubkey_hex>"] }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
Permalink: Security Considerations
|
||||||
|
|
||||||
|
- **Witness Collusion**: Threshold prevents unilateral early disclosure but not collusion of any `t` witnesses. Choose diverse witnesses and set `t` accordingly.
|
||||||
|
- **Early Disclosure**: Enforce timestamp `T` at relays (reject pre-`T - skew`) and at clients (ignore early shares).
|
||||||
|
- **Time Manipulation**: Use trusted time sources where possible; keep small skew windows.
|
||||||
|
- **External Storage Integrity**: Include `sha256` for any `uri` content.
|
||||||
|
- **Spam/DoS**: Rate-limit `1991/1992` per capsule and per witness.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
Permalink: Examples
|
||||||
|
|
||||||
|
### Time Capsule (kind 1990, threshold 2/3)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 1990,
|
||||||
|
"pubkey": "a2b3c4d5...",
|
||||||
|
"created_at": 1735689600,
|
||||||
|
"content": "base64_encoded_nip44v2_ciphertext",
|
||||||
|
"tags": [
|
||||||
|
["u","threshold","t","2","n","3","T","1735776000"],
|
||||||
|
["p","f7234bd4..."],
|
||||||
|
["p","a1a2a3a4..."],
|
||||||
|
["p","b1b2b3b4..."],
|
||||||
|
["w-commit","3a5f...c9"],
|
||||||
|
["enc","nip44:v2"],
|
||||||
|
["loc","inline"],
|
||||||
|
["alt","Secret message requiring 2 of 3 witnesses"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Time Capsule (kind 30095, external storage)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 30095,
|
||||||
|
"pubkey": "a2b3c4d5...",
|
||||||
|
"created_at": 1735689600,
|
||||||
|
"content": "",
|
||||||
|
"tags": [
|
||||||
|
["d","capsule-2025-07"],
|
||||||
|
["u","threshold","t","3","n","5","T","1736000000"],
|
||||||
|
["p","w1..."],
|
||||||
|
["p","w2..."],
|
||||||
|
["p","w3..."],
|
||||||
|
["p","w4..."],
|
||||||
|
["p","w5..."],
|
||||||
|
["w-commit","9c01...ab"],
|
||||||
|
["enc","nip44:v2"],
|
||||||
|
["loc","https"],
|
||||||
|
["uri","https://media.example/caps/abc"],
|
||||||
|
["sha256","c0ffee..."],
|
||||||
|
["alt","External ciphertext with integrity hash"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Unlock Share (kind 1991)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 1991,
|
||||||
|
"pubkey": "a1a2a3a4...",
|
||||||
|
"created_at": 1735776100,
|
||||||
|
"content": "base64_shamir_share",
|
||||||
|
"tags": [
|
||||||
|
["e","...capsule_event_id..."],
|
||||||
|
["a","30095:a2b3c4d5...:capsule-2025-07"],
|
||||||
|
["p","a1a2a3a4..."],
|
||||||
|
["T","1735776000"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Share Distribution (kind 1992)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"kind": 1992,
|
||||||
|
"pubkey": "a2b3c4d5...",
|
||||||
|
"created_at": 1735689700,
|
||||||
|
"content": "base64_nip44v2_encrypted_share_for_witness",
|
||||||
|
"tags": [
|
||||||
|
["e","...capsule_event_id..."],
|
||||||
|
["a","30095:a2b3c4d5...:capsule-2025-07"],
|
||||||
|
["p","a1a2a3a4..."],
|
||||||
|
["share-idx","1"],
|
||||||
|
["enc","nip44:v2"]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Vectors
|
||||||
|
Permalink: Test Vectors
|
||||||
|
|
||||||
|
### Test Vector A: Threshold 2-of-3
|
||||||
|
|
||||||
|
- Witnesses (ordered pubkeys): `hex_pubkey_A`, `hex_pubkey_B`, `hex_pubkey_C`
|
||||||
|
- `w-commit` = MerkleRoot([(0, `hex_pubkey_A`), (1, `hex_pubkey_B`), (2, `hex_pubkey_C`)])
|
||||||
|
- `T` = `1735776000`
|
||||||
|
- Shares: `S0,S1,S2`; any two reconstruct `K`
|
||||||
|
- Ciphertext: `C = NIP44v2_Encrypt(K, "hello world")` → `content = base64(C)`
|
||||||
|
|
||||||
|
Expected flow:
|
||||||
|
|
||||||
|
- `1990` event as shown above
|
||||||
|
- `1992` to `hex_pubkey_B` with `share-idx=1` (content = NIP-44 encrypted `S1` to `hex_pubkey_B`)
|
||||||
|
- `1991` from `hex_pubkey_B` and `hex_pubkey_C` after `T` (plaintext shares)
|
||||||
|
- Client reconstructs `K` and decrypts `C` → `"hello world"`
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
Permalink: Rationale
|
||||||
|
|
||||||
|
- Uses new kinds to avoid overloading existing semantics; unaware nodes ignore unknown kinds
|
||||||
|
- Leverages standard `p`/`e` tags for discovery; avoids non-standard tag filtering
|
||||||
|
- `w-commit` binds the witness set to prevent tampering
|
||||||
|
- Parameterized replaceable variant (`30095`) supports pre-`T` fixes via the `d` tag and `a` addressing
|
||||||
|
|
||||||
|
## Backwards Compatibility
|
||||||
|
Permalink: Backwards Compatibility
|
||||||
|
|
||||||
|
New kinds are ignored by unaware relays/clients. The `alt` tag provides a human-readable hint for unknown kinds. Use of standard `p` and `e` tags preserves discoverability via existing filters.
|
||||||
|
|
||||||
|
## Reference Implementation
|
||||||
|
Permalink: Reference Implementation
|
||||||
|
|
||||||
|
A reference implementation is provided in [Shugur Relay](https://github.com/Shugur-Network/relay) project:
|
||||||
|
|
||||||
|
- Relay validation: `internal/relay/nips/nip_time_capsules.go`
|
||||||
|
- Test suite: `tests/nips/test_time_capsules_comprehensive.sh`
|
||||||
Loading…
Reference in New Issue