SDK

open

How geode.open fetches and decrypts a stored file, with a shared key or from the vault, what it returns and the errors it raises.

TypeScript
open(id: string, key?: string): Promise<OpenResult>

open fetches a ciphertext by its Irys id and decrypts it on the device. With a key it opens any Geode file and never touches the wallet. Without a key it looks the key up in the vault's manifest.

  1. Seal
  2. Quote
  3. Prove
  4. Pay
  5. Store
  6. Open
Every file, from your device to Irys. Dashed: what the chain sees. Solid: what stays with you.

What it does

  1. Find the key

    With key, the client uses it as given. Without it, the client unlocks the vault on first use (the wallet signs the key message and the manifest is read, as in recover) and takes the key of the entry whose id matches. No matching entry raises NOT_FOUND.

  2. Fetch the ciphertext

    The id must be 43 base64url characters. The client reads /config once per client, even when gatewayUrl is set in the options, then fetches <gateway>/<id>, where the gateway is gatewayUrl from the options or else from /config. A ciphertext larger than 64 MiB, by its Content-Length or its bytes, raises PAYLOAD_TOO_LARGE.

  3. Unseal

    The client checks the GEODE001 header and that the length is a bucket, decrypts every chunk with XChaCha20-Poly1305 under the file key, and reads the name, media type and exact length from inside the ciphertext. A wrong or malformed key, or a changed byte, raises WRONG_KEY.

A client created without a wallet opens files with a key; it needs only relayerUrl.

Arguments

open(id, key)
idrequired
string
The Irys id of the ciphertext, 43 base64url characters, as in StoreResult.id.
key
string
The 32-byte file key as 43 base64url characters, the fragment of a share link. When omitted, the key comes from the vault's manifest.

Return value

OpenResult
bytes
Uint8Array<ArrayBuffer>
The file's plaintext, its exact original length. It is a valid BlobPart, so new Blob([bytes], { type }) makes a file of it.
name
string
The name sealed with the file.
type
string
The media type sealed with the file, empty when the file had none.

What it costs

Nothing. open reads a public ciphertext from the gateway and sends no transaction. Neither the key nor the plaintext enters a request.

Errors

CodeRaised when
WRONG_KEYThe key is not 43 base64url characters or does not decrypt the ciphertext
VALIDATION_ERRORThe id is not 43 base64url characters
NOT_FOUNDNo key is given and the vault has no entry with this id, or the gateway has no ciphertext with this id (it answers 404)
IRYS_UNAVAILABLEThe gateway answers any other non-success status
PAYLOAD_TOO_LARGEThe ciphertext is larger than 64 MiB
CONFIGURATION_REQUIREDNeither the options nor /config give a gateway URL
WALLET_REJECTEDNo key is given and the client has no wallet, or the wallet declines the key message
UNKNOWN_ROOT, RELAYER_FAILEDNo key is given and the vault cannot be unlocked: the tree does not hash to its root, or a relayer reply does not match the contract
UPSTREAM_UNAVAILABLEA network failure or any other unrecognised error

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

Samples

Open a share link, with no wallet:

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

const reader = createGeode({ relayerUrl: 'https://api.geode.directory' })

// A share link has the form /s/<id>#<key>.
const id = decodeURIComponent(location.pathname.slice('/s/'.length))
const key = location.hash.slice(1)
const { bytes, name, type } = await reader.open(id, key)
const opened = new File([bytes], name, { type })

Open a file from the vault and save it:

TypeScript
const { bytes, name, type } = await geode.open(id)
const url = URL.createObjectURL(new Blob([bytes], { type }))
const a = document.createElement('a')
a.href = url
a.download = name
a.click()
URL.revokeObjectURL(url)