@provenonce/sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -26,6 +26,59 @@
  *
  * ═══════════════════════════════════════════════════════════
  */
+/** SIGIL identity class — determines tier pricing and heartbeat volume caps */
+type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';
+/**
+ * Ed25519-signed lineage proof — portable, offline-verifiable credential.
+ * Also known as the agent's "passport" — a cryptographic proof of identity
+ * that can be verified offline without any API call or SOL cost.
+ */
+interface LineageProof {
+    agent_hash: string;
+    agent_public_key: string | null;
+    identity_class: IdentityClass;
+    registered_at_beat: number;
+    sigil_issued_at_beat: number | null;
+    last_heartbeat_beat: number;
+    lineage_chain_hash: string;
+    issued_at: number;
+    valid_until: number;
+    provenonce_signature: string;
+}
+/** Passport = LineageProof. The agent's portable, offline-verifiable credential. */
+type Passport = LineageProof;
+/** Result from purchasing a SIGIL (Structured Identity Governance and Intelligent Lookup) */
+interface SigilResult {
+    ok: boolean;
+    sigil?: {
+        identity_class: IdentityClass;
+        issued_at_beat: number;
+        birth_tx: string | null;
+        explorer_url: string | null;
+    };
+    lineage_proof?: LineageProof;
+    fee?: {
+        amount_sol: number;
+        amount_lamports: number;
+        payment_tx: string | null;
+    };
+    error?: string;
+}
+/** Result from a paid heartbeat */
+interface HeartbeatResult {
+    ok: boolean;
+    lineage_proof?: LineageProof;
+    heartbeat_count_epoch?: number;
+    billing_epoch?: number;
+    current_beat?: number;
+    fee?: {
+        amount_sol: number;
+        amount_lamports: number;
+        tier: number;
+        payment_tx: string | null;
+    };
+    error?: string;
+}
 interface Beat {
     index: number;
     hash: string;
@@ -97,8 +150,10 @@ interface RegistrationResult {
     depth: number;
     name: string;
     metadata?: Record<string, unknown> | null;
-    signature: string;
-    explorer_url?: string;
+    /** @deprecated No Solana write at registration (D-65). Will be null. */
+    signature?: string | null;
+    /** @deprecated No Solana write at registration (D-65). Will be null. */
+    explorer_url?: string | null;
     /** Wallet chain: 'solana', 'ethereum', or null (no wallet) */
     wallet_chain?: string | null;
     beat?: {
@@ -108,6 +163,11 @@ interface RegistrationResult {
     };
     /** Wallet info — only present for root agents with wallets */
     wallet?: WalletInfo;
+    /** Next steps after registration */
+    _next_steps?: {
+        sigil?: string;
+        heartbeat?: string;
+    };
 }
 /**
  * Register a new agent on the Provenonce registry.
@@ -179,14 +239,18 @@ interface BeatAgentConfig {
     apiKey: string;
     /** Provenonce registry URL */
     registryUrl: string;
-    /** Beats to compute per pulse (default: 10) */
+    /** @deprecated Use heartbeatIntervalSec. Beats to compute per pulse (default: 10) */
     beatsPerPulse?: number;
-    /** Seconds between automatic check-ins (default: 300 = 5min) */
+    /** @deprecated Use heartbeatIntervalSec. Seconds between automatic check-ins (default: 300 = 5min) */
     checkinIntervalSec?: number;
-    /** Callback when heartbeat ticks */
+    /** Seconds between automatic heartbeats (default: 300 = 5min). Replaces checkinIntervalSec. */
+    heartbeatIntervalSec?: number;
+    /** @deprecated VDF pulse callback. No longer used in Phase 2. */
     onPulse?: (beats: Beat[], totalBeats: number) => void;
-    /** Callback when check-in completes */
+    /** @deprecated Use onHeartbeat. Callback when check-in completes. */
     onCheckin?: (result: CheckinResult) => void;
+    /** Callback when heartbeat completes (Phase 2) */
+    onHeartbeat?: (result: HeartbeatResult) => void;
     /** Callback on error */
     onError?: (error: Error, context: string) => void;
     /** Callback when status changes */
@@ -218,18 +282,17 @@ declare class BeatAgent {
         error?: string;
     }>;
     /**
+     * @deprecated Phase 2: VDF computation retired (D-68). Payment is the liveness mechanism.
+     * Use heartbeat() instead. This method will be removed in the next major version.
+     *
      * Compute N beats locally (VDF hash chain).
-     * This is the "heartbeat" — proof that the agent has lived
-     * through a specific window of computational time.
      */
     pulse(count?: number): Beat[];
     /** Internal beat computation — no status check. Used by both pulse() and resync(). */
     private computeBeats;
     /**
-     * Submit a Beat proof to the registry.
-     *
-     * "To remain on the Whitelist, an agent must periodically
-     *  submit a proof of its Local Beats to the Registry."
+     * @deprecated Phase 2: VDF check-in retired (D-68). Use heartbeat() instead.
+     * This method will be removed in the next major version.
      */
     checkin(): Promise<{
         ok: boolean;
@@ -238,21 +301,19 @@ declare class BeatAgent {
     }>;
     /**
      * Start the autonomous heartbeat loop.
-     * Computes beats continuously and checks in periodically.
-     * This is "keeping the agent alive" in Beat time.
+     * Phase 2: Sends paid heartbeats at regular intervals.
+     *
+     * @param paymentTxFn - Optional function that returns a payment tx for each heartbeat.
+     *                      If not provided, uses 'devnet-skip' (devnet only).
      */
-    startHeartbeat(): void;
+    startHeartbeat(paymentTxFn?: () => Promise<string> | string): void;
     /**
-     * Stop the heartbeat. Agent's time "freezes."
-     * Must call resync() when waking up.
+     * Stop the heartbeat loop.
      */
     stopHeartbeat(): void;
     /**
-     * Re-sync after being offline/frozen.
-     *
-     * "When an agent powers down, its time 'freezes.' Upon waking,
-     *  it must perform a Re-Sync Challenge with the Registry to
-     *  fill the 'Temporal Gap' and re-establish its provenance."
+     * @deprecated Phase 2: Resync retired (D-67). Dormancy resume is free — just call heartbeat().
+     * This method will be removed in the next major version.
      */
     resync(): Promise<{
         ok: boolean;
@@ -264,6 +325,56 @@ declare class BeatAgent {
      * Requires sufficient accumulated beats (Temporal Gestation).
      */
     requestSpawn(childName?: string, childHash?: string): Promise<SpawnResult>;
+    /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
+    private cachedProof;
+    /**
+     * Purchase a SIGIL (cryptographic identity) for this agent.
+     * SIGILs gate heartbeating, lineage proofs, and offline verification.
+     * One-time purchase — cannot be re-purchased.
+     *
+     * @param identityClass - 'narrow_task' (0.05 SOL), 'autonomous' (0.15 SOL), or 'orchestrator' (0.35 SOL)
+     * @param paymentTx - Solana transaction signature proving payment. Use 'devnet-skip' on devnet.
+     */
+    purchaseSigil(identityClass: IdentityClass, paymentTx: string): Promise<SigilResult>;
+    /**
+     * Send a paid heartbeat to the registry.
+     * Requires a SIGIL. Returns a signed lineage proof.
+     * This is the Phase 2 replacement for pulse() + checkin().
+     *
+     * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+     * @param globalAnchor - Optional: the global anchor index to reference.
+     */
+    heartbeat(paymentTx?: string, globalAnchor?: number): Promise<HeartbeatResult>;
+    /**
+     * Reissue a lineage proof. "Reprint, not a renewal."
+     * Does NOT create a new lineage event.
+     *
+     * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+     */
+    reissueProof(paymentTx?: string): Promise<{
+        ok: boolean;
+        lineage_proof?: LineageProof;
+        error?: string;
+    }>;
+    /**
+     * Get the latest cached lineage proof (no network call).
+     * Returns null if no proof has been obtained yet.
+     */
+    getLatestProof(): LineageProof | null;
+    /**
+     * Get the agent's passport (alias for getLatestProof).
+     * The passport is the agent's portable, offline-verifiable credential.
+     * Returns null if no passport has been issued yet (requires SIGIL + heartbeat).
+     */
+    getPassport(): Passport | null;
+    /**
+     * Verify a lineage proof locally using the authority public key.
+     * Offline verification — no API call, no SOL cost.
+     *
+     * @param proof - The LineageProof to verify
+     * @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
+     */
+    static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string): boolean;
     /**
      * Get this agent's full beat status from the registry.
      */
@@ -295,4 +406,84 @@ declare function computeBeatsLite(startHash: string, startIndex: number, count:
     elapsed: number;
 };
 
-export { type AgentStatus, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, type RegistrationResult, type SpawnResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
+/**
+ * Provenonce SDK Error Classes
+ *
+ * Typed error hierarchy for programmatic error handling.
+ * All errors extend ProvenonceError for catch-all, or catch specific
+ * subclasses for fine-grained control:
+ *
+ *   try {
+ *     await agent.checkin();
+ *   } catch (err) {
+ *     if (err instanceof RateLimitError) {
+ *       await sleep(err.retryAfterMs);
+ *     } else if (err instanceof FrozenError) {
+ *       await agent.resync();
+ *     } else if (err instanceof AuthError) {
+ *       console.error('Bad API key');
+ *     }
+ *   }
+ */
+/** Error codes for programmatic switching */
+declare enum ErrorCode {
+    VALIDATION = "VALIDATION",
+    AUTH_INVALID = "AUTH_INVALID",
+    AUTH_MISSING = "AUTH_MISSING",
+    RATE_LIMITED = "RATE_LIMITED",
+    AGENT_FROZEN = "AGENT_FROZEN",
+    AGENT_NOT_INITIALIZED = "AGENT_NOT_INITIALIZED",
+    AGENT_WRONG_STATE = "AGENT_WRONG_STATE",
+    NOT_FOUND = "NOT_FOUND",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    SERVER_ERROR = "SERVER_ERROR"
+}
+/** Base error class for all Provenonce SDK errors */
+declare class ProvenonceError extends Error {
+    /** Machine-readable error code */
+    readonly code: ErrorCode;
+    /** HTTP status code (if from an API response) */
+    readonly statusCode?: number;
+    /** Additional context */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: ErrorCode, statusCode?: number, details?: Record<string, unknown>);
+}
+/** Thrown when input validation fails (bad config, invalid args) */
+declare class ValidationError extends ProvenonceError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Thrown on 401/403 — bad or missing API key */
+declare class AuthError extends ProvenonceError {
+    constructor(message: string, code?: ErrorCode.AUTH_INVALID | ErrorCode.AUTH_MISSING, statusCode?: number);
+}
+/** Thrown on 429 — rate limit exceeded */
+declare class RateLimitError extends ProvenonceError {
+    /** Milliseconds until the rate limit resets (if provided by server) */
+    readonly retryAfterMs?: number;
+    constructor(message: string, statusCode?: number, retryAfterMs?: number);
+}
+/** Thrown when an agent is frozen and cannot perform the requested action */
+declare class FrozenError extends ProvenonceError {
+    constructor(message?: string);
+}
+/** Thrown when the agent is in the wrong state for the requested action */
+declare class StateError extends ProvenonceError {
+    /** The agent's current state */
+    readonly currentState: string;
+    constructor(message: string, currentState: string, code?: ErrorCode);
+}
+/** Thrown on 404 — agent or resource not found */
+declare class NotFoundError extends ProvenonceError {
+    constructor(message: string, statusCode?: number);
+}
+/** Thrown on network failures — non-JSON responses, fetch errors, timeouts */
+declare class NetworkError extends ProvenonceError {
+    constructor(message: string, code?: ErrorCode.NETWORK_ERROR | ErrorCode.TIMEOUT);
+}
+/** Thrown on 5xx — unexpected server errors */
+declare class ServerError extends ProvenonceError {
+    constructor(message: string, statusCode?: number);
+}
+
+export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilResult, type SpawnResult, StateError, ValidationError, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };