SDK

recover

How geode.recover finds and decrypts a vault's manifest and rebuilds its notes from the wallet alone, what it returns, and the errors it raises.

TypeScript
recover(): Promise<RecoveryResult>

recover rebuilds a vault from the wallet: it locates and decrypts the latest manifest and rebuilds the holder's unspent notes from the encrypted memos in the pool's tree. The first vault call of any method does the same work once; recover does it again on demand, for example to pick up files stored from another device.

What it does

  1. Derive the keys

    On the client's first use, the wallet signs the key message. The signature gives the spending key, the view key and the locator. See Keys.

  2. Locate the manifest and read the tree

    GET /manifest?locator=... and GET /tree, at the same time. The relayer returns the Irys id of the latest manifest stored under the locator, or null.

  3. Decrypt the manifest

    With an id, the client fetches the ciphertext from the gateway, decrypts it with the view key and checks it: version must be 1 and every entry must have a valid id, receipt, bucket, term, key, size and time. The entries replace the client's list, and files this client stored that the manifest lacks are merged back in. Without an id, the list holds only those files.

  4. Rebuild the notes

    The tree's leaves must hash to its root. Every memo that decrypts under the view key and matches its commitment, and whose nullifier is unspent, becomes a note. See Notes and the pool.

The client counts as unlocked afterwards, so later calls read from memory.

Return value

RecoveryResult
found
boolean
Whether a manifest is stored under the vault's locator.
files
number
How many file entries the client now lists: the manifest's, plus files this client stored that it lacks; 0 for a new vault.
notes
number
How many unspent notes were rebuilt.
lamports
string
Their sum in lamports, as a decimal string.

What it costs

Nothing. recover reads; it sends no transaction.

Errors

CodeRaised when
WALLET_REJECTEDThe client has no wallet, or the wallet declines the key message or returns a signature that is not 64 bytes
WRONG_KEYThe manifest does not decrypt under the view key
VALIDATION_ERRORThe manifest has an unsupported format or an invalid entry, or a memo that decrypts has invalid fields
NOT_FOUNDThe gateway answers 404 for the manifest id
IRYS_UNAVAILABLEThe gateway answers any other non-success status
PAYLOAD_TOO_LARGEThe manifest ciphertext is larger than 64 MiB
CONFIGURATION_REQUIREDNeither the options nor /config give a gateway URL
UNKNOWN_ROOTThe tree leaves the relayer returned do not hash to its root
RELAYER_FAILEDA relayer reply does not match the contract
UPSTREAM_UNAVAILABLEA network failure or any other unrecognised error

Codes from /manifest, /tree and /config pass through as listed at /docs/api#errors.

Sample

TypeScript
import { createGeode } from '@geode/sdk'

const geode = createGeode({ wallet, relayerUrl: 'https://api.geode.directory' })
const { found, files, notes, lamports } = await geode.recover()
if (!found) console.log('No manifest is stored for this vault yet.')