Hubert - Distributed Infrastructure for Secure Multiparty Transactions - v1.0.0-alpha.20
    Preparing search index...

    Interface KvStore

    Unified interface for key-value storage backends using ARID-based addressing.

    All implementations provide write-once semantics: once an envelope is stored at an ARID, subsequent attempts to write to the same ARID will fail with an AlreadyExistsError.

    • ARID holder can read (by deriving storage key)
    • ARID creator can write once (by deriving storage key)
    • Storage networks see only derived keys, never ARIDs themselves
    • ARIDs shared only via secure channels (GSTP, Signal, QR codes)
    • MainlineDhtKv: Fast, lightweight DHT storage (≤1 KB messages)
    • IpfsKv: Large capacity, content-addressed storage (up to 10 MB messages)
    • HybridKv: Automatic optimization by size, combining DHT speed with IPFS capacity
    • ServerKvClient: HTTP client for centralized server backend

    Port of trait KvStore from kv_store.rs lines 81-214.

    interface KvStore {
        put(
            arid: ARID,
            envelope: Envelope,
            ttlSeconds?: number,
            verbose?: boolean,
        ): Promise<string>;
        get(
            arid: ARID,
            timeoutSeconds?: number,
            verbose?: boolean,
        ): Promise<Envelope | null>;
        exists(arid: ARID): Promise<boolean>;
    }

    Implemented by

    Index

    Methods

    put get exists

    Methods

    • Store an envelope at the given ARID.

      This operation will fail if the ARID already exists. The implementation must check for existence before writing and return an appropriate error if the key is already present.

      Parameters

      • arid: ARID

        Cryptographic identifier for this storage location

      • envelope: Envelope

        The envelope to store

      • OptionalttlSeconds: number

        Optional time-to-live in seconds. After this time, the envelope may be removed from storage.

        • Mainline DHT: Ignored (no TTL support)
        • IPFS: Used as IPNS record lifetime (default: 24h if undefined)
        • Server: Clamped to max_ttl if exceeded; uses max_ttl if undefined. All entries expire (hubert is for coordination, not long-term storage).
      • Optionalverbose: boolean

        If true, log operations with timestamps

      Returns Promise<string>

      A receipt containing storage metadata on success

      If the ARID already exists

      If the envelope is too large for this backend

      If network operation fails

      If serialization fails

      const arid = ARID.new();
      const envelope = Envelope.new("Hello, Hubert!");

      // Store without TTL
      const receipt = await store.put(arid, envelope);

      // Store with 1 hour TTL and verbose logging
      const arid2 = ARID.new();
      const receipt2 = await store.put(arid2, envelope, 3600, true);
      console.log("Stored at:", receipt2);

    • Retrieve an envelope for the given ARID.

      Polls the storage backend until the envelope becomes available or the timeout is reached. This is useful for coordinating between parties where one party puts data and another polls for it.

      Parameters

      • arid: ARID

        The ARID to look up

      • OptionaltimeoutSeconds: number

        Maximum time to wait for the envelope to appear. If undefined, uses a backend-specific default (typically 30 seconds). After timeout, returns null rather than continuing to poll.

      • Optionalverbose: boolean

        If true, log operations with timestamps and print polling dots

      Returns Promise<Envelope | null>

      The envelope if found within the timeout, or null if not found

      On network or deserialization errors

      // Wait up to 10 seconds for envelope to appear with verbose logging
      const envelope = await store.get(arid, 10, true);
      if (envelope) {
        console.log("Found:", envelope);
      } else {
        console.log("Not found within timeout");
      }

    • Check if an envelope exists at the given ARID.

      Parameters

      • arid: ARID

        The ARID to check

      Returns Promise<boolean>

      true if the ARID exists, false otherwise

      On network errors

      For hybrid storage, this only checks the DHT layer. Reference envelopes count as existing even if the referenced IPFS content is not available.

      if (await store.exists(arid)) {
        console.log("ARID already used");
      } else {
        console.log("ARID available");
      }

    Settings

    Member Visibility

    On This Page

    Security ModelImplementations
    Methods