Types and Errors

This reference covers commonly used types from @engram-sdk/core.

Core Types

interface StorageReceipt {
  cid: string
  dealId: string
  ttlTimestamp: Date
  spendUSDFC: number
  policy: ResolvedPolicy
  identityAddress?: string
  attestationTx?: string
}

interface StoreOptions {
  priority?: Priority
  replication?: number
  ttlDays?: number
  encrypt?: boolean
  /**
   * Internal option to skip index flush.
   * Use only for ephemeral records that should not enter durable memory index.
   */
  _skipFlush?: boolean
}

interface RetrieveOptions {
  decrypt?: boolean
}

interface RenewOptions {
  force?: boolean
}

type Priority = 'critical' | 'standard' | 'temporary' | 'ephemeral'

interface ResolvedPolicy {
  replication: number
  ttlDays: number
  encrypt: boolean
}

interface EngramConfig {
  storageProvider: StorageProvider
  operatorPrivateKey?: string
  vincentApiKey?: string
  network?: 'calibration' | 'mainnet'
  baseRpcUrl?: string
  filecoinRpcUrl?: string
  vincentApiBaseUrl?: string
  identityRegistryAddress?: string
  reputationRegistryAddress?: string
  indexRegistryAddress?: string
  agentName?: string
  agentMcpPort?: number
  verbose?: boolean
  wallet?: WalletStub
  maxSpendUSDFC?: number
  renewThresholdDays?: number
  safetyMarginPct?: number
  logPath?: string
  autoFund?: boolean
  attestOnChain?: boolean
  identityPath?: string
}

interface StorageProvider {
  readonly name: string
  store(data: unknown, policy: ResolvedPolicy): Promise<{ cid: string; dealId: string }>
  retrieve(cid: string): Promise<unknown>
  renew(cid: string, policy: ResolvedPolicy): Promise<{ dealId: string }>
}

interface WalletStub {
  checkBalance(required: number): Promise<void>
  getRunningSpend(): number
  encryptPayload?(data: unknown): Promise<{ ciphertext: string; accessCondition: unknown }>
  decryptPayload?(ciphertext: string, accessCondition: unknown): Promise<unknown>
  requestFunding?(requiredUSDFC: number): Promise<void>
  getWalletAddress?(): string
  signRenewal?(payload: string): Promise<string>
}

Policy Function

resolvePolicy(context?: {
  priority?: Priority
  replication?: number
  ttlDays?: number
  encrypt?: boolean
}): ResolvedPolicy

The function is pure and deterministic. Explicit fields override priority defaults.

Common Errors

The SDK exposes typed errors from @engram-sdk/core/errors.

Important classes to handle explicitly:

• EngramError (base class; has code)
• BudgetExceededError
• InsufficientBalanceError
• StalePriceDataError
• StorageDealFailedError
• DecryptionFailedError
• PruneError
• DelegationVerificationError
• DelegationExpiredError
• RegistrationFailedError
• RegistrationFundingError
• FundingTimeoutError

Error Payload Fields

Error	Key fields
BudgetExceededError	attempted, runningTotal, maxSpend
InsufficientBalanceError	required, available
StorageDealFailedError	provider, reason
DecryptionFailedError	cid, reason
PruneError	cid, reason
DelegationVerificationError	tokenCid, reason
DelegationExpiredError	tokenCid, expiredAt
FundingTimeoutError	walletAddress, requiredUSDFC, timeoutMs
RegistrationFundingError	pkpAddress, requiredEth

Suggested Handling Pattern

try {
  await sdk.store(payload, { priority: 'critical', encrypt: true })
} catch (error) {
  if (error instanceof BudgetExceededError) {
    // reject + alert with attempted/runningTotal/maxSpend
  } else if (error instanceof InsufficientBalanceError) {
    // trigger funding path or alert
  } else if (error instanceof StorageDealFailedError) {
    // provider outage retry/failover path
  } else {
    // fallback logging / incident routing
  }
}