Integrate Elydora.
Step by step.

// The EAR structure returned from submitOperation()
{
  receipt_version: "1.0",
  receipt_id: "019462a0-7e8b-7c3d-a1b2-3c4d5e6f7890",
  operation_id: "019462a0-7e8a-7b2c-9a8b-7c6d5e4f3210",
  org_id: "org_acme",
  agent_id: "agent_underwriter",
  server_received_at: 1740835800000,
  seq_no: 42,
  chain_hash: "base64url-encoded-sha256-hash",
  queue_message_id: "msg_01HQ4R5S6T7U8V9W0X1Y2Z3A",
  receipt_hash: "base64url-encoded-sha256-hash",
  elydora_kid: "elydora-server-key-v1",
  elydora_signature: "base64url-encoded-ed25519-signature"
}

Parsing and storing receipts

The SDK returns the receipt as a typed object, so parsing is handled automatically. Your responsibility is to persist the receipt in durable storage. You should store receipts alongside the original operation data in your database so you can reconstruct the complete audit trail at any time. Consider storing receipts in an append-only table or immutable storage to prevent accidental modification.

// Store the receipt alongside the operation
const { receipt } = await client.submitOperation(record);

// Persist both the EOR and EAR
await db.operations.insert({
  operation_id: record.operation_id,
  eor: record,          // The signed operation record
  ear: receipt,          // The platform attestation receipt
  created_at: new Date(),
});

// The SDK automatically updates the local chain hash
// No manual chain hash management needed

Verifying receipt authenticity

Every receipt is signed by the Elydora platform using its own Ed25519 key. You can verify the platform signature against Elydora's public JWKS, published at /.well-known/elydora/jwks.json. This ensures the receipt was genuinely issued by Elydora and has not been tampered with. The SDK's verifyReceipt() method performs this check automatically, fetching and caching the JWKS as needed.

// Verify a receipt's authenticity
const isValid = await client.verifyReceipt(receipt);
// Returns true if the platform signature is valid

// For manual verification:
// 1. Fetch JWKS from https://api.elydora.com/.well-known/elydora/jwks.json
// 2. Find the key matching receipt.elydora_kid
// 3. Verify receipt.elydora_signature against the receipt body

Error handling in code

Use the ElydoraError class to catch and handle specific error codes. The code property provides the machine-readable error type, while message provides a human-readable explanation. The requestId is essential for debugging — include it when contacting Elydora support.

import { ElydoraError } from '@elydora/sdk';

try {
  const { receipt } = await client.submitOperation(record);
  console.log('Submitted:', receipt.receipt_id);
} catch (err) {
  if (err instanceof ElydoraError) {
    console.error(`[${err.code}] ${err.message}`);
    console.error('Request ID:', err.requestId);

    switch (err.code) {
      case 'PREV_HASH_MISMATCH':
        // Local chain state is out of sync.
        // Fetch latest chain hash and rebuild the operation.
        const state = await client.getChainState();
        const retryRecord = client.createOperation({
          ...originalParams,
        });
        await client.submitOperation(retryRecord);
        break;

      case 'TTL_EXPIRED':
        // Operation too old — regenerate with fresh timestamp.
        const freshRecord = client.createOperation({
          ...originalParams,
        });
        await client.submitOperation(freshRecord);
        break;

      case 'AGENT_FROZEN':
        // Agent is frozen — alert the administrator.
        await alertAdmin('Agent frozen', err.details);
        break;

      case 'KEY_REVOKED':
        // Signing key revoked — cannot retry with same key.
        await alertAdmin('Key revoked', err.details);
        break;

      case 'RATE_LIMITED':
        // Back off and retry after the indicated delay.
        const retryAfter = err.details?.retryAfterMs ?? 1000;
        await sleep(retryAfter);
        await client.submitOperation(record);
        break;

      default:
        throw err; // Unhandled error — propagate
    }
  } else {
    throw err; // Not an Elydora error
  }
}

// Freeze an agent (reversible)
await client.freezeAgent(
  'agent_underwriter',
  'Suspicious activity detected — pending investigation'
);

// Unfreeze an agent (restore normal operation)
await client.unfreezeAgent(
  'agent_underwriter',
  'Investigation complete — no issues found'
);

// Revoke a specific key (permanent — cannot be undone)
await client.revokeKey(
  'agent_underwriter',
  'agent_underwriter-key-v1',
  'Key compromised — rotating to new key pair'
);

// After revoking, register a new key for the agent
const { privateKey, publicKey } = generateKeyPair();
await client.registerKey('agent_underwriter', {
  kid: 'agent_underwriter-key-v2',
  public_key: publicKey,
  algorithm: 'ed25519',
});