Skip to main content

​
What’s in the Backup

The contains the user’s plus a set of files needed to fully restore World App on a new device. Today this includes the user’s s (Orb, Document, Face) and the credential vault. Each file is tagged with a designator identifying its kind. The exact list of designators is owned by Bedrock and evolves as new credentials are added. The authoritative enumeration lives in BackupFileDesignator; refer to it directly rather than duplicating the list here. The backup format itself is versioned (BackupFormat). The current version is V0: a tar+gzip archive of CBOR-encoded files with per-file BLAKE3 checksums.

​
The Manifest

Because the backup is end-to-end encrypted, the Backup Service cannot enforce content-level rules. If Client M observes that the user just verified their passport (and now holds a new PCP), the Backup Service has no way to require that a sync from Client N — which doesn’t have that file — must include it. The manifest mechanism described below is what prevents accidental data loss in that case.
Every backup ships with a manifest: a versioned, hashed ledger of every file in the . The manifest entries record each file’s path, designator, and content checksum. The hash of the manifest is the backup’s state. Both the client and the Backup Service track this hash. The Backup Service uses it to enforce that every update transitions from the current state — preventing an out-of-date client from silently overwriting a newer backup with a stale one. The canonical encoding and BLAKE3 hashing are computed by Bedrock so they’re identical across iOS and Android. See BackupManifest for the implementation.

​
State Transitions

A successful update transitions the backup from state mtm_t (the current manifest hash) to mt+1m_{t+1} (the updated manifest hash). The rules:
  • Client. Bears responsibility for performing updates against the current state. Verifies it holds the latest manifest before making changes.
  • Backup Service. Maintains the current state hash. Validates each update is a transition from the recorded state. Cannot inspect encrypted contents.
If the client tries to sync from a stale state, the service rejects with manifest_hash_mismatch (HTTP 412). The client must re-authenticate a , download the latest , apply local changes on top, and retry. See Multiple Device Sync for why this happens in practice.

​
ManifestManager API

Clients interact with the manifest through Bedrock’s ManifestManager. It gates every operation on a fresh remote-hash check before mutating local state, so the client cannot accidentally produce an update from a stale base:
  • store_file(designator, path) — Add a file. Computes its checksum, appends to the manifest, packs and uploads.
  • list_files(designator) — List files for a designator.
  • replace_all_files_for_designator(designator, new_path) — Atomically replace every file under a designator with a new one.
  • remove_file(path) — Remove a file entry.
If the local manifest is missing or its hash differs from the remote, every method short-circuits with RemoteAheadStaleError. The client surfaces this as a prompt to re-authenticate and download the latest backup before retrying the change. See ManifestManager for signatures and behavior.

​
Pack & Upload

When building a new backup version (see BF-4: Sync):
  1. Validate the local manifest exists and matches the remote state.
  2. Build the from the files referenced in the manifest. Verify each file’s checksum.
  3. Encrypt with the ‘s keypair public key.
  4. POST /sync with the new , the current manifest hash, and the new manifest hash.
  5. Backup Service checks the current hash matches its recorded state, then atomically swaps the blob and the recorded hash.

​
Download & Unpack

When restoring or catching up (see BF-2 and BF-5):
  1. Decrypt the with the -unlocked .
  2. Replace the local manifest unconditionally with the manifest from the unpacked backup.
  3. Write each file to its declared path. On checksum mismatch the file is overwritten with the version from the backup and the mismatch is logged — the backup is the source of truth.

​
Startup Verification

On every app launch the client fetches the remote manifest hash. If it differs from the local hash, the user is prompted to re-authenticate a and download the remote backup. This handles the multi-device case where the user updated their backup from Device A and then opens World App on Device B.

​
Backend Safety Measures

  • Short-lived locks. The Backup Service holds a short-lived per-backup_id lock during create and sync to close the narrow race window between the hash check and the write. The authoritative consistency check remains the manifest hash comparison.
Last modified on June 7, 2026