Skip to main content

auki-network

Synced from the repository

This page mirrors crates/auki-network/README.md in the auki-sdk repo (branch develop). The repository is the source of truth.

The libp2p substrate for the SDK and the Discovery HTTP client. Behind the swarm feature: TCP/QUIC transport, Noise, Yamux, Circuit Relay v2, identify, ping, and a native helper for reserving a relay-mediated Manager address through a Domain Relay. On top: the typed /auki/stream/0.2.0 stream protocol, live /auki/message/0.1.0 typed messaging, and the peer-to-peer lifecycle protocols (join, heartbeat, membership, info, resources, registries). The Discovery client carries both Manager multiaddrs and optional Relay multiaddrs for browser-compatible reachability hints.

Peer identity is derived from a wallet: Wallet::derive_child("peer/v1"). The app_instance value is MAC-derived per machine.

Status: Shipped.

Public surface​

  • Types: PeerIdentity, ParticipantInfo, ReachabilityRecord, Capability
  • Modules: swarm, network_runtime, join_protocol, heartbeat_protocol, membership_protocol, info_protocol, resources_protocol, resources_v3_protocol, resources_v4_protocol, message_protocol, stream_protocol, stream_runtime, app_instance, discovery_client
  • SessionHandle trait — implemented by auki_session::Session; called by the resources protocol handler to serve catalog rows to remote peers. Defined here to break the potential auki-domain ↔ auki-session cycle.
  • Resource catalog protocol /auki/resources/0.2.0: ResourceEntry rows discriminated by variant (sensor_log | pose_log | time_transform_log | detection_log). Each row has source_peer_id, writer_peer_id, resource_id, state, head | extent, available, optional sensor block (only on sensor_log: kind/type/sensor_id/sensor_hash), optional pose block (only on pose_log: writer_mode), and a variant-specific manifest pointer. Replaces the old SensorStreamResource / TransformEdgeResource / PoseStreamResource types.
  • /auki/resources/0.2.0 is a live, pollable snapshot of currently requestable resources. Peers may join before resources are ready; producers omit resources that cannot currently accept stream opens; consumers poll and reconcile row additions/removals. resource_id values stay stable across temporary outages. The current schema has no unavailable/degraded state, so absence from the catalog is the unavailability signal.
  • Resource catalog protocol /auki/resources/0.3.0 is additive: it preserves v0.2 rows and adds receiver-owned message_channel rows containing owner_peer_id, resource_id, and an existing clock RegistryRef. Fetch v0.3 explicitly with request_resources_catalog_v3_with; an unsupported peer returns RequestResourcesV3Error::UnsupportedProtocol and never silently falls back to v0.2.
  • Resource catalog protocol /auki/resources/0.4.0 discovers live MapLogResource rows. Each row pins source/writer identities plus exact Map and clock Registry refs. MapCatalogProvider supplies fresh snapshots; request_map_catalog fetches them explicitly.
  • Typed-message protocol /auki/message/0.1.0: NetworkRuntime::register_message_channel(resource, capacity) atomically binds a catalog row to a bounded live receiver; open_message_channel(owner, resource_id, expected_clock) returns a persistent MessageChannelSender only when the receiver's current clock RegistryRef exactly matches the discovered row, so stale rows cannot silently change timestamp meaning. send(type, timestamp_ns, payload) resolves after transport acceptance into the receiver queue. If the event is enqueued but the ACK is lost, send returns an error with indeterminate delivery; callers must not automatically retry. Type, timestamp, and payload are opaque to the SDK.
  • Typed messages are live and ephemeral: no history, persistence, queue across disconnect, retry, replay, materialization, or application outcome semantics. The channel Resource declares the clock; messages carry only timestamp_ns.
  • A message-channel registration exists only while its receiver or owning runtime exists. Dropping the receiver removes the v0.3 row and closes active endpoints; runtime shutdown drains all registrations and closes retained receivers.
  • Security is intentionally coarse for this milestone: any current Noise-authenticated cluster member may send. There is no generic channel-level ACL. The NetworkRuntime allow-list prevents unknown or removed peers from delivering payloads to an app receiver.
  • Stream request type StreamRequest { source_peer_id, resource_id, read_from } where read_from is a oneof (latest, from_start, from_timestamp(i64)).
  • Typed stream payloads: camera, point cloud, joint encoders, audio, non-spatial scalar Data, pose SpatialTransform, detection frames, and sparse MapUpdates. StreamDispatch::AcceptScalar and open_stream::<scalar::Data> use the same protobuf payload as Scalar Sensor Logs.
  • Relay reachability: swarm::reserve_relay_circuit_addr reserves /p2p-circuit on a relay and returns the Manager circuit address to publish; discovery_client derives relay_multiaddrs from circuit Manager addresses when creating or rotating Discovery entries.
  • Runtime relay reachability: NetworkRuntimeHandle::reserve_relay_circuit_addr lets a runtime-owned swarm reserve a Manager circuit address after spawn, for promotion/rotation flows.
  • Discovery: ClusterEntry.relay_multiaddrs, create_cluster_with_relay_multiaddrs, rotate_manager_with_relay_multiaddrs
  • Constants: PEER_DERIVATION_LABEL = "peer/v1"
  • Locked vectors pin seed → PeerId and the stream wire bytes across language reimplementations.

Depends on​

  • auki-identity — for Wallet and child derivation.
  • auki-datatypes (optional) — for stream payload types.
  • auki-time (optional) — for clock-stamped peer messages.
  • auki-jcs (optional) — for canonical-JSON peer protocol bodies.