Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.story.foundation/llms.txt

Use this file to discover all available pages before exploring further.

​
Observer

The Observer sub-client is always available, even without a walletClient. It provides read-only access to CDR and DKG state. 
const observer = client.observer;
The Observer reads from two backends: CDR contract state (vaults, fees, maxEncryptedDataSize, operational threshold) over the EVM publicClient, and DKG state (active round, global public key, threshold, validators, attestations) over the Story-API REST endpoint configured by apiUrl.
Round-keyed DKG snapshots are cached for the lifetime of the Observer for rounds in the stable Active and Ended stages, with in-flight request deduplication. getActiveRound() always re-fetches, since the active round can transition at any time.

​
Methods

  • getVault
  • getAllocateFee
  • getWriteFee
  • getReadFee
  • getMaxEncryptedDataSize
  • getOperationalThreshold
  • getActiveRound
  • getGlobalPubKey
  • getParticipantCount
  • getThreshold
  • getThresholdAt
  • getRegisteredValidators
  • getValidatorAttestations

​
getVault

Fetch a vault’s on-chain data by UUID.
MethodType
getVault(uuid: number) => Promise<Vault>
Parameters:
  • uuid: The vault’s unique identifier (uint32)
Example
const vault = await client.observer.getVault(42);

console.log(vault.uuid); // 42
console.log(vault.updatable); // false
console.log(vault.writeConditionAddr); // "0x..."
console.log(vault.readConditionAddr); // "0x..."
console.log(vault.encryptedData); // "0x..." (hex-encoded TDH2 ciphertext)
Vault
interface Vault {
  uuid: number;
  updatable: boolean;
  writeConditionAddr: `0x${string}`;
  readConditionAddr: `0x${string}`;
  writeConditionData: `0x${string}`;
  readConditionData: `0x${string}`;
  encryptedData: `0x${string}`;
}

​
getAllocateFee

Returns the current fee (in wei) required to allocate a new vault.
MethodType
getAllocateFee() => Promise<bigint>
Example
const fee = await client.observer.getAllocateFee();
console.log(`Allocate fee: ${fee} wei`);

​
getWriteFee

Returns the current fee (in wei) required to write data to a vault.
MethodType
getWriteFee() => Promise<bigint>
Example
const fee = await client.observer.getWriteFee();
console.log(`Write fee: ${fee} wei`);

​
getReadFee

Returns the current fee (in wei) required to submit a read request.
MethodType
getReadFee() => Promise<bigint>
Example
const fee = await client.observer.getReadFee();
console.log(`Read fee: ${fee} wei`);

​
getMaxEncryptedDataSize

Returns the maximum encrypted payload size (in bytes) supported by the on-chain vault path. The CDR contract treats this as a constant, so it is cached for the lifetime of the Observer.
MethodType
getMaxEncryptedDataSize() => Promise<bigint>
Example
const maxSize = await client.observer.getMaxEncryptedDataSize();
console.log(`Max encrypted payload size: ${maxSize} bytes`);

​
getOperationalThreshold

Returns the DKG operational threshold as a basis-points constant read from the DKG contract (e.g., 667 = 66.7%).
MethodType
getOperationalThreshold() => Promise<bigint>
Example
const threshold = await client.observer.getOperationalThreshold();
console.log(`Threshold: ${Number(threshold) / 10}%`); // e.g. "66.7%"

​
getActiveRound

Returns the currently active DKG round number. Always hits the Story-API REST endpoint — the active round can transition at any time, so it is never served from cache.
MethodType
getActiveRound() => Promise<number>
Example
const round = await client.observer.getActiveRound();
console.log(`Active DKG round: ${round}`);

​
getGlobalPubKey

Returns the DKG global public key from the active round, used for TDH2 encryption. This is an Ed25519 point with a 2-byte curve-code prefix (0x043f), 34 bytes total, so it can be passed directly to the WASM TDH2 functions.
MethodType
getGlobalPubKey() => Promise<Uint8Array>
Example
const globalPubKey = await client.observer.getGlobalPubKey();
console.log(globalPubKey.length); // 34

​
getParticipantCount

Returns the number of validators selected to participate in the active DKG round.
MethodType
getParticipantCount() => Promise<number>
Example
const count = await client.observer.getParticipantCount();
console.log(`Participating validators: ${count}`);

​
getThreshold

Returns the absolute threshold for the currently active DKG round — the minimum number of partial decryptions needed to combine. If minThresholdRatio is set on the client, the effective value is max(network.threshold, ceil(participants * minThresholdRatio)).
MethodType
getThreshold() => Promise<number>
Example
const threshold = await client.observer.getThreshold();
console.log(`Need ${threshold} partials to decrypt`);
Use this for UI / status display. Do not use it to validate a specific partial-decryption bucket from collectPartials — a bucket carries its own round, which can differ from the active round during DKG rollover. Use getThresholdAt for that.

​
getThresholdAt

Returns the absolute threshold for a specific DKG round, computed against that round’s own participant total. Used internally by collectPartials so a DKG rollover mid-poll does not measure a bucket against the wrong round.
MethodType
getThresholdAt(round: number) => Promise<number>
Parameters:
  • round: The DKG round number to compute the threshold for
Example
const threshold = await client.observer.getThresholdAt(4);
console.log(`Round 4 threshold: ${threshold}`);

​
getRegisteredValidators

Returns a map of validator address → commPubKey bytes for the given DKG round (defaults to the active round). Only includes validators with Finalized status. The commPubKey is the secp256k1 public key the validator’s TEE uses to sign partial decryption responses.
MethodType
getRegisteredValidators(params?: { round?: number }) => Promise<Map<string, Uint8Array>>
Parameters:
  • params.round (optional): DKG round number. Defaults to the active round.
Example
const validators = await client.observer.getRegisteredValidators();
for (const [address, commPubKey] of validators) {
  console.log(address, commPubKey.length);
}

​
getValidatorAttestations

Returns a map of validator address → enclaveReport (raw SGX quote bytes) for the given DKG round (defaults to the active round). Only includes validators with Finalized status. Shares a per-round cache with getRegisteredValidators.
MethodType
getValidatorAttestations(params?: { round?: number }) => Promise<Map<string, Uint8Array>>
Parameters:
  • params.round (optional): DKG round number. Defaults to the active round.
Example
const attestations = await client.observer.getValidatorAttestations();
for (const [address, enclaveReport] of attestations) {
  console.log(address, enclaveReport.length);
}
Use with verifyAttestation() to verify each validator’s TEE enclave before trusting their partial decryptions.