SDK API

This page documents the primary runtime surface exported from engramjs.

EngramSDK

class EngramSDK {
  constructor(config: EngramConfig)

  store(data: unknown, options?: StoreOptions): Promise<StorageReceipt>
  retrieve(cid: string, options?: RetrieveOptions): Promise<unknown>
  renew(cid: string, options?: RenewOptions): Promise<RenewResult>
  prune(cid: string): Promise<PruneResult>

  get runningSpendUSDFC(): number
  get activeCids(): string[]
  get storageProviderName(): string
  get network(): 'calibration' | 'mainnet'
  get isAttestOnChain(): boolean
  get maxSpendUSDFC(): number
}

Constructor

new EngramSDK(config: EngramConfig)

EngramSDK initializes:

• configuration context for internal packages
• structured logging pipeline
• running spend tracking
• active CID index for lifecycle operations

store(data, options?)

store(data: unknown, options?: StoreOptions): Promise<StorageReceipt>

store resolves policy, validates budget, optionally encrypts, writes through provider, and returns a StorageReceipt.

Parameters

• data: any JSON-serializable payload
• options.priority: critical | standard | temporary | ephemeral
• options.replication: explicit replication override
• options.ttlDays: explicit retention override
• options.encrypt: explicit encryption override
• options._skipFlush: skip index flush (use only for ephemeral internals like delegation token storage)

Example

const receipt = await sdk.store(
  { objective: 'rotate keys', urgency: 'high' },
  { priority: 'critical', encrypt: true }
)

Returns

• cid: immutable content identifier
• dealId: provider-specific deal marker
• ttlTimestamp: expiration timestamp
• spendUSDFC: estimated spend charged to running total
• policy: resolved policy used for operation
• identityAddress?: optional identity value
• attestationTx?: optional ERC-8004 transaction hash

retrieve(cid, options?)

retrieve(cid: string, options?: RetrieveOptions): Promise<unknown>

Fetches payload by CID and decrypts when encrypted metadata is present.

Parameters

• cid: target content identifier
• options.decrypt: optional decrypt control for specialized usage

Example

const payload = await sdk.retrieve(receipt.cid)

renew(cid, options?)

renew(cid: string, options?: RenewOptions): Promise<RenewResult>

Renews when a CID is inside renewThresholdDays, or always when force: true.

Parameters

• cid: target content identifier
• options.force: bypass threshold check

Example

const renewResult = await sdk.renew(receipt.cid)
if (renewResult.renewed) {
  console.log('Renewed')
}

RenewResult

interface RenewResult {
  cid: string
  dealId: string
  renewed: boolean
  daysUntilExpiry: number
}

prune(cid)

prune(cid: string): Promise<PruneResult>

Removes CID from active index tracking (does not delete immutable provider content).

Example

await sdk.prune(receipt.cid)

PruneResult

interface PruneResult {
  cid: string
  pruned: boolean
}

SDK State Getters

runningSpendUSDFC

In-process cumulative spend value used by budget guard.

activeCids

Current active memory index CIDs.

storageProviderName

Provider identifier currently backing storage operations.

network

Resolved network (calibration or mainnet).

isAttestOnChain

Whether attestation writes are enabled in current config.

maxSpendUSDFC

Configured hard budget cap.

Delegation Functions

delegate(
  sdk: EngramSDK,
  cid: string,
  recipientDID: string,
  options?: DelegateOptions
): Promise<{ tokenCid: string; token: CapabilityToken }>

verifyDelegation(
  sdk: EngramSDK,
  tokenCid: string,
  callerDID: string
): Promise<CapabilityToken>

Delegation Token Shape

interface CapabilityToken {
  cid: string
  issuerDID: string
  recipientDID: string
  scope: 'agent/read'
  issuedAt: string
  expiresAt: string
  signature?: string
}

Identity Functions

Identity utilities are exported from engramjs via @engram-sdk/identity:

• registration utilities
• attestation helpers
• restore utilities
• identity validation helpers

See Types and Errors for referenced interfaces and failure classes.