@provenonce/sdk 0.8.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @provenonce/sdk
 
-Agent heartbeat client for sovereign time authentication on Solana.
+Cryptographic identity and accountability SDK for AI agents. Chain-agnostic (Solana + Ethereum).
 
 ## Install
 
@@ -15,7 +15,7 @@ Before using the SDK, register your agent to get an API key:
 ```typescript
 import { register } from '@provenonce/sdk';
 
-// Root registration (one-time)
+// No-wallet registration (default — identity only)
 const creds = await register('my-agent-v1', {
   registryUrl: 'https://provenonce.io',
   registrationSecret: process.env.REGISTRATION_SECRET, // required in production
@@ -25,6 +25,14 @@ console.log(creds.hash);    // unique agent identity
 console.log(creds.api_key); // use this for BeatAgent
 console.log(creds.secret);  // save — shown only once
 
+// Solana self-custody wallet (opt-in)
+const withWallet = await register('my-org', {
+  registryUrl: 'https://provenonce.io',
+  walletModel: 'self-custody',
+});
+// withWallet.wallet.address = Solana address
+// withWallet.wallet.secret_key = SAVE — cannot be recovered
+
 // Child registration (requires parent credentials)
 const child = await register('worker-1', {
   registryUrl: 'https://provenonce.io',
@@ -45,9 +53,23 @@ const agent = new BeatAgent({
 });
 
 await agent.init();           // Birth in Beat time
-agent.startHeartbeat();       // Compute + check in continuously
 
-// ... your agent does work ...
+// Purchase a SIGIL (cryptographic identity)
+const sigil = await agent.purchaseSigil({
+  identityClass: 'autonomous',
+  paymentTx: 'solana-tx-signature...',
+});
+
+// Start heartbeating (paid liveness proofs)
+agent.startHeartbeat();
+
+// Get your Passport (latest lineage proof)
+const passport = await agent.getPassport();
+console.log(passport?.identity_class);     // 'autonomous'
+console.log(passport?.provenonce_signature); // Ed25519 signed
+
+// Verify any proof offline — no API call needed
+const valid = BeatAgent.verifyProofLocally(passport, authorityPubKeyHex);
 
 agent.stopHeartbeat();
 ```
@@ -59,14 +81,16 @@ agent.stopHeartbeat();
 | Method | Description |
 |--------|-------------|
 | `init()` | Initialize the agent's Beat chain (birth in Logical Time) |
-| `pulse(count?)` | Compute N beats locally (VDF hash chain) |
-| `checkin()` | Submit beat proof to the registry |
-| `startHeartbeat()` | Start autonomous pulse + check-in loop |
-| `stopHeartbeat()` | Stop heartbeat (time freezes) |
-| `resync()` | Re-sync after being offline/frozen |
+| `purchaseSigil(opts)` | Purchase a SIGIL identity (required for heartbeating) |
+| `heartbeat(opts?)` | Submit a paid heartbeat and receive a signed lineage proof |
+| `startHeartbeat()` | Start autonomous heartbeat loop |
+| `stopHeartbeat()` | Stop heartbeat |
+| `getPassport()` | Get latest lineage proof (Passport) |
+| `reissueProof(paymentTx?)` | Reissue proof without extending lineage |
 | `requestSpawn(name?)` | Spawn a child agent (requires accumulated beats) |
 | `getStatus()` | Get full beat status from registry |
 | `getLocalState()` | Get local state (no network call) |
+| `static verifyProofLocally(proof, pubKey)` | Verify a lineage proof offline |
 
 ### `BeatAgentConfig`
 
@@ -74,24 +98,57 @@ agent.stopHeartbeat();
 |--------|---------|-------------|
 | `apiKey` | *required* | API key from registration (`pvn_...`) |
 | `registryUrl` | *required* | Provenonce registry URL |
-| `beatsPerPulse` | `10` | Beats to compute per pulse |
-| `checkinIntervalSec` | `300` | Seconds between automatic check-ins |
-| `onPulse` | — | Callback when heartbeat ticks |
-| `onCheckin` | — | Callback when check-in completes |
+| `heartbeatIntervalSec` | `300` | Seconds between automatic heartbeats |
+| `onHeartbeat` | — | Callback when heartbeat completes |
 | `onError` | — | Callback on error |
 | `onStatusChange` | — | Callback when status changes |
 | `verbose` | `false` | Enable console logging |
 
-### Standalone helpers
+### `register(name, options)`
+
+| Option | Description |
+|--------|-------------|
+| `registryUrl` | Registry URL (required) |
+| `registrationSecret` | Registration gate (mainnet) |
+| `walletModel` | `'self-custody'` or `'operator'` (opt-in wallet) |
+| `walletChain` | `'solana'` or `'ethereum'` |
+| `walletAddress` | Ethereum BYO address |
+| `walletSignFn` | Signing function for BYO wallets |
+| `parentHash` | Parent hash (child registration) |
+| `parentApiKey` | Parent's API key (child registration) |
+
+Returns `RegistrationResult` with `hash`, `api_key`, `secret`, `wallet?`.
+
+**Note:** Agent names should only contain `[a-zA-Z0-9_\-. ]`. Other characters are stripped by the server before signature verification.
+
+### Phase 2 Types
 
 ```typescript
-import { computeBeat, computeBeatsLite } from '@provenonce/sdk';
+import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';
 
-// Single beat
-const beat = computeBeat(prevHash, beatIndex, difficulty);
+// Passport = LineageProof (type alias)
+// Contains: agent_hash, agent_public_key, identity_class, lineage_chain_hash,
+//           provenonce_signature, issued_at, valid_until, etc.
 
-// N sequential beats (returns only the last)
-const { lastBeat, elapsed } = computeBeatsLite(startHash, startIndex, count, difficulty);
+// IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator'
+```
+
+### Error Handling
+
+```typescript
+import { ProvenonceError, AuthError, RateLimitError, FrozenError, ErrorCode } from '@provenonce/sdk';
+
+try {
+  await agent.heartbeat();
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    console.log(`Retry after ${err.retryAfterMs}ms`);
+  } else if (err instanceof FrozenError) {
+    console.log('Agent is frozen — heartbeat refused');
+  } else if (err instanceof AuthError) {
+    console.log('Invalid API key');
+  }
+}
 ```
 
 ## Framework Integration Examples
@@ -111,5 +168,5 @@ Python examples use the REST API directly — no Python SDK needed. See [`exampl
 
 - [Live prototype](https://provenonce.io)
 - [npm package](https://www.npmjs.com/package/@provenonce/sdk)
-- [API docs](https://provenonce.io/docs)
-- [GitHub](https://github.com/jarekpiot/provenonce)
+- [API docs](https://provenonce.dev)
+- [Whitepaper](https://provenonce.dev/concepts/architecture)

package/dist/index.d.mts

@@ -26,6 +26,132 @@
  *
  * ═══════════════════════════════════════════════════════════
  */
+/** SIGIL identity class — determines tier pricing and heartbeat volume caps */
+type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';
+/** SIGIL trust governance tier — orthogonal to identity_class (fee axis) */
+type SigilTier = 'sov' | 'org' | 'ind' | 'eph' | 'sbx';
+/** Substrate — what the agent runs on */
+type Substrate = 'frontier' | 'open' | 'local' | 'symbolic' | 'hybrid' | 'human';
+/** Substrate provider */
+type SubstrateProvider = 'anthropic' | 'openai' | 'google' | 'meta' | 'mistral' | 'xai' | 'cohere' | 'deepseek' | 'custom';
+/** Capability — what the agent primarily does */
+type Capability = 'analyst' | 'executor' | 'orchestrator' | 'guardian' | 'retriever' | 'renderer' | 'witness';
+/** Protocol — how to reach the agent */
+type SigilProtocol = 'http' | 'grpc' | 'websocket' | 'mcp' | 'a2a' | 'custom';
+/** Compliance regime */
+type ComplianceRegime = 'gdpr' | 'pdpa' | 'hipaa' | 'sox' | 'aisi' | 'none' | 'custom';
+/**
+ * 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;
+/** Options for purchasing a SIGIL with full namespace */
+interface SigilPurchaseOptions {
+    identity_class: IdentityClass;
+    principal: string;
+    tier: SigilTier;
+    name?: string;
+    payment_tx: string;
+    substrate?: Substrate;
+    substrate_provider?: SubstrateProvider;
+    substrate_model?: string;
+    capability?: Capability;
+    capability_scope?: string;
+    tools?: string[];
+    modality_input?: string[];
+    modality_output?: string[];
+    protocol?: SigilProtocol;
+    endpoint?: string;
+    compliance_regime?: ComplianceRegime;
+}
+/** Mutable SIGIL metadata fields for PATCH updates */
+interface SigilMutableFields {
+    substrate?: Substrate;
+    substrate_provider?: SubstrateProvider;
+    substrate_model?: string;
+    capability?: Capability;
+    capability_scope?: string;
+    generation_trigger?: string;
+    tools?: string[];
+    modality_input?: string[];
+    modality_output?: string[];
+    protocol?: SigilProtocol;
+    endpoint?: string;
+    compliance_regime?: ComplianceRegime;
+}
+/** Result from purchasing a SIGIL (Structured Identity Governance and Intelligent Lookup) */
+interface SigilResult {
+    ok: boolean;
+    sigil?: {
+        sigil: string;
+        sigil_name: string;
+        principal: string;
+        tier: SigilTier;
+        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 updating mutable SIGIL metadata */
+interface MetadataUpdateResult {
+    ok: boolean;
+    sigil?: string;
+    generation?: number;
+    updated_fields?: string[];
+    error?: string;
+}
+/** Result from offline lineage proof verification */
+interface VerificationResult {
+    /** Overall validity: signature is valid AND not expired */
+    valid: boolean;
+    /** Ed25519 signature verification passed */
+    signatureValid: boolean;
+    /** Proof has passed its valid_until timestamp */
+    expired: boolean;
+    /** The beat index of the agent's last heartbeat */
+    lastHeartbeatBeat: number;
+    /** Beats elapsed since last heartbeat (null if currentBeat not provided) */
+    beatsSinceHeartbeat: number | null;
+    /** Human-readable warning if proof is expired or stale */
+    warning?: 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 +223,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 +236,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 +312,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 +355,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 +374,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 +398,70 @@ 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 options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
+     *
+     * Legacy signature (deprecated):
+     * @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
+     * @param paymentTx - Solana transaction signature or 'devnet-skip'
+     */
+    purchaseSigil(optionsOrClass: SigilPurchaseOptions | IdentityClass, paymentTx?: string): Promise<SigilResult>;
+    /**
+     * Update mutable SIGIL metadata fields.
+     * Requires a SIGIL. Cannot modify immutable fields.
+     *
+     * @param fields - Subset of mutable SIGIL fields to update
+     */
+    updateMetadata(fields: Partial<SigilMutableFields>): Promise<MetadataUpdateResult>;
+    /**
+     * 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.
+     *
+     * Returns a VerificationResult object. The object is truthy when valid,
+     * so `if (BeatAgent.verifyProofLocally(proof, key))` still works.
+     *
+     * @param proof - The LineageProof to verify
+     * @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
+     * @param currentBeat - Optional current global beat index (for beatsSinceHeartbeat calculation)
+     */
+    static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
     /**
      * Get this agent's full beat status from the registry.
      */
@@ -295,4 +493,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 Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };