Sync

The private balance lives on the user's device. syncNoteStore brings it up to date with Solana and Nimbus's indexer. Why the device syncs explains the reason.

Every payment syncs before it starts. Between payments, syncing is up to you. In this guide, Alice's app syncs when she opens it, then every 15 seconds while the tab is visible.

Sync onceCopy Anchor Link

import { syncNoteStore } from "@umbra/nimbus-solana-web";

const result = await syncNoteStore(session, {});

switch (result.kind) {
  case "ingested":
    console.log(`Synced through slot ${result.slot}.`, result.caughtUp);
    break;
  case "unregistered":
    console.log("Register first. There is nothing to sync yet.");
    break;
  case "unavailable":
    console.log(`Stopped at ${result.step}. The next sync carries on.`);
    break;
}

The resultCopy Anchor Link

unavailable also carries step, the step that stopped, and detail. Both are for your logs.

A sync throws a NimbusSdkError when it cannot go on. The reason is service-unavailable when the indexer or the RPC cannot be reached. It is unreadable when either answers something that cannot be read.

What caughtUp meansCopy Anchor Link

A sync runs in rounds. Each round reads one page of everything new, up to pageRows rows.

caughtUp is true when the last round reached the end of everything new. It is false only when maxRounds ran out first. Sync again to read the rest.

OptionsCopy Anchor Link

A maxRounds or pageRows outside its range throws a NimbusSdkError with reason misconfigured, before anything is fetched.

When the signal aborts, the sync stops between rounds. It rejects with the signal's reason, and what earlier rounds took in stays.

Sync in the backgroundCopy Anchor Link

This recipe syncs every 15 seconds while the tab is visible. It reads a few rounds at a time, never runs two syncs at once, and returns a function that stops it:

import { syncNoteStore } from "@umbra/nimbus-solana-web";

function startBackgroundSync(session: NimbusSession): () => void {
  const controller = new AbortController();
  let syncing = false;

  const tick = async (): Promise<void> => {
    if (syncing || document.visibilityState !== "visible") return;
    syncing = true;
    try {
      const result = await syncNoteStore(
        session,
        {},
        { maxRounds: 3, signal: controller.signal },
      );
      if (result.kind === "ingested") await refreshBalances();
    } catch (thrown) {
      if (!controller.signal.aborted) console.error(thrown);
    } finally {
      syncing = false;
    }
  };

  void tick();
  const timer = setInterval(() => void tick(), 15_000);

  return () => {
    clearInterval(timer);
    controller.abort();
  };
}

Call the stop function before you close the session. A sync that is still running then stops at the end of its round.

What a sync also doesCopy Anchor Link

• It frees stopped payments. A payment whose tab closed before it sent anything holds part of the balance. A sync gives it back. See Reserved funds.
• It serves every tab. Each tab of your app on the same site reads the same device storage. A sync in one tab updates the balance for all of them.

Two tabs syncing at once is safe, but wasted work. A step that keeps losing to the other tab returns unavailable, and the next sync finishes it.

NextCopy Anchor Link