Skip to content

The Rust side ​

Three Rust libraries sit beside @flowsta/holochain. One is required for a linked app. The other two are optional, and you take them one piece at a time.

A Holochain desktop app (Tauri, or anything with a Rust back end) has two places that can talk to the person's Flowsta Vault: the page in the window, and the Rust process behind it. The page uses @flowsta/holochain. This page is about the Rust process: what Flowsta publishes for it, what each library gives your app, and what you can leave out.

The three libraries ​

LibraryWhat it isWhere it runsDo you need it?
flowsta-agent-linkingTwo zomes that record, on your app's own network, that your app's agent and a Flowsta identity belong to the same personIn your DNARequired for a linked app
flowsta-vault-clientFinds the person's Vault from Rust, says which app a call is from, keeps the sign-in on the device, and keeps your app's own device key where a backup can carry itIn your app's Rust processOptional. Needed once your Rust side calls the Vault or holds keys or profiles
flowsta-hc-linesRuns a Holochain conductor and key store inside a desktop app, keeps them running, and stops them cleanlyIn your app's Rust processOptional. It has nothing to do with identity; use it if you want the conductor handled for you

All three are MIT licensed and public on GitHub. The two libraries for the Rust process are before 1.0: depend on them from git and pin a commit.

What is required ​

For an app that links its agent to a Flowsta identity:

  1. A client_id, and the addresses your app connects from, from dev.flowsta.com. See Register Your App.
  2. The two flowsta-agent-linking zomes in your DNA, at the tag for your Holochain version. See Agent Linking.
  3. @flowsta/holochain in the page, to ask the Vault for the link (linkFlowstaIdentity) and to tell it when the person disconnects (revokeFlowstaIdentity). The person approves the link in their Vault; that step always starts from the page.
  4. One zome call, create_external_link, with the signature the Vault returned. Make it from the page or from Rust.

That is a complete linked app. Nothing in Rust beyond your own zome call is required.

What is optional, and what each piece depends on ​

Take a row when your app needs what it gives. "Depends on" lists the other rows a piece needs first.

Identity and the Vault (flowsta-vault-client) ​

Your app getsModuleDepends onHow to
Rust calls to the Vault that find the right Vault and say which app they are fromvaultThe link token from the page's sign-inTalk to the Vault from Rust
The sign-in kept on the device, and a check before each write, so the app works with the Vault locked or closedidentityvaultCheck before a write
The person's name and picture shown while the Vault is closedidentityvaultShow who is signed in
Opening the Vault app for the personvaultNothingOpen the Vault
Your app's own device key in a file, so a Vault backup can carry itdevice_seedImporting the seed into your key storeKeep the device key
Backups that never replace a key the person still needsadoptvault, device_seed, backups from the pageBack up safely
The same key, and so the same author, on a new computeradoptThe two rows above, and a way to stop your conductorCarry on from a new computer
One profile per Flowsta identity on one installprofilesidentity, device_seedOne profile per identity

Running Holochain in the app (flowsta-hc-lines) ​

Your app getsModuleDepends onHow to
A conductor and key store started, watched and stopped by the librarysupervisor, conductor, keystoreBundled conductor and key store binariesRun a conductor
Conductors asked to shut down properly at quit, and any left behind by a crash ended at the next launchprocess, reapNothingStop cleanly
A start that works with no network, and a device that stays listed for its peersrendezvous, keeperThe supervisorOffline starts and staying listed
A stopped conductor brought back, and a restart before memory runs outwatchThe supervisorKeep it running
A key's own history restored on a new device (Holochain 0.7)admin, restoreThe supervisor, and the device key from flowsta-vault-clientRestore on a new device
Two Holochain versions side by side, and the person's data moved from the old one to the new onefeatures line-06 and line-07; marker, pass, policyThe supervisorTwo versions side by side
A fix for a window crash on Linux computers with NVIDIA graphicswebviewNothingThe Linux window fix

Features that need no Rust library ​

These work from the page alone, through @flowsta/holochain:

Page or Rust: which side does what ​

JobPage (@flowsta/holochain)Rust (flowsta-vault-client)
Ask the Vault for the link; the person approvesYesNo. The approval starts from the page
Tell the Vault the person disconnectedYesNo
Post and read backupsYesReads the backup, for the key check and the restore
Sign a document, sign in to a web serviceYesNo
Find the Vault among its portsYesYes, and it ignores a Vault that belongs to another user account on the same computer
Present your app's originThe window's origin, set by the systemThe origin you choose, so it can match the window's
Keep the link tokenBrowser storageA file of your app's, set at each start
Check the sign-in before a write inside a commandNoYes
Keep a device key, replace it, keep profilesNoYes

The rule of thumb. If the page makes every call to the Vault, and your Rust side never calls the Vault and never manages keys or profiles, your app needs only @flowsta/holochain and the linking zomes. Add flowsta-vault-client when your Rust side does any of these:

  • checks who is signed in before a zome write;
  • reads the Vault backup (the key check, a restore);
  • keeps your app's own device key, or replaces it;
  • keeps one profile per identity;
  • must ignore another user account's Vault on a shared computer.

Electron and other JavaScript desktop apps ​

An Electron app has no Rust process, and it does not need one. @flowsta/holochain is the whole Flowsta client there: linking, the link token, link status, backups and restore, signing, and finding the Vault among its ports. Make the calls from the window, which is where the request gets its origin. The linking zomes go in your DNA exactly as for any other app.

Four things to know:

  • Serve the window from an origin. The Vault tells apps apart by the origin a request carries. Load your window from a scheme of your own (app://yourapp, registered with Electron as a standard scheme so that requests carry it) or a local port, and register that origin. A window loaded straight from a file has no origin the Vault can check.
  • Calls from the main process say which origin they are. Node sends no origin by itself. If your main process (or a tool beside your app) calls the Vault, call setVaultOrigin with your registered origin first; without it the Vault refuses the request to connect.
  • Keep the link token with your app's data. The SDK keeps it in the window's storage by default. If you keep a profile per identity, or your app's storage is cleared between runs, store the token yourself and hand it back at startup with setVaultLinkToken.
  • The parts on this page that are Rust-only are conveniences built on the public Vault IPC and on plain files: the check before a write, the device key file, the safe order for replacing a key, profile folders, and running the conductor. An Electron app that wants them writes them in JavaScript against the same endpoints. The how-tos on the two library pages describe each one closely enough to follow.

Where the pieces meet ​

A Tauri app that uses all of it starts like this. Each step is optional except where your own app needs it.

rust
fn main() {
    // flowsta-hc-lines: both must run before anything else.
    flowsta_hc_lines::process::interrupt_helper_or_continue();
    flowsta_hc_lines::webview::apply();

    // flowsta-hc-lines: end any conductor a crashed run left behind.
    flowsta_hc_lines::reap::reap_orphaned_sidecars(&["holochain", "lair-keystore"]);

    // flowsta-vault-client: one client for every Rust call to the Vault.
    // (see "Talk to the Vault from Rust")

    // flowsta-vault-client: pick the profile for the identity the Vault holds,
    // load that profile's link token, then start the conductor in that folder.
}

ProofPoll is a complete open-source app built this way: a Tauri app on a shared network, linked to Flowsta, with backups that carry its device key. Its src-tauri/src/ folder has a working version of every how-to on these pages.

Versions ​

LibraryVersionHolochainRust
flowsta-agent-linkingtag v0.4.00.7.1 (hdi =0.8.1, hdk =0.7.1)1.94 or later
flowsta-agent-linkingtag v0.3.00.6.x (hdi =0.7.0, hdk =0.6.0)
flowsta-vault-client0.2Any; it has no Holochain dependency1.93 or later
flowsta-hc-lines0.10.7.1 (feature line-07), 0.6.1 (feature line-06)1.93 or later
@flowsta/holochain3.11.0Any

The link token and the "which app is calling" checks described on these pages apply from Vault 1.8.0. An older Vault ignores the extra fields, so one build of your app works with both.

Next ​

Documentation licensed under CC BY-SA 4.0.