@calimero-network/mero-js 25.3.2 → 26.0.0

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
 export type { RelayClientConfig, RelayExecutor, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, FoundNamespaceInput, FoundedNamespace, } from './relay-client.js';
-export { createMemoryNonceSource, createLocalStorageNonceSource, createRecoveringNonceSource, authorNonceLookup, WarrantNonceExhaustedError, } from './nonce-source.js';
-export type { NonceSource, WarrantNonceLookup, RecoveringNonceSourceOptions, } from './nonce-source.js';
+export { createMemoryNonceSource, createLocalStorageNonceSource, } from './nonce-source.js';
+export type { NonceSource } from './nonce-source.js';

package/dist/relay/index.js

@@ -1,2 +1,2 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export { createMemoryNonceSource, createLocalStorageNonceSource, createRecoveringNonceSource, authorNonceLookup, WarrantNonceExhaustedError, } from './nonce-source.js';
+export { createMemoryNonceSource, createLocalStorageNonceSource, } from './nonce-source.js';

package/dist/relay/nonce-source.d.ts

@@ -22,7 +22,6 @@
  * is the one you have to ask for. It is also why a source may jump: reserving a
  * block and losing the tail is the correct trade.
  */
-import type { WarrantNonceState } from '../admin-api/admin-types.js';
 /** Produces the next nonce for one author device. Must never go backwards. */
 export interface NonceSource {
     next(): Promise<bigint>;
@@ -30,10 +29,10 @@ export interface NonceSource {
      * Raise the floor of the sequence to `floor`, if this source can record it.
      *
      * Optional, and additive: a source that does not implement it still works
-     * everywhere a `NonceSource` is taken, and {@link createRecoveringNonceSource}
-     * keeps the floor itself in that case. Implementing it is what lets a
-     * *persistent* source remember a jump, so a later cold start that cannot
-     * reach a node resumes above the mark rather than below it.
+     * everywhere a `NonceSource` is taken. Implementing it is what lets a caller
+     * that learns a higher spent nonce out of band — a refusal naming the nonce,
+     * say — skip ahead, and lets a *persistent* source remember that jump across
+     * a cold start.
      *
      * Never lowers: a smaller `floor` than the source's own position is ignored.
      */
@@ -71,125 +70,3 @@ export declare function createLocalStorageNonceSource(key: string, storage?: {
     getItem(k: string): string | null;
     setItem(k: string, v: string): void;
 }): NonceSource;
-/** A node (or anything else) that can answer where a device's sequence stands. */
-export interface WarrantNonceLookup {
-    getWarrantNonce(contextId: string, authorDeviceKey: string): Promise<WarrantNonceState>;
-}
-/**
- * A lookup a delegated client can actually use.
- *
- * {@link WarrantNonceLookup} names the device key because the admin route takes
- * it in the path. The delegated route does not: it reads the key from the
- * certificate it verifies, so the only way to ask is to present that
- * certificate. This adapter bridges the two — it satisfies the interface, and
- * ignores the device key argument because the credential already determines it.
- *
- * That the argument is ignored is not an oversight to tidy away. The whole
- * point of the delegated route is that the device key is not caller-supplied:
- * a key passed alongside the proof would be a second spelling of a fact the
- * signature already fixes, and two spellings can differ. The adapter therefore
- * has nothing to check it against, and pretending otherwise would invent a
- * comparison the protocol deliberately does not make.
- *
- * Use with {@link createRecoveringNonceSource} exactly as an `AdminApiClient`
- * would be used — on a relay, this is the form that works.
- */
-export declare function authorNonceLookup(options: {
-    /** Anything that can reach the node's admin path; an `AdminApiClient` does. */
-    client: {
-        getWarrantNonceAsAuthor(contextId: string, authorProof: string): Promise<WarrantNonceState>;
-    };
-    /** Hex borsh `AccountProof<DeviceCert>` — the same one the relay client sends. */
-    authorProof: string;
-}): WarrantNonceLookup;
-/** Thrown when every node asked says this device has spent `u64::MAX` here. */
-export declare class WarrantNonceExhaustedError extends Error {
-    readonly contextId: string;
-    readonly authorDeviceKey: string;
-    name: string;
-    constructor(contextId: string, authorDeviceKey: string);
-}
-/** What {@link createRecoveringNonceSource} needs to know. */
-export interface RecoveringNonceSourceOptions {
-    /**
-     * The node(s) to ask. Pass an {@link AdminApiClient} — it satisfies this
-     * structurally — or several, one per relay this author writes through.
-     *
-     * With more than one, the **highest** answer wins. Nonce state folds per peer,
-     * so a node can only be behind a client whose warrants it has not applied,
-     * never ahead of the truth; taking the highest is therefore the only reading
-     * that cannot hand out a nonce somebody has already spent.
-     */
-    lookups: WarrantNonceLookup | readonly WarrantNonceLookup[];
-    contextId: string;
-    /** The author device's SIGNING key, base58 or hex. Not its `deviceId`. */
-    authorDeviceKey: string;
-    /**
-     * The client's own counter, folded in with `max`. Defaults to an in-memory
-     * one starting at 1.
-     *
-     * Pass {@link createLocalStorageNonceSource} to keep both halves: the local
-     * counter carries the sequence forward between calls, the node supplies the
-     * floor when that counter has been cleared.
-     */
-    local?: NonceSource;
-    /**
-     * What to do when no node can be reached on the cold-start lookup.
-     *
-     * `'throw'` (the default) refuses to mint. That is the conservative reading:
-     * a source that quietly fell back to a cleared local counter would replay
-     * spent nonces, which is the exact failure this exists to prevent, and it
-     * would do it invisibly. `'local'` mints from the local counter anyway —
-     * correct only when that counter is known to be intact and the app would
-     * rather write offline than not at all.
-     */
-    onLookupFailure?: 'throw' | 'local';
-}
-/**
- * A nonce source that asks the node where the sequence stands before its first
- * mint, then carries on locally.
- *
- * # Why this is not the default
- *
- * It costs a round trip and an admin credential, and an author that never lost
- * its counter gains nothing from it. It earns its place in exactly one
- * situation, which is common rather than exotic: a client whose local state is
- * gone. A browser keyholder lives in storage that is partitioned per top-level
- * site and cleared on a schedule it does not control, so for it, losing the
- * counter is the normal lifecycle. Without this, such a client either restarts
- * at 1 — replaying every nonce it already spent, each write refused, which
- * reads to the user as the app silently not saving — or guesses upward, one
- * burnt round trip per wrong guess.
- *
- * # What it does
- *
- * The lookup happens once, lazily, on the first {@link NonceSource.next}: a
- * source that is constructed and never used costs nothing, and an app that
- * builds its relay client at startup does not pay a network call for it. The
- * answer becomes a **floor**, and every nonce handed out afterwards is
- * `max(localCounter, floor)`. It never goes backwards from either input, which
- * is the one property a nonce source owes its caller.
- *
- * If the local counter is the one that is ahead, it wins — the node may simply
- * not have applied this client's recent warrants yet.
- *
- * The floor is also pushed into the local source through
- * {@link NonceSource.advanceTo} when it has one, so a persistent counter
- * remembers the jump.
- *
- * # Exhaustion
- *
- * A node reporting no `nextNonce` means `u64::MAX` is spent and this device can
- * never write here again. `next()` rejects with
- * {@link WarrantNonceExhaustedError} rather than guessing, because every guess
- * from there is refused forever.
- *
- * # On an older node
- *
- * The route is new and absent from core `master` builds, which answer 404 —
- * {@link AdminApiClient.getWarrantNonce} surfaces that as
- * `WarrantNonceRouteUnavailableError`. It reaches the caller as a lookup
- * failure, so `onLookupFailure` decides: refuse to mint, or fall back to the
- * local counter.
- */
-export declare function createRecoveringNonceSource(options: RecoveringNonceSourceOptions): NonceSource;

package/dist/relay/nonce-source.js

@@ -77,8 +77,8 @@ export function createLocalStorageNonceSource(key, storage) {
     // already written would replay. But the client cannot know, and 1 is the only
     // defensible start, so it is what a fresh key gets. This is why the doc above
     // tells apps to key per device: a device whose storage was cleared should be
-    // re-paired rather than resumed — or handed a recovering source, which asks
-    // the node what it already spent instead of guessing.
+    // re-paired rather than resumed. No node serves a "where does my sequence
+    // stand" lookup, so the local counter is the only record there is.
     const lastHandedOut = () => {
         const raw = store.getItem(key);
         if (raw === null || raw === '')
@@ -109,155 +109,3 @@ export function createLocalStorageNonceSource(key, storage) {
         },
     };
 }
-/**
- * A lookup a delegated client can actually use.
- *
- * {@link WarrantNonceLookup} names the device key because the admin route takes
- * it in the path. The delegated route does not: it reads the key from the
- * certificate it verifies, so the only way to ask is to present that
- * certificate. This adapter bridges the two — it satisfies the interface, and
- * ignores the device key argument because the credential already determines it.
- *
- * That the argument is ignored is not an oversight to tidy away. The whole
- * point of the delegated route is that the device key is not caller-supplied:
- * a key passed alongside the proof would be a second spelling of a fact the
- * signature already fixes, and two spellings can differ. The adapter therefore
- * has nothing to check it against, and pretending otherwise would invent a
- * comparison the protocol deliberately does not make.
- *
- * Use with {@link createRecoveringNonceSource} exactly as an `AdminApiClient`
- * would be used — on a relay, this is the form that works.
- */
-export function authorNonceLookup(options) {
-    return {
-        getWarrantNonce: (contextId, _authorDeviceKey) => options.client.getWarrantNonceAsAuthor(contextId, options.authorProof),
-    };
-}
-/** Thrown when every node asked says this device has spent `u64::MAX` here. */
-export class WarrantNonceExhaustedError extends Error {
-    constructor(contextId, authorDeviceKey) {
-        super(`author device ${authorDeviceKey} has spent every nonce in context ${contextId}; it must re-key to write again`);
-        this.contextId = contextId;
-        this.authorDeviceKey = authorDeviceKey;
-        this.name = 'WarrantNonceExhaustedError';
-    }
-}
-/**
- * A nonce source that asks the node where the sequence stands before its first
- * mint, then carries on locally.
- *
- * # Why this is not the default
- *
- * It costs a round trip and an admin credential, and an author that never lost
- * its counter gains nothing from it. It earns its place in exactly one
- * situation, which is common rather than exotic: a client whose local state is
- * gone. A browser keyholder lives in storage that is partitioned per top-level
- * site and cleared on a schedule it does not control, so for it, losing the
- * counter is the normal lifecycle. Without this, such a client either restarts
- * at 1 — replaying every nonce it already spent, each write refused, which
- * reads to the user as the app silently not saving — or guesses upward, one
- * burnt round trip per wrong guess.
- *
- * # What it does
- *
- * The lookup happens once, lazily, on the first {@link NonceSource.next}: a
- * source that is constructed and never used costs nothing, and an app that
- * builds its relay client at startup does not pay a network call for it. The
- * answer becomes a **floor**, and every nonce handed out afterwards is
- * `max(localCounter, floor)`. It never goes backwards from either input, which
- * is the one property a nonce source owes its caller.
- *
- * If the local counter is the one that is ahead, it wins — the node may simply
- * not have applied this client's recent warrants yet.
- *
- * The floor is also pushed into the local source through
- * {@link NonceSource.advanceTo} when it has one, so a persistent counter
- * remembers the jump.
- *
- * # Exhaustion
- *
- * A node reporting no `nextNonce` means `u64::MAX` is spent and this device can
- * never write here again. `next()` rejects with
- * {@link WarrantNonceExhaustedError} rather than guessing, because every guess
- * from there is refused forever.
- *
- * # On an older node
- *
- * The route is new and absent from core `master` builds, which answer 404 —
- * {@link AdminApiClient.getWarrantNonce} surfaces that as
- * `WarrantNonceRouteUnavailableError`. It reaches the caller as a lookup
- * failure, so `onLookupFailure` decides: refuse to mint, or fall back to the
- * local counter.
- */
-export function createRecoveringNonceSource(options) {
-    const lookups = Array.isArray(options.lookups)
-        ? options.lookups
-        : [options.lookups];
-    if (lookups.length === 0) {
-        throw new Error('a recovering nonce source needs at least one node to ask');
-    }
-    const local = options.local ?? createMemoryNonceSource(1);
-    const onLookupFailure = options.onLookupFailure ?? 'throw';
-    let floor = null;
-    // Memoised so concurrent first calls ask once. Cleared on failure, since a
-    // node that was unreachable a moment ago may answer the next call — caching
-    // the failure would make one flaky request poison the whole session.
-    let pending = null;
-    const resolveFloor = async () => {
-        const answers = await Promise.allSettled(lookups.map((lookup) => lookup.getWarrantNonce(options.contextId, options.authorDeviceKey)));
-        let highest = null;
-        let exhausted = false;
-        for (const answer of answers) {
-            if (answer.status !== 'fulfilled')
-                continue;
-            const state = answer.value;
-            if (state.kind === 'exhausted') {
-                exhausted = true;
-                continue;
-            }
-            if (highest === null || state.nextNonce > highest)
-                highest = state.nextNonce;
-        }
-        // Exhaustion is only decisive when nothing usable came back. One node
-        // saturated while another still has room is not a thing the ledger can
-        // produce — the sequence is the device's, not the node's — but if it ever
-        // is, the usable answer is the actionable one.
-        if (highest === null && exhausted) {
-            throw new WarrantNonceExhaustedError(options.contextId, options.authorDeviceKey);
-        }
-        if (highest === null) {
-            const first = answers.find((a) => a.status === 'rejected');
-            const reason = first && first.status === 'rejected' ? first.reason : undefined;
-            if (onLookupFailure === 'local') {
-                floor = 0n;
-                return;
-            }
-            throw reason instanceof Error
-                ? reason
-                : new Error(`no node could answer where the warrant-nonce sequence stands: ${String(reason)}`);
-        }
-        floor = highest;
-        await local.advanceTo?.(highest);
-    };
-    return {
-        async next() {
-            if (floor === null) {
-                pending ?? (pending = resolveFloor().finally(() => {
-                    pending = null;
-                }));
-                await pending;
-            }
-            const mine = await local.next();
-            const value = floor !== null && floor > mine ? floor : mine;
-            // Advance the floor past what was just handed out, so a local source that
-            // is behind cannot re-offer this number on the next call.
-            floor = value + 1n;
-            return value;
-        },
-        async advanceTo(wanted) {
-            if (floor === null || wanted > floor)
-                floor = wanted;
-            await local.advanceTo?.(wanted);
-        },
-    };
-}

package/dist/relay/relay-client.d.ts

@@ -76,9 +76,9 @@ export interface RelayClientConfig {
     /**
      * Where nonces come from. See {@link NonceSource} — a reset replays.
      *
-     * A client whose storage may be cleared between sessions should wrap its
-     * counter in `createRecoveringNonceSource`, which asks the node where the
-     * sequence actually stands before the first mint instead of restarting at 1.
+     * Persist it (`createLocalStorageNonceSource` in a browser): the node keeps
+     * the spent ledger but serves no lookup of it, so the client's own counter is
+     * the only record of where the sequence stands.
      */
     nonces: NonceSource;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "25.3.2",
+  "version": "26.0.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {