lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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.