Desktop Companion

Architecture overview

The desktop app is an Electron shell. The renderer process loads a thin React UI that talks to a local backend running in the main process. The main process owns the Sui RPC client, the Walrus blob client, the Seal session keys, and the local cache. For protected persona sprites, the main process decrypts locally and returns an explicit byte payload to the renderer so the renderer can populate the local persona cache; the bytes remain on the user's machine and are not sent back to Soulidity servers.

• Web app handles login, mint, market, grants, paid access — anything that requires a wallet signature happens in the browser.
• Desktop app renders the persona and runs the chat agent. It links to the web account, stores its desktop token and agent key locally, and authorizes itself as a grant agent when protected content requires it.
• Both apps share the same Sui mainnet state. The DB mirror behind the web app is non-authoritative — desktop fetches live chain state when issuing Seal approvals.

Sprite & audio grant flow

When the desktop app first opens a Soul whose sprite or audio is not public, it walks the user through a single grant TX that authorizes the desktop wallet to decrypt those blobs.

1. Desktop reads the Soul state and asks: do I already hold a SoulGrant for this Soul with at least SCOPE_ASSETS (bit 8)?
2. If not, it prompts the user (the Soul owner) to sign grant::issue_to_grantee with the desktop wallet address as grantee. Default expiry is null (no TTL) — termination is by explicit revoke.
3. After confirmation, the desktop app records the grant in its local cache and fetches the active sprite + audio versions.
4. If you later add a sprite/audio version, auto-grant on append tops up any agent (including this desktop agent) whose existing scopes don't cover the new content. See Agent Integration.

Protected-sprite IPC

For persona sprites bound under non-public read modes, the renderer fetches a Soul access payload, then asks the main process to decrypt that payload:

// Renderer → main
ipcRenderer.invoke('soul:decrypt-protected-sprite', {
  access: privateAccessPayload,
})
// → { bytes: Uint8Array, fileName: 'sprite.png', mimeType: 'image/png' }

ipcRenderer.invoke('soul:cache-persona', {
  catalogId,
  sourceType: 'soul',
  sourceRef: soulId,
  version,
  spriteBytes: decrypted.bytes,
  configJson,
})

The main process validates the access payload, pulls the encrypted blob from Walrus, decrypts it locally, and returns the decrypted bytes to the renderer. The renderer immediately hands those bytes back to soul:cache-persona; the main process writes the sprite and config into the desktop cache under the app's local user-data directory. The plaintext cache is local to the machine and is not uploaded to Soulidity servers.

Mint completion callback

After a Mint By Web hand-off finishes minting, the web app can notify the desktop app through the registered custom protocol:

soulidity://mint-completed?token=mh_...

The desktop app registers soulidity:// via app.setAsDefaultProtocolClient. The current handler accepts mint-completed to clear the local extract draft and bring the main window forward. It does not currently implement a soulidity://open?soulId=... purchase or mint handoff route.

Install & upgrade

• Install. Download the latest release from the download page. macOS and Windows builds are signed; Linux is a tarball.
• Channel. The web app ships fresh on every release. The desktop app fetches its update manifest from Vercel Blob with ISR caching (the web app does not redeploy when desktop releases) — set the channel (stable / beta) in the desktop settings.
• Auto-update. On launch, the app checks the manifest, downloads the delta if newer, and prompts to restart. Manual download from the same release page always works as a fallback.

Troubleshooting

• Sprite shows as placeholder. The desktop wallet doesn't hold an asset-scope grant — open the Soul detail in the web app and authorize.
• Sprite went blank after I bought the Soul. Ownership rotated and the old auto-grant was invalidated. The desktop app should detect this and prompt for a fresh grant; if not, retry from the persona settings.
• Open-in-desktop button did nothing. The protocol handler isn't registered. Reinstall the desktop app or copy the Soul ID manually into the desktop pairing screen.
• Decryption errors. Open View → Toggle Developer Tools → Main Process for the raw IPC error code. The four error classes are NOT_GRANTED, WALRUS_FETCH_FAILED, SEAL_DENIED, TIMEOUT.