@provenonce/sdk 0.11.0 → 0.14.0

package/dist/index.d.mts

@@ -15,12 +15,11 @@
  *     registryUrl: 'https://provenonce.io',
  *   });
  *
- *   await agent.init();           // Birth in Beat time
- *   await agent.pulse(50);        // Compute 50 beats
- *   await agent.checkin();        // Report to registry
+ *   await agent.init();           // Initialize agent state
+ *   await agent.heartbeat();      // Send paid heartbeat (Phase 2)
  *
- *   // Or run the autonomous heartbeat:
- *   agent.startHeartbeat();       // Computes + checks in continuously
+ *   // Or run the autonomous heartbeat loop:
+ *   agent.startHeartbeat();       // Heartbeats at regular intervals
  *   // ... do your agent work ...
  *   agent.stopHeartbeat();
  *
@@ -161,6 +160,20 @@ interface Beat {
     anchor_hash?: string;
 }
 declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string, anchorHash?: string): Beat;
+/**
+ * Verify an anchor hash locally.
+ * V3 (solana_entropy present): binary-canonical single SHA-256.
+ * V1 legacy (no entropy): string-based hash with difficulty iteration.
+ */
+declare function verifyAnchorHash(anchor: {
+    prev_hash: string;
+    beat_index: number;
+    hash: string;
+    utc: number;
+    epoch: number;
+    difficulty: number;
+    solana_entropy?: string;
+}): boolean;
 /** Result from a check-in submission */
 interface CheckinResult {
     ok: boolean;
@@ -175,8 +188,34 @@ interface SpawnResult {
     ok: boolean;
     eligible: boolean;
     child_hash?: string;
+    spawn_authorization?: string;
+    receipt_based?: boolean;
+    required_beats?: number;
+    accumulated_beats?: number;
     progress_pct?: number;
     deficit?: number;
+    error?: string;
+}
+/** A signed work-proof receipt from the Beats service. */
+interface WorkProofReceipt {
+    type: string;
+    beats_verified: number;
+    difficulty: number;
+    anchor_index: number;
+    anchor_hash: string | null;
+    from_hash: string;
+    to_hash: string;
+    utc: string;
+    signature: string;
+    [key: string]: unknown;
+}
+/** Result of computeWorkProof() */
+interface WorkProofResult {
+    ok: boolean;
+    receipt?: WorkProofReceipt;
+    beats_computed?: number;
+    elapsed_ms?: number;
+    error?: string;
 }
 /** Agent status from the registry */
 interface AgentStatus {
@@ -191,21 +230,8 @@ interface AgentStatus {
     };
     difficulty?: number;
 }
-/**
- * Generate an Ed25519 keypair for agent wallet identity.
- * Returns hex-encoded raw keys (32 bytes each).
- * Uses Node.js built-in crypto — zero external dependencies.
- */
-declare function generateWalletKeypair(): {
-    publicKey: string;
-    secretKey: string;
-};
 /** Wallet info returned from root registration */
 interface WalletInfo {
-    /** Hex-encoded 32-byte Ed25519 public key (Solana self-custody only, empty otherwise) */
-    public_key: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed — SAVE THIS for future fee signing (Solana self-custody only) */
-    secret_key: string;
     /** Solana-compatible base58 address (Solana wallets only) */
     solana_address?: string;
     /** The wallet address (base58 for Solana, 0x for Ethereum) */
@@ -252,10 +278,8 @@ interface RegisterOptions {
     registrationToken?: string;
     /** Admin-minted invite token */
     registrationInvite?: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
-    walletSecretKey?: string;
-    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
-    walletModel?: 'self-custody' | 'operator';
+    /** Wallet model: 'operator' (Model B). Must be set explicitly to opt in. */
+    walletModel?: 'operator';
     /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
     walletChain?: 'solana' | 'ethereum';
     /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
@@ -281,20 +305,6 @@ interface RegisterOptions {
  * No wallet (default, single-phase):
  *   const creds = await register('my-agent', { registryUrl: '...' });
  *
- * Solana self-custody wallet (Model A, two-phase):
- *   const creds = await register('my-org', {
- *     registryUrl: '...',
- *     walletModel: 'self-custody',
- *   });
- *   // creds.wallet.secret_key = hex secret (SAVE THIS)
- *   // creds.wallet.address = base58 Solana address
- *
- * Solana with existing key:
- *   const creds = await register('my-org', {
- *     registryUrl: '...',
- *     walletSecretKey: '<hex-encoded-32-byte-seed>',
- *   });
- *
  * Ethereum bring-your-own (two-phase):
  *   const creds = await register('my-org', {
  *     registryUrl: '...',
@@ -342,6 +352,10 @@ interface BeatAgentConfig {
     onStatusChange?: (status: string, details: Record<string, unknown>) => void;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** Verify anchor hash locally before trusting it (default: true). */
+    verifyAnchors?: boolean;
+    /** Beats service URL for work-proof submission (default: https://beats.provenonce.dev). */
+    beatsUrl?: string;
 }
 declare class BeatAgent {
     private config;
@@ -366,24 +380,8 @@ declare class BeatAgent {
         genesis?: string;
         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).
-     */
-    pulse(count?: number): Beat[];
-    /** Internal beat computation — no status check. Used by both pulse() and resync(). */
+    /** Internal beat computation — no status check. Used by resync(). */
     private computeBeats;
-    /**
-     * @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;
-        total_beats?: number;
-        error?: string;
-    }>;
     /**
      * Start the autonomous heartbeat loop.
      * Phase 2: Sends paid heartbeats at regular intervals.
@@ -397,8 +395,14 @@ declare class BeatAgent {
      */
     stopHeartbeat(): void;
     /**
-     * @deprecated Phase 2: Resync retired (D-67). Dormancy resume is free — just call heartbeat().
-     * This method will be removed in the next major version.
+     * Re-Sync Challenge (D-67 reversal): reactivate a frozen agent by proving CPU work.
+     *
+     * When BEATS_REQUIRED=true on the server: requires a signed Beats work-proof
+     * receipt. This method computes the proof automatically using computeWorkProof().
+     *
+     * When BEATS_REQUIRED=false (devnet): no receipt needed — agent is reactivated freely.
+     *
+     * Gap formula: min(gap_anchors * 100, 10_000) beats required (matches Beats constants).
      */
     resync(): Promise<{
         ok: boolean;
@@ -407,9 +411,45 @@ declare class BeatAgent {
     }>;
     /**
      * Request to spawn a child agent.
-     * Requires sufficient accumulated beats (Temporal Gestation).
+     * Requires sufficient accumulated beats (Temporal Gestation), OR a valid Beats work-proof receipt.
+     *
+     * @param childName    Optional name for the child agent
+     * @param childHash    Pre-registered child hash (Step 2 finalization)
+     * @param beatsReceipt Signed work-proof receipt from computeWorkProof() (receipt-based spawn)
+     */
+    requestSpawn(childName?: string, childHash?: string, beatsReceipt?: WorkProofReceipt): Promise<SpawnResult>;
+    /**
+     * Compute a Beats work-proof for spawn or resync authorization.
+     *
+     * Computes `beatsNeeded` sequential SHA-256 beats at `difficulty`, weaving in
+     * the given anchor hash, then submits to the Beats service and returns a signed receipt.
+     *
+     * @param opts.beatsNeeded  Minimum beats required (from spawn/resync response.required_beats)
+     * @param opts.anchorHash   Current global anchor hash (from syncGlobal or getAnchor)
+     * @param opts.anchorIndex  Current global anchor index
+     * @param opts.difficulty   Beat difficulty (default: agent's current difficulty)
+     */
+    computeWorkProof(opts: {
+        beatsNeeded: number;
+        anchorHash: string;
+        anchorIndex: number;
+        difficulty?: number;
+    }): Promise<WorkProofResult>;
+    /**
+     * Compute a Beats work-proof and use it to request spawn authorization.
+     *
+     * Probes the spawn endpoint to determine required beats, computes the proof,
+     * and returns the spawn_authorization token. The caller still needs to:
+     *   1. Register the child via POST /api/v1/register with spawn_authorization
+     *   2. Finalize via POST /api/v1/agent/spawn with child_hash
+     *
+     * @param opts.childName   Optional name for the child agent
+     * @param opts.beatsNeeded Override the required beats (default: auto-probed)
      */
-    requestSpawn(childName?: string, childHash?: string): Promise<SpawnResult>;
+    requestSpawnWithBeatsProof(opts?: {
+        childName?: string;
+        beatsNeeded?: number;
+    }): Promise<SpawnResult>;
     /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
     private cachedProof;
     /**
@@ -585,4 +625,4 @@ 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 RegisterOptions, 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 };
+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 RegisterOptions, 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, type WorkProofReceipt, type WorkProofResult, computeBeat, computeBeatsLite, register, verifyAnchorHash };

package/dist/index.d.ts

@@ -15,12 +15,11 @@
  *     registryUrl: 'https://provenonce.io',
  *   });
  *
- *   await agent.init();           // Birth in Beat time
- *   await agent.pulse(50);        // Compute 50 beats
- *   await agent.checkin();        // Report to registry
+ *   await agent.init();           // Initialize agent state
+ *   await agent.heartbeat();      // Send paid heartbeat (Phase 2)
  *
- *   // Or run the autonomous heartbeat:
- *   agent.startHeartbeat();       // Computes + checks in continuously
+ *   // Or run the autonomous heartbeat loop:
+ *   agent.startHeartbeat();       // Heartbeats at regular intervals
  *   // ... do your agent work ...
  *   agent.stopHeartbeat();
  *
@@ -161,6 +160,20 @@ interface Beat {
     anchor_hash?: string;
 }
 declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string, anchorHash?: string): Beat;
+/**
+ * Verify an anchor hash locally.
+ * V3 (solana_entropy present): binary-canonical single SHA-256.
+ * V1 legacy (no entropy): string-based hash with difficulty iteration.
+ */
+declare function verifyAnchorHash(anchor: {
+    prev_hash: string;
+    beat_index: number;
+    hash: string;
+    utc: number;
+    epoch: number;
+    difficulty: number;
+    solana_entropy?: string;
+}): boolean;
 /** Result from a check-in submission */
 interface CheckinResult {
     ok: boolean;
@@ -175,8 +188,34 @@ interface SpawnResult {
     ok: boolean;
     eligible: boolean;
     child_hash?: string;
+    spawn_authorization?: string;
+    receipt_based?: boolean;
+    required_beats?: number;
+    accumulated_beats?: number;
     progress_pct?: number;
     deficit?: number;
+    error?: string;
+}
+/** A signed work-proof receipt from the Beats service. */
+interface WorkProofReceipt {
+    type: string;
+    beats_verified: number;
+    difficulty: number;
+    anchor_index: number;
+    anchor_hash: string | null;
+    from_hash: string;
+    to_hash: string;
+    utc: string;
+    signature: string;
+    [key: string]: unknown;
+}
+/** Result of computeWorkProof() */
+interface WorkProofResult {
+    ok: boolean;
+    receipt?: WorkProofReceipt;
+    beats_computed?: number;
+    elapsed_ms?: number;
+    error?: string;
 }
 /** Agent status from the registry */
 interface AgentStatus {
@@ -191,21 +230,8 @@ interface AgentStatus {
     };
     difficulty?: number;
 }
-/**
- * Generate an Ed25519 keypair for agent wallet identity.
- * Returns hex-encoded raw keys (32 bytes each).
- * Uses Node.js built-in crypto — zero external dependencies.
- */
-declare function generateWalletKeypair(): {
-    publicKey: string;
-    secretKey: string;
-};
 /** Wallet info returned from root registration */
 interface WalletInfo {
-    /** Hex-encoded 32-byte Ed25519 public key (Solana self-custody only, empty otherwise) */
-    public_key: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed — SAVE THIS for future fee signing (Solana self-custody only) */
-    secret_key: string;
     /** Solana-compatible base58 address (Solana wallets only) */
     solana_address?: string;
     /** The wallet address (base58 for Solana, 0x for Ethereum) */
@@ -252,10 +278,8 @@ interface RegisterOptions {
     registrationToken?: string;
     /** Admin-minted invite token */
     registrationInvite?: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
-    walletSecretKey?: string;
-    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
-    walletModel?: 'self-custody' | 'operator';
+    /** Wallet model: 'operator' (Model B). Must be set explicitly to opt in. */
+    walletModel?: 'operator';
     /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
     walletChain?: 'solana' | 'ethereum';
     /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
@@ -281,20 +305,6 @@ interface RegisterOptions {
  * No wallet (default, single-phase):
  *   const creds = await register('my-agent', { registryUrl: '...' });
  *
- * Solana self-custody wallet (Model A, two-phase):
- *   const creds = await register('my-org', {
- *     registryUrl: '...',
- *     walletModel: 'self-custody',
- *   });
- *   // creds.wallet.secret_key = hex secret (SAVE THIS)
- *   // creds.wallet.address = base58 Solana address
- *
- * Solana with existing key:
- *   const creds = await register('my-org', {
- *     registryUrl: '...',
- *     walletSecretKey: '<hex-encoded-32-byte-seed>',
- *   });
- *
  * Ethereum bring-your-own (two-phase):
  *   const creds = await register('my-org', {
  *     registryUrl: '...',
@@ -342,6 +352,10 @@ interface BeatAgentConfig {
     onStatusChange?: (status: string, details: Record<string, unknown>) => void;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** Verify anchor hash locally before trusting it (default: true). */
+    verifyAnchors?: boolean;
+    /** Beats service URL for work-proof submission (default: https://beats.provenonce.dev). */
+    beatsUrl?: string;
 }
 declare class BeatAgent {
     private config;
@@ -366,24 +380,8 @@ declare class BeatAgent {
         genesis?: string;
         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).
-     */
-    pulse(count?: number): Beat[];
-    /** Internal beat computation — no status check. Used by both pulse() and resync(). */
+    /** Internal beat computation — no status check. Used by resync(). */
     private computeBeats;
-    /**
-     * @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;
-        total_beats?: number;
-        error?: string;
-    }>;
     /**
      * Start the autonomous heartbeat loop.
      * Phase 2: Sends paid heartbeats at regular intervals.
@@ -397,8 +395,14 @@ declare class BeatAgent {
      */
     stopHeartbeat(): void;
     /**
-     * @deprecated Phase 2: Resync retired (D-67). Dormancy resume is free — just call heartbeat().
-     * This method will be removed in the next major version.
+     * Re-Sync Challenge (D-67 reversal): reactivate a frozen agent by proving CPU work.
+     *
+     * When BEATS_REQUIRED=true on the server: requires a signed Beats work-proof
+     * receipt. This method computes the proof automatically using computeWorkProof().
+     *
+     * When BEATS_REQUIRED=false (devnet): no receipt needed — agent is reactivated freely.
+     *
+     * Gap formula: min(gap_anchors * 100, 10_000) beats required (matches Beats constants).
      */
     resync(): Promise<{
         ok: boolean;
@@ -407,9 +411,45 @@ declare class BeatAgent {
     }>;
     /**
      * Request to spawn a child agent.
-     * Requires sufficient accumulated beats (Temporal Gestation).
+     * Requires sufficient accumulated beats (Temporal Gestation), OR a valid Beats work-proof receipt.
+     *
+     * @param childName    Optional name for the child agent
+     * @param childHash    Pre-registered child hash (Step 2 finalization)
+     * @param beatsReceipt Signed work-proof receipt from computeWorkProof() (receipt-based spawn)
+     */
+    requestSpawn(childName?: string, childHash?: string, beatsReceipt?: WorkProofReceipt): Promise<SpawnResult>;
+    /**
+     * Compute a Beats work-proof for spawn or resync authorization.
+     *
+     * Computes `beatsNeeded` sequential SHA-256 beats at `difficulty`, weaving in
+     * the given anchor hash, then submits to the Beats service and returns a signed receipt.
+     *
+     * @param opts.beatsNeeded  Minimum beats required (from spawn/resync response.required_beats)
+     * @param opts.anchorHash   Current global anchor hash (from syncGlobal or getAnchor)
+     * @param opts.anchorIndex  Current global anchor index
+     * @param opts.difficulty   Beat difficulty (default: agent's current difficulty)
+     */
+    computeWorkProof(opts: {
+        beatsNeeded: number;
+        anchorHash: string;
+        anchorIndex: number;
+        difficulty?: number;
+    }): Promise<WorkProofResult>;
+    /**
+     * Compute a Beats work-proof and use it to request spawn authorization.
+     *
+     * Probes the spawn endpoint to determine required beats, computes the proof,
+     * and returns the spawn_authorization token. The caller still needs to:
+     *   1. Register the child via POST /api/v1/register with spawn_authorization
+     *   2. Finalize via POST /api/v1/agent/spawn with child_hash
+     *
+     * @param opts.childName   Optional name for the child agent
+     * @param opts.beatsNeeded Override the required beats (default: auto-probed)
      */
-    requestSpawn(childName?: string, childHash?: string): Promise<SpawnResult>;
+    requestSpawnWithBeatsProof(opts?: {
+        childName?: string;
+        beatsNeeded?: number;
+    }): Promise<SpawnResult>;
     /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
     private cachedProof;
     /**
@@ -585,4 +625,4 @@ 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 RegisterOptions, 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 };
+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 RegisterOptions, 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, type WorkProofReceipt, type WorkProofResult, computeBeat, computeBeatsLite, register, verifyAnchorHash };