@kalo/sdk API Reference
Complete TypeScript API reference for KaloClient, kalo.fetch(), kaloGate(), filterPiiHeaders(), and cryptographic helpers.
Installation
npm install @kalo/sdk @solana/web3.jsPackage entry point: @kalo/sdk (v0.1.0, ESM, TypeScript declarations included, peer/runtime dependency @solana/web3.js 1.99.0).
KaloClient
Agent-side HTTP 402 client that handles pre-execution PII filtering, challenge negotiation, SealedEscrow locking, Ed25519 receipt verification, and viewing-key decryption.
Constructor
new KaloClient(config: KaloClientConfig)| Option | Type | Required | Description |
|---|---|---|---|
apiUrl | string | Yes | Base URL of the Kalo API server (used for /v1/settlements/lock/build) |
agentPubkey | string | Yes | Base58 Ed25519 public key of the delegated agent |
ringAddress | string | Yes | Base58 address of the funding PrivacyRing PDA |
defaultMandate | string | No | Default AuthorityMandate PDA address used when options.mandate is omitted |
defaultViewingKey | string | No | Default viewing key sent via X-Kalo-Viewing-Key and used to decrypt encryptedResponse |
fetch | typeof globalThis.fetch | No | Custom Fetch implementation (defaults to globalThis.fetch) |
kalo.fetch<T>(url, options?)
Executes a confidential HTTP 402 request and returns Promise<KaloFetchResponse<T>>.
KaloFetchOptions extends standard RequestInit:
| Option | Type | Required | Description |
|---|---|---|---|
mandate | string | No | Overrides defaultMandate for this call (throws if neither is set) |
viewingKey | string | No | Overrides defaultViewingKey for this call |
maxPriceBaseUnits | bigint | No | Client-side ceiling; throws before locking if BigInt(challenge.amountBaseUnits) > maxPriceBaseUnits |
method, headers, body | RequestInit | No | Standard fetch parameters; method defaults to 'POST' |
KaloFetchResponse<T>:
| Property | Type | Description | |
|---|---|---|---|
status | number | HTTP status code from provider | |
ok | boolean | true on successful execution | |
escrowAddress | string | Derived SealedEscrow PDA address ('' if provider did not return 402) | |
requestHash | string | 0x SHA-256 request digest | |
outputHash | string | 0x SHA-256 response digest | |
teeSignature | string | 0x 64-byte Ed25519 signature | |
enclavePubkey | string | Base58 enclave signing public key | |
receiptVerified | boolean | Result of local verifyTeeReceipt() check | |
piiStrippedHeaders | string[] | Header keys removed by filterPiiHeaders() | |
piiFilterLatencyMs | number | Filter execution duration in milliseconds | |
encryptedBody | `string \ | null` | AES-256-GCM ciphertext if encryptedResponse was returned |
data | T | Parsed response payload (decrypted if viewingKey was supplied) |
kaloGate(config, handler)
Provider-side Fetch API middleware that gates any route behind HTTP 402 challenge negotiation and Confidential Compute receipt signing.
function kaloGate(config: KaloGateConfig, handler: GateHandler): (req: Request) => Promise<Response>KaloGateConfig
| Field | Type | Required | Description |
|---|---|---|---|
providerAddress | string | Yes | Base58 EnclaveRegistry PDA address |
enclavePubkey | string | Yes | Base58 enclave Ed25519 public key |
enclaveSecret32 | Uint8Array | Yes | 32-byte raw Ed25519 private seed held inside the TEE |
mint | string | Yes | Settlement token mint address |
symbol | string | No | Asset ticker (defaults to 'USDC') |
priceBaseUnits | string | Yes | Decimal string price per call in mint base units |
verifyEscrow | (escrowAddress: string, requestHash: string) => Promise<boolean> | No | Hook to verify SealedEscrow state on-chain before running handler |
GateHandler
type GateHandler = (bodyText: string, req: Request) => Promise<unknown> | unknownfilterPiiHeaders(headers, extraBlocked?)
Removes sensitive and identifying headers before outbound HTTP 402 dispatch.
function filterPiiHeaders(
headers: HeadersInit | Record<string, string> | undefined,
extraBlocked?: readonly string[],
): PiiFilterResultReturns { cleanHeaders: Record<string, string>, stripped: string[], latencyMs: number }. See HTTP 402 Wire Format for the full 16-header default blocklist.
Cryptographic helpers
All functions are exported directly from @kalo/sdk:
| Function | Signature | Description | ||||||
|---|---|---|---|---|---|---|---|---|
stripHex | (hex: string) => string | Removes a leading 0x or 0X prefix | ||||||
sha256Hex | `(input: string \ | Buffer \ | Uint8Array) => string` | Returns 0x-prefixed 32-byte SHA-256 hex digest | ||||
createCommitment | (amountBaseUnits: bigint, blindingHex?: string) => { commitment: string; blinding: string } | Computes `SHA256("kalo:spr:commitment:v1" \ | \ | amount \ | \ | blinding)` with a 32-byte blinding factor | ||
deriveNullifier | (commitmentHex: string, ownerPubkey: string) => string | Computes a fresh 32-byte 0x nullifier bound to commitment and owner | ||||||
encryptWithViewingKey | (plaintext: string, viewingKey: string) => string | Encrypts UTF-8 plaintext with AES-256-GCM (`iv \ | \ | tag \ | \ | ciphertext) keyed by SHA256("kalo:vk:v1:" \ | \ | viewingKey)` |
decryptWithViewingKey | `(ciphertextHex: string, viewingKey: string) => string \ | null` | Decrypts AES-256-GCM ciphertext; returns null if key is wrong or payload is tampered | |||||
buildReceiptDigest | (escrowAddress: string, requestHashHex: string, outputHashHex: string) => Buffer | Computes the 32-byte digest `SHA256(escrow_pda_bytes \ | \ | req_bytes \ | \ | out_bytes)` | ||
signReceiptEd25519 | (digest: Buffer, secret32: Uint8Array) => string | Signs a 32-byte digest with a 32-byte Ed25519 seed, returning 0x-prefixed 64-byte hex | ||||||
verifyTeeReceipt | (digest: Buffer, signatureHex: string, enclavePubkey: string) => boolean | Verifies a 64-byte Ed25519 receipt signature against a Base58 Solana public key |