README.md (14016B)
1 # radroots_protocol 2 3 With `listing`, the public decoder validates a complete canonical profile and 4 its standard projections without assuming a particular tag order. With 5 `advertisement`, the closed capability decoder preserves exact bounded versions, 6 features and at-most-thirty-day author-time validity. These are passive claims; 7 signature admission, observed-head ranking and current-time policy belong to the 8 concrete adapter. Known values supply neither source freshness nor permission. 9 10 The chat profile's `GiftWrapBudget` measures the complete kind-1059 envelope 11 for the exact already obtained seal representation. Whitespace in retained 12 signed JSON still consumes encryption and event budget; canonical event 13 identity does not permit replacing those bytes during recovery. 14 15 Authored chat rumors carry the original full operation ID in a private 16 `radroots/operation` tag. Identical messages from distinct operations in one 17 second therefore have distinct NIP-01 message identities. Replaying the 18 original operation preserves its captured time, exact rumor and message ID; 19 the discriminator supplies no authorization. 20 21 `radroots_protocol` defines the passive, versioned wire contracts shared by 22 Radroots processes and language bindings. It is a `no_std + alloc` foundation 23 crate: it validates schema identities and contract catalogs, but performs no 24 network, storage, signing, scheduling, or process-lifecycle work. 25 26 The crate is pre-release and its Cargo version is frozen at `0.1.0-alpha` until 27 explicitly changed. Cargo package versions are independent from the version 28 numbers embedded in wire and schema contracts. 29 30 ## Contract surface 31 32 | Module | Authority | 33 | --- | --- | 34 | `capability::v1` | transport capabilities, maturity, and availability | 35 | `error::v1` | stable, redaction-safe error reports and recovery guidance | 36 | `event::v1` | event-kind catalogs and the serialized trade-state vocabulary | 37 | `runtime::v1` | operation descriptors, risk, approval, idempotency, and effects | 38 | `radrootsd::transport_publish::v5` | daemon transport-publish request, job, outcome, and capability DTOs | 39 | `schema` | schema IDs, module generations, descriptors, and aggregate registries | 40 | `profile` | assigned regular commerce kind8890 and replaceable capability kind18890, with closed profile identities; authoring qualification remains pending | 41 | `terms` (`terms` feature) | bounded closed Terms v1 decoding, explicit protected encoding and domain-separated digest; no authenticated consent, stock or signing authority | 42 | `commerce` (`commerce` feature) | complete closed record data, canonical RecordId and exact final carrier-field matching; no authenticated ingress or issuing authority | 43 | `private_rumor` (`private_rumor` feature) | closed protected unsigned data, bounded decoded text/tags and original NIP-01 RumorEventId recomputation; no cryptographic carrier admission | 44 | `command` (`commands` feature) | bounded closed v1 inquiry/reply data codec and exact command/approval-intent hashes | 45 | `nip01` (`nip01` feature) | exact bounded canonical preimages, IDs and complete-event sizes | 46 | `intent` (`intent` feature) | exact v1 signing commitments and passive replay declarations without execution authority | 47 | `nip59` (`chat` or `commerce` feature) | shared complete nesting budgets, exact seal data and bounded DM route descriptors | 48 | `chat` (`chat` feature) | bounded kind-14/13 data and complete immutable chat signing-plan codec | 49 | `listing` (`listing` feature) | closed sale-option inputs and bounded kind-30402/profile-v1 preimages without execution or publication authority | 50 51 Versioned DTOs live below an explicit generation module. The command codec 52 implements its fixed v1 profile without exposing automatic serialization of 53 captured private commands. Parsed command data supplies no authority or consent. 54 Command roots, inquiry/reply inputs, source references and all shared context 55 descriptors require objects; positional arrays are refused. The map-only typed 56 decoder preserves borrowed input and existing duplicate, unknown-field, explicit 57 null, byte/depth and exact canonical command/hash checks. 58 The crate root 59 does not reexport individual DTOs, so consumers must name the contract version 60 they use. 61 62 Public listing inputs retain fixed, quote-required or per-sale-unit variable 63 prices, with fixed/estimated/unspecified package metadata. Object fields reject 64 positional arrays, and the closed typed decoder rejects duplicate, missing and 65 unknown fields. Up to eight complete media-reference objects retain exact 66 URL/digest/MIME/alt claims; missing, malformed or excessive references are 67 refused. Media never activates fetching, uploading or a decoder. Estimated 68 supply retains its exact nonnegative amount and a required nullable absolute 69 window. Windows require strictly ordered Unix-second strings and an exact known 70 IANA zone from the pinned dataset; missing fields, positional arrays, duplicates, 71 noncanonical zones and extra offset/fold/wall-time claims are refused. Estimates 72 do not provide stock, reservation or freshness authority. 73 Only the fixed default contributes a three-field NIP-99 base-rate `price` tag; 74 the monetary summary identifies its basis, unit, discount and tier conditions. 75 Variable bounds/caps stay explicit in the profile and summary. No recurring 76 frequency field is used for units. Complete signed events retain the64KiB cap, 77 with at most nine tags and19 fields shared by signer and storage admission. 78 79 ## Features 80 81 | Feature | Default | Effect | 82 | --- | --- | --- | 83 | `std` | yes | implements standard-library error integration and enables `serde?/std` | 84 | `serde` | yes | derives serialization and deserialization for wire-contract types | 85 | `commands` | no | enables the portable closed chat codec, domain values, SHA-256 and zeroizing private command buffers | 86 | `nip01` | no | enables pure exact NIP-01 serialization and complete byte counting | 87 | `private_rumor` | no | enables bounded closed protected unsigned data and original rumor identity checks | 88 | `intent` | no | enables pure domain-separated v1 signing commitment data | 89 | `chat` | no | enables commands, NIP-01 and the bounded known-kind chat/plan data profile | 90 | `listing` | no | enables portable complete listing input and exact public profile/event production | 91 | `terms` | no | enables the closed private Terms codec over validated domain data, without record authoring | 92 | `commerce` | no | enables all nineteen complete record families, their closed codec and canonical identity over Terms data | 93 94 Terms encoding preserves complete source snapshots, resolved prices, private 95 fulfillment and explicit supply commitments. It counts the escaped UTF-8 output 96 before allocating one zeroizing private buffer, retains exact array order and 97 computes `SHA256("radroots.terms.v1\0" || JCS(Terms))`. The16KiB Terms limit 98 also applies jointly with the header/payload when building a complete private 99 record; fitting Terms alone supplies no complete-record or nested-wrap proof. 100 `EncodedTerms::protected_wire` is an explicit private disclosure. Its digest and 101 redacted diagnostics provide no participant approval, authenticated source, 102 reservation or installed agreement. 103 104 `terms::decode` admits at most16KiB and depth16, requiring closed objects, 105 explicit nullable fields and bounded line/group arrays. It checks duplicates 106 before acceptance and runs the shared domain constructors for every value. 107 Private text is borrowed from the caller's original frame until explicitly 108 decoded into zeroizing buffers; only public snapshots enter temporary JSON 109 trees. Decoding a claim establishes no signature, consent or current source 110 availability. Callers retain responsibility for protecting original bytes. 111 Profile public keys must match the identity library's canonical lowercase 112 spelling. The general identity parser remains case insensitive; profile input 113 does not silently normalize an uppercase participant, organization, peer, 114 listing author or product producer. 115 116 The commerce codec counts the complete header, record ID and payload against 117 the16KiB private content limit. Its record identity is 118 `SHA256("radroots.record.v1\0" || JCS(complete content without record_id))`. 119 The temporary protected hash preimage is dropped before final wire allocation. 120 All nineteen families retain complete data and exact causal references; parsing 121 checks every domain constructor and recomputes the content identity. Unknown 122 profile/version/type is classified before interpreting a known payload. 123 `check_rumor_fields` compares the final kind, author and time claims. Callers 124 must separately authenticate the complete wrap/seal/rumor and recipient, prove 125 history/authority/consent and check enclosing byte budgets before issuing or 126 installing anything. These data APIs enable no structured send or stock effect. 127 128 The listing producer emits one canonical `radroots.listing` version-1 profile, 129 explicit default units and no fabricated price. Paused/withdrawn projections 130 keep the same addressable coordinate, state non-availability in summary and 131 content, and omit a standard status that cannot represent that state. Complete 132 signed-event framing is bounded to 64 KiB before the canonical preimage is 133 allocated. Canonical profile ordering remains explicit when a consumer enables 134 JSON insertion-order preservation. The producer retains all implemented price, 135 package-content and public-supply modes, including estimated supply windows, 136 and the explicit media list. Pure input/preimage construction supplies no workspace 137 permission, durable preparation, signature, installed record or delivery receipt. 138 139 Disabling default features leaves the catalog and structural validation APIs 140 available with `alloc` only. Enable `serde` without `std` for portable encoded 141 DTOs. 142 143 ## Validate the aggregate contract 144 145 ```rust 146 use radroots_protocol::{capability, event, runtime, schema}; 147 148 capability::v1::validate_catalog(capability::v1::CATALOG).unwrap(); 149 event::v1::validate_catalog(event::v1::CATALOG).unwrap(); 150 event::v1::validate_trade_state_vocabulary(event::v1::TRADE_STATE_VOCABULARY) 151 .unwrap(); 152 runtime::v1::validate_catalog(runtime::v1::CATALOG).unwrap(); 153 154 let registry = schema::protocol_v1_registry().unwrap(); 155 assert!(!registry.is_empty()); 156 ``` 157 158 For a runnable version, see 159 [`examples/inspect_contract.rs`](examples/inspect_contract.rs). 160 161 ## Serialization and trust boundaries 162 163 Wire representations are stable only within their named generation. A caller 164 must deserialize into the intended version, run the module's structural 165 validation, and apply its own authorization and policy checks before acting on 166 the data. Successful deserialization alone does not make input trusted. 167 168 Stable error reports intentionally carry only safe messages and bounded detail 169 values. Use `error::v1::ErrorReport::redacted_from_source` at sensitive 170 boundaries; do not copy secrets, credentials, raw upstream errors, or private 171 payloads into protocol DTOs. 172 173 ## Side effects, cancellation, and commit points 174 175 This crate has no side effects, asynchronous work, cancellation mechanism, or 176 commit point. Runtime operation descriptors describe those properties; they do 177 not execute operations. The owning SDK, daemon, storage, signing, or transport 178 implementation must define cancellation behavior and must not report a commit 179 until its own durable boundary has succeeded. 180 181 ## Intended consumers 182 183 The direct consumers are Radroots domain crates, SDK and daemon runtimes, 184 transport/storage/signing boundaries, generated bindings, and conformance 185 tools. Applications should normally enter through `radroots` or 186 `radroots_sdk`, using this crate directly only when implementing or inspecting 187 a versioned boundary. 188 189 The package charter is the 190 [Release V1 specification](../../contracts/crates/release_v1/radroots_crates_release_v1.toml). 191 The reviewed Rust surface is recorded in the 192 [public API baseline](../../contracts/api_baselines/radroots_protocol.txt). 193 194 ## Complete private signing-plan data 195 196 `command::CapturedCommand` preserves the original chat bytes and commitments 197 and admits a separate typed `listing::CapturedListingCommand` when `listing` 198 is enabled. Public capture uses the same context and correlation/approval hash 199 projections. Its closed parser validates the supported quote-required profile 200 through domain constructors; unsupported price, supply, package contents or 201 media features are refused explicitly. Public commands have no chat peer or 202 private message. Capture supplies no current grant, signature or durable effect. 203 204 `chat::ChatSigningPlan` retains the exact sorted unique peer/self recipient set, 205 seal author/kind/time/empty tags/content/event ID/purpose, original signed DM 206 route-source bytes, selected targets, logical message ID, command commitment and 207 provider replay declaration. The closed binary profile is capped at 384 KiB; 208 its decoded recipient collections discard caller spare capacity. Original route 209 sources are each at most 64 KiB, selected URIs at most 2048 bytes, and the 210 combined session selection at most sixteen distinct relays. 211 212 Construction and decoding validate descriptors only. They verify no signature, 213 MAC, grant, consent, route readiness or provider capability and create no durable 214 commit. The executor must verify source evidence, approved targets and current 215 access, then retain this complete plan through its qualified protected journal 216 before any business signing invocation. A stored replay declaration alone never 217 permits uncertain reissue. 218 219 `commerce::initial_commitment_rumor` derives initial agreement data from a 220 captured acceptance, original request and declared seller author head. 221 `CommerceSigningPlan` retains both exact peer/self seals, original route sources 222 and selected targets within256KiB. It uses the shared `nip59` bounds and 223 `intent::SigningReplay` declarations. Concrete hosts must compare these claims 224 with retained T0, verify ciphertext/plaintext and route evidence, and commit T1 225 before signing. These constructors provide no permission or durable proof.