@reticulum/dacar 1.1.1 → 1.2.0

package/src/crdt.js

@@ -305,7 +305,7 @@ export class StateVector {
 }
 
 /**
- * @param {unknown} value
+ * @param {Uint8Array} value
  * @param {number} len
  * @param {string} name
  * @returns {Uint8Array}
@@ -317,7 +317,7 @@ function expectBytes(value, len, name) {
   return value;
 }
 
-/** @param {unknown} value @param {string} name @returns {boolean} */
+/** @param {boolean} value @param {string} name @returns {boolean} */
 function expectBool(value, name) {
   if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`);
   return value;

package/src/operation.js

@@ -232,7 +232,7 @@ export class Operation {
 }
 
 /**
- * @param {unknown} value
+ * @param {Uint8Array} value
  * @param {number} len
  * @param {string} name
  * @returns {Uint8Array}
@@ -245,7 +245,7 @@ function expectBytes(value, len, name) {
 }
 
 /**
- * @param {unknown} value
+ * @param {boolean} value
  * @param {string} name
  * @returns {boolean}
  */

package/src/transport/lxmfSync.js

@@ -18,7 +18,7 @@
  * never pulls it in. It depends only on `@reticulum/core`, which the core
  * already depends on, so no new dependency is added.
  *
- * Typical use (receiver, wired to a {@link import("@reticulum/core").LXMRouter
+ * Typical use (receiver, wired to a {@link import("@reticulum/core/src/lxmf/index.js").LXMRouter
  * LXMRouter}):
  *
  * ```js
@@ -38,7 +38,7 @@
  * await delivery.handleMessage(event.detail.message);
  */
 
-import { LXMessage as LXMFMessage } from "@reticulum/core";
+import { LXMessage as LXMFMessage } from "@reticulum/core/src/lxmf/index.js";
 import { LXMF_DELIVERY_TITLE } from "../naming.js";
 
 /**
@@ -99,13 +99,13 @@ export class LxmfDeltaDelivery {
    * @param {import("../delta.js").DeltaReceiver | null} [opts.receiver]
    *   The shared DeltaReceiver (state + key resolver). May be omitted on a
    *   send-only node (then `handleMessage` throws if called).
-   * @param {import("@reticulum/core").LXMRouter | null} [opts.router]
+   * @param {import("@reticulum/core/src/lxmf/index.js").LXMRouter | null} [opts.router]
    *   Optional bound `LXMRouter` for `deliver` / `ingestPaperUri`.
    */
   constructor({ receiver = null, router = null } = {}) {
     /** @type {import("../delta.js").DeltaReceiver | null} */
     this._receiver = receiver;
-    /** @type {import("@reticulum/core").LXMRouter | null} */
+    /** @type {import("@reticulum/core/src/lxmf/index.js").LXMRouter | null} */
     this._router = router;
   }
 
@@ -121,7 +121,7 @@ export class LxmfDeltaDelivery {
    * @param {Uint8Array} deltaPayload
    * @param {Uint8Array} destinationHash The recipient `lxmf.delivery` hash.
    * @param {Uint8Array} sourceHash The sender's `lxmf.delivery` hash.
-   * @returns {import("@reticulum/core").LXMessage}
+   * @returns {import("@reticulum/core/src/lxmf/index.js").LXMessage}
    */
   makeMessage(deltaPayload, destinationHash, sourceHash) {
     if (!(deltaPayload instanceof Uint8Array)) {
@@ -145,7 +145,7 @@ export class LxmfDeltaDelivery {
    * @param {Uint8Array} destinationHash The recipient `lxmf.delivery` hash.
    * @param {Object} [opts]
    * @param {Uint8Array | null} [opts.linkId] Reuse an existing DIRECT link id.
-   * @returns {Promise<import("@reticulum/core").LXMessage>}
+   * @returns {Promise<import("@reticulum/core/src/lxmf/index.js").LXMessage>}
    */
   async deliver(deltaPayload, destinationHash, { linkId = null } = {}) {
     if (!this._router) {
@@ -210,7 +210,7 @@ export class LxmfDeltaDelivery {
    * ingest result (the reconstructed message, or `null` if it was not for this
    * node / already ingested).
    * @param {string} uri
-   * @returns {Promise<import("@reticulum/core").LXMessage | null>}
+   * @returns {Promise<import("@reticulum/core/src/lxmf/index.js").LXMessage | null>}
    */
   async ingestPaperUri(uri) {
     if (!this._router) {

package/src/transport/rfedSync.js

@@ -10,60 +10,80 @@
  * delivery — **never** through the unauthenticated `StateVector.merge()` path.
  * A forged or stale Delta is simply dropped before it can mutate state.
  *
- * `RfedDeltaSync` wraps a `@reticulum/core` `RFedClient`. A Delta is wrapped as
- * the LXMF *content* of a channel message under the fixed `dacar/sync/delta`
- * title; on receipt the channel is the feed discriminator (every message on it
- * is a Dacar Delta), and the content bytes are fed to `DeltaReceiver`.
+ * `RfedDeltaSync` wraps a `@reticulum/core` `RFedClient`. A Delta travels in
+ * Dacar's **compact inner format** (§11.1.1): the raw §5.3 payload is placed
+ * straight after the RTID source-identity prelude and EC-encrypted to the
+ * derived channel identity — no LXMF envelope, which would only duplicate the
+ * Delta's own destination/source/signature/timestamp and push a typical
+ * 170-byte Delta past the 500-byte RNS MTU. On receipt the channel is the feed
+ * discriminator (every message on it is a Dacar Delta), and the recovered Delta
+ * bytes are fed to `DeltaReceiver`.
  *
- * §11.3 air-gapped/optical transport is served by `./lxmfSync.js` (Paper
- * Messages); RFed is the online many-to-many path.
+ * The compact format is built on `@reticulum/core`'s raw RFed primitives —
+ * `subscribeRaw` / `publishRaw` / `unwrapRawChannelMessage` — which carry an
+ * arbitrary self-authenticating payload in place of the LXMF tail. The Delta's
+ * own Ed25519 signature (§5.3 field [7]) is the authenticity check at
+ * verify-on-ingest; the prelude's `sender_identity_pub` only identifies the
+ * transport sender.
+ *
+ * §11.2 targeted delivery and §11.3 air-gapped/optical transport still use full
+ * LXMF framing (`./lxmfSync.js`, Paper Messages); only the RFed broadcast
+ * channel uses the compact format.
  *
  * This module is part of the optional transport layer: importing the pure core
  * never pulls it in. It depends only on `@reticulum/core`, which the core
- * already depends on, so no new dependency is added.
+ * already depends on, so no new dependency is added. It mirrors
+ * `python/dacar/transport/rfed_sync.py` (the canonical implementation).
  *
  * Typical use:
  *
  * ```js
  * const client = new RFedClient({ identity, rns });
  * const sync = new RfedDeltaSync({ receiver: new DeltaReceiver(state, resolver), client });
- * await sync.subscribe(nodeHash);   // cache the channel's stamp cost
- * await sync.listen();              // receive live fanout Deltas
+ * await sync.subscribe(nodeHash);   // subscribeRaw: cache stamp cost + mark raw
+ * await sync.listen();              // receive live fanout Deltas (kind: "raw")
  * await sync.publish(deltaPayload, nodeHash);
  * ```
  */
 
 import {
-  LXMessage,
-  deliveryHashFor,
   deriveChannel,
-  unwrapChannelMessage,
-} from "@reticulum/core";
-import { LXMF_DELIVERY_TITLE, RFED_TOPIC } from "../naming.js";
-import { messageContent } from "./lxmfSync.js";
-
-/**
- * The shape of the decoded fanout callback argument from `RFedClient.listen`.
- * Only `message` is consumed here.
- * @typedef {Object} RfedDecoded
- * @property {import("@reticulum/core").LXMessage} message
- * @property {unknown} [senderIdentity]
- * @property {Uint8Array} [senderPub]
- * @property {Uint8Array} [sourceHash]
- * @property {boolean} [signatureValid]
- * @property {Uint8Array} [channelHash]
- * @property {string | null} [channelName]
- */
+  unwrapRawChannelMessage,
+} from "@reticulum/core/src/rfed/index.js";
+import { RFED_TOPIC } from "../naming.js";
 
 /**
  * The minimal `RFedClient` surface this adapter relies on. The real client from
- * `@reticulum/core` satisfies it; tests inject a fake.
+ * `@reticulum/core` satisfies it; tests inject a fake. The raw-publish API
+ * (`subscribeRaw` / `publishRaw`) carries a self-authenticating payload in the
+ * RTID prelude instead of an LXMF envelope (§11.1.1).
+ *
  * @typedef {Object} RFedClientLike
- * @property {(nodeHash: Uint8Array, channelName: string) => Promise<unknown>} subscribe
- * @property {(nodeHash: Uint8Array, channelName: string) => Promise<unknown>} [unsubscribe]
- * @property {(nodeHash: Uint8Array, channelName: string, lxmMessage: import("@reticulum/core").LXMessage) => Promise<unknown>} publish
+ * @property {(nodeHash: Uint8Array, channelName: string) => Promise<{ ok: boolean, stampCost: number | null }>} subscribeRaw
+ *   Subscribes and marks the channel raw so fanout is decoded via
+ *   `unwrapRawChannelMessage` (not the LXMF path).
+ * @property {(nodeHash: Uint8Array, channelName: string) => Promise<{ ok: boolean }>} [unsubscribe]
+ * @property {(nodeHash: Uint8Array, channelName: string, payload: Uint8Array) => Promise<void>} publishRaw
+ *   Fire-and-forget SEND of a raw application payload (wrapped in the RTID
+ *   prelude + EC-encrypted to the channel identity by the client).
  * @property {(nodeHash: Uint8Array, channelName: string) => Promise<{ items: Array<{ channelHash: Uint8Array, blob: Uint8Array }>, morePending: boolean }>} pull
- * @property {(onMessage: (decoded: RfedDecoded) => void) => Promise<Uint8Array>} listen
+ * @property {(onMessage: (decoded: RfedDecodedRaw) => void) => Promise<Uint8Array>} listen
+ *   Delivers a decoded fanout object; channels subscribed via `subscribeRaw`
+ *   carry `kind: "raw"` with a `payload` field (the unwrapped application
+ *   bytes). The client performs the EC-decrypt + RTID-prelude unwrap.
+ */
+
+/**
+ * The shape of the decoded fanout callback argument from `RFedClient.listen` for
+ * a raw channel. Only `kind` and `payload` are consumed here.
+ *
+ * @typedef {Object} RfedDecodedRaw
+ * @property {"raw"|"lxmf"} kind
+ * @property {Uint8Array} [payload] Raw application payload (`kind === "raw"`).
+ * @property {import("@reticulum/core/src/core/identity.js").Identity} [senderIdentity]
+ * @property {Uint8Array} [senderPub]
+ * @property {Uint8Array} [channelHash]
+ * @property {string} [channelName]
  */
 
 /**
@@ -97,42 +117,25 @@ export class RfedDeltaSync {
   }
 
   /**
-   * Builds the LXMF channel message wrapping one §5.3 Delta payload.
+   * Subscribes to the channel on a node (raw mode) and caches its advertised
+   * stamp cost. Call at least once per session and after any publish seems
+   * dropped.
    *
-   * The message's `sourceHash`/`destinationHash` are placeholders: the rfed
-   * Phase-0 codec (`wrapChannelMessage`) overwrites them with the channel's
-   * `lxmf.delivery` hashes before serialization, so the classic "source_hash
-   * is the bare identity hash" bug cannot occur.
-   * @param {Uint8Array} deltaPayload
-   * @returns {import("@reticulum/core").LXMessage}
-   */
-  makeMessage(deltaPayload) {
-    if (!(deltaPayload instanceof Uint8Array)) {
-      throw new TypeError("deltaPayload must be a Uint8Array");
-    }
-    return new LXMessage({
-      // Overwritten by the rfed codec before going on the wire.
-      destinationHash: new Uint8Array(16),
-      sourceHash: new Uint8Array(16),
-      content: new Uint8Array(deltaPayload),
-      title: LXMF_DELIVERY_TITLE,
-    });
-  }
-
-  /**
-   * Subscribes to the channel on a node, caching its advertised stamp cost.
-   * Call at least once per session and after any publish seems dropped.
+   * Uses `subscribeRaw` so incoming fanout is decoded via
+   * `unwrapRawChannelMessage` (the Dacar compact inner format), not the LXMF
+   * path. The wire protocol is identical to `subscribe` — the node never
+   * inspects the `inner_blob` — only this client's local decode changes.
    * @param {Uint8Array} nodeHash Any `rfed.*` destination hash of the node.
-   * @returns {Promise<unknown>} The client's `{ ok, stampCost }` result.
+   * @returns {Promise<{ ok: boolean, stampCost: number | null }>}
    */
   async subscribe(nodeHash) {
-    return this._client.subscribe(nodeHash, this._topic);
+    return this._client.subscribeRaw(nodeHash, this._topic);
   }
 
   /**
    * Removes the subscription.
    * @param {Uint8Array} nodeHash
-   * @returns {Promise<unknown>}
+   * @returns {Promise<{ ok: boolean }>}
    */
   async unsubscribe(nodeHash) {
     if (!this._client.unsubscribe) {
@@ -144,26 +147,34 @@ export class RfedDeltaSync {
   /**
    * Publishes a Delta to the channel (fire-and-forget, §11.1).
    *
-   * Call {@link subscribe} first so the channel's stamp cost is cached; an
-   * unstamped publish may be silently dropped by a cost-enforcing node.
+   * The client wraps the raw Delta in the RTID prelude + EC-encrypts it to the
+   * channel identity (`publishRaw` → `wrapRawChannelMessage`) and sends it as a
+   * fire-and-forget DATA packet. Call {@link subscribe} first so the channel's
+   * stamp cost is cached; an unstamped publish may be silently dropped by a
+   * cost-enforcing node. Returns `true` if the transport accepted the outbound
+   * packet (no throw) — transport acceptance ≠ node storage (fire-and-forget).
    * @param {Uint8Array} deltaPayload
    * @param {Uint8Array} nodeHash
-   * @returns {Promise<import("@reticulum/core").LXMessage>} The published message.
+   * @returns {Promise<boolean>}
    */
   async publish(deltaPayload, nodeHash) {
-    const message = this.makeMessage(deltaPayload);
-    await this._client.publish(nodeHash, this._topic, message);
-    return message;
+    if (!(deltaPayload instanceof Uint8Array)) {
+      throw new TypeError("deltaPayload must be a Uint8Array");
+    }
+    await this._client.publishRaw(nodeHash, this._topic, new Uint8Array(deltaPayload));
+    return true; // fire-and-forget: no throw ⇒ transport accepted the packet
   }
 
   /**
    * Starts listening for live fanout Deltas and routes each through
-   * verify-on-ingest (§11.1, §11.2.4).
+   * verify-on-ingest (§11.1, §11.2).
    *
-   * The channel is the feed discriminator, so every received message is a
-   * Dacar Delta; `DeltaReceiver.applyPayload()` authenticates it by signature
-   * and swallows any malformed/forged payload so a bad message can never crash
-   * the transport or mutate state.
+   * Because the channel was subscribed via `subscribeRaw`, the client decodes
+   * each fanout delivery with `unwrapRawChannelMessage` and the callback
+   * receives `{ kind: "raw", payload }`. The `payload` is the carried §5.3
+   * Delta, fed to `DeltaReceiver.applyPayload()`, which authenticates it by
+   * signature and swallows any malformed/forged payload so a bad message can
+   * never crash the transport or mutate state.
    * @returns {Promise<Uint8Array>} The local `rfed.delivery` destination hash.
    */
   async listen() {
@@ -172,11 +183,10 @@ export class RfedDeltaSync {
     }
     const receiver = this._receiver;
     return this._client.listen((decoded) => {
+      if (decoded?.kind !== "raw") return; // not a raw channel payload
       // RFedClient.invoke does not await the callback; run applyPayload without
       // leaving an unhandled rejection (it swallows malformed payloads itself).
-      Promise.resolve(receiver.applyPayload(messageContent(decoded.message))).catch(
-        () => {},
-      );
+      Promise.resolve(receiver.applyPayload(decoded.payload)).catch(() => {});
     });
   }
 
@@ -184,10 +194,12 @@ export class RfedDeltaSync {
    * Drains the node's deferred queue (offline catch-up) and routes each blob
    * through verify-on-ingest (§11.1).
    *
-   * Each blob is EC-decrypted with the derived channel identity and the
-   * recovered LXMF message's content is applied. Foreign/undecryptable blobs
-   * are dropped, not fatal. Repeats until the node reports no more pending
-   * pages. Returns the count of Deltas newly applied to the CRDT.
+   * Each blob is the EC-encrypted `inner_blob` (the node serves it verbatim, as
+   * stored); it is EC-decrypted with the derived channel identity and the
+   * recovered Dacar Delta (`unwrapRawChannelMessage`) is applied. Foreign/
+   * undecryptable blobs are dropped, not fatal. Repeats until the node reports
+   * no more pending pages. Returns the count of Deltas newly applied to the
+   * CRDT.
    *
    * > **Assumption:** the node serves each deferred entry's `blob` as the rfed
    * > `inner_blob` (the EC-encrypted channel message), matching the fanout
@@ -201,7 +213,6 @@ export class RfedDeltaSync {
       throw new Error("RfedDeltaSync.pull requires a receiver");
     }
     const { identity: channelIdentity } = await deriveChannel(this._topic);
-    const channelDeliveryHash = await deliveryHashFor(channelIdentity);
     const receiver = this._receiver;
     let applied = 0;
     let morePending = true;
@@ -209,19 +220,18 @@ export class RfedDeltaSync {
       const page = await this._client.pull(nodeHash, this._topic);
       for (const item of page.items) {
         try {
-          const decoded = await unwrapChannelMessage({
+          const decoded = await unwrapRawChannelMessage({
             innerBlob: item.blob,
             channelIdentity,
-            channelDeliveryHash,
           });
-          if (await receiver.applyPayload(messageContent(decoded.message))) {
+          if (await receiver.applyPayload(decoded.payload)) {
             applied++;
           }
         } catch {
           // a foreign/undecryptable blob is dropped, never fatal
         }
       }
-      morePending = page.morePending;
+      morePending = !!page.morePending;
     }
     return applied;
   }

package/src/tuple.js

@@ -105,7 +105,7 @@ export class Tuple {
     return toHex(this.preimage);
   }
 
-  /** Structural equality with another Tuple. @param {unknown} other @returns {boolean} */
+  /** Structural equality with another Tuple. @param {Tuple} other @returns {boolean} */
   equals(other) {
     if (!(other instanceof Tuple)) return false;
     return (