@provenonce/sdk 0.5.0 → 0.8.0

package/README.md

@@ -8,6 +8,31 @@ Agent heartbeat client for sovereign time authentication on Solana.
 npm install @provenonce/sdk
 ```
 
+## Registration
+
+Before using the SDK, register your agent to get an API key:
+
+```typescript
+import { register } from '@provenonce/sdk';
+
+// Root registration (one-time)
+const creds = await register('my-agent-v1', {
+  registryUrl: 'https://provenonce.io',
+  registrationSecret: process.env.REGISTRATION_SECRET, // required in production
+});
+
+console.log(creds.hash);    // unique agent identity
+console.log(creds.api_key); // use this for BeatAgent
+console.log(creds.secret);  // save — shown only once
+
+// Child registration (requires parent credentials)
+const child = await register('worker-1', {
+  registryUrl: 'https://provenonce.io',
+  parentHash: creds.hash,
+  parentApiKey: creds.api_key,
+});
+```
+
 ## Quick Start
 
 ```typescript
@@ -15,7 +40,7 @@ import { BeatAgent } from '@provenonce/sdk';
 
 const agent = new BeatAgent({
   apiKey: 'pvn_...',
-  registryUrl: 'https://provenonce.vercel.app',
+  registryUrl: 'https://provenonce.io',
   verbose: true,
 });
 
@@ -84,7 +109,7 @@ Python examples use the REST API directly — no Python SDK needed. See [`exampl
 
 ## Links
 
-- [Live prototype](https://provenonce.vercel.app)
+- [Live prototype](https://provenonce.io)
 - [npm package](https://www.npmjs.com/package/@provenonce/sdk)
-- [API docs](https://provenonce.vercel.app/docs)
+- [API docs](https://provenonce.io/docs)
 - [GitHub](https://github.com/jarekpiot/provenonce)

package/dist/index.d.mts

@@ -12,7 +12,7 @@
  *
  *   const agent = new BeatAgent({
  *     apiKey: 'pvn_...',
- *     registryUrl: 'https://provenonce.vercel.app',
+ *     registryUrl: 'https://provenonce.io',
  *   });
  *
  *   await agent.init();           // Birth in Beat time
@@ -32,8 +32,148 @@ interface Beat {
     prev: string;
     timestamp: number;
     nonce?: string;
+    anchor_hash?: string;
 }
-declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string): Beat;
+declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string, anchorHash?: string): Beat;
+/** Result from a check-in submission */
+interface CheckinResult {
+    ok: boolean;
+    total_beats: number;
+    beats_accepted: number;
+    global_beat: number;
+    status?: string;
+    beats_behind?: number;
+}
+/** Result from a spawn request */
+interface SpawnResult {
+    ok: boolean;
+    eligible: boolean;
+    child_hash?: string;
+    progress_pct?: number;
+    deficit?: number;
+}
+/** Agent status from the registry */
+interface AgentStatus {
+    already_initialized: boolean;
+    total_beats: number;
+    genesis_hash: string;
+    status: string;
+    genesis?: {
+        hash: string;
+        prev: string;
+        timestamp: number;
+    };
+    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) */
+    address: string;
+    /** Wallet chain: 'solana' or 'ethereum' */
+    chain: string;
+}
+/** Result from registering an agent */
+interface RegistrationResult {
+    hash: string;
+    api_key: string;
+    secret: string;
+    type: 'root' | 'agent';
+    parent: string | null;
+    depth: number;
+    name: string;
+    metadata?: Record<string, unknown> | null;
+    signature: string;
+    explorer_url?: string;
+    /** Wallet chain: 'solana', 'ethereum', or null (no wallet) */
+    wallet_chain?: string | null;
+    beat?: {
+        genesis_hash: string;
+        difficulty: number;
+        status: string;
+    };
+    /** Wallet info — only present for root agents with wallets */
+    wallet?: WalletInfo;
+}
+/**
+ * Register a new agent on the Provenonce registry.
+ *
+ * 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: '...',
+ *     walletChain: 'ethereum',
+ *     walletAddress: '0x...',
+ *     walletSignFn: (msg) => wallet.signMessage(msg),
+ *   });
+ *
+ * Solana operator (Model B, two-phase):
+ *   const creds = await register('my-org', {
+ *     registryUrl: '...',
+ *     walletModel: 'operator',
+ *     operatorWalletAddress: '<base58>',
+ *     operatorSignFn: (msg) => signWithWallet(msg),
+ *   });
+ *
+ * Child agent (no wallet):
+ *   const creds = await register('worker-1', {
+ *     registryUrl: '...',
+ *     parentHash: parentCreds.hash,
+ *     parentApiKey: parentCreds.api_key,
+ *   });
+ */
+declare function register(name: string, options?: {
+    registryUrl?: string;
+    parentHash?: string;
+    parentApiKey?: string;
+    registrationSecret?: 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 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) */
+    walletAddress?: string;
+    /** Async function to sign a message with an Ethereum wallet (EIP-191 personal_sign). Returns 0x-prefixed 65-byte hex sig. */
+    walletSignFn?: (message: string) => Promise<string>;
+    /** Operator's Solana wallet address (base58). Required when walletModel='operator'. */
+    operatorWalletAddress?: string;
+    /** Function to sign a message with the operator's Solana wallet. Required when walletModel='operator'. */
+    operatorSignFn?: (message: string) => Promise<string>;
+    /** Optional agent metadata (arbitrary JSON object, max 4KB). Returned in /verify and /status. */
+    metadata?: Record<string, unknown>;
+}): Promise<RegistrationResult>;
 interface BeatAgentConfig {
     /** API key from registration (pvn_...) */
     apiKey: string;
@@ -46,11 +186,11 @@ interface BeatAgentConfig {
     /** Callback when heartbeat ticks */
     onPulse?: (beats: Beat[], totalBeats: number) => void;
     /** Callback when check-in completes */
-    onCheckin?: (result: any) => void;
+    onCheckin?: (result: CheckinResult) => void;
     /** Callback on error */
     onError?: (error: Error, context: string) => void;
     /** Callback when status changes */
-    onStatusChange?: (status: string, details: any) => void;
+    onStatusChange?: (status: string, details: Record<string, unknown>) => void;
     /** Enable verbose logging */
     verbose?: boolean;
 }
@@ -65,6 +205,7 @@ declare class BeatAgent {
     private status;
     private heartbeatInterval;
     private globalBeat;
+    private globalAnchorHash;
     constructor(config: BeatAgentConfig);
     /**
      * Initialize the agent's Beat chain.
@@ -82,6 +223,8 @@ declare class BeatAgent {
      * 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.
      *
@@ -120,11 +263,11 @@ declare class BeatAgent {
      * Request to spawn a child agent.
      * Requires sufficient accumulated beats (Temporal Gestation).
      */
-    requestSpawn(childName?: string, childHash?: string): Promise<any>;
+    requestSpawn(childName?: string, childHash?: string): Promise<SpawnResult>;
     /**
      * Get this agent's full beat status from the registry.
      */
-    getStatus(): Promise<any>;
+    getStatus(): Promise<AgentStatus>;
     /**
      * Get local state (no network call).
      */
@@ -147,9 +290,9 @@ declare class BeatAgent {
  * Compute N sequential VDF beats.
  * Returns only the last beat (for lightweight usage).
  */
-declare function computeBeatsLite(startHash: string, startIndex: number, count: number, difficulty?: number): {
+declare function computeBeatsLite(startHash: string, startIndex: number, count: number, difficulty?: number, anchorHash?: string): {
     lastBeat: Beat;
     elapsed: number;
 };
 
-export { type Beat, BeatAgent, type BeatAgentConfig, computeBeat, computeBeatsLite };
+export { type AgentStatus, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, type RegistrationResult, type SpawnResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  *
  *   const agent = new BeatAgent({
  *     apiKey: 'pvn_...',
- *     registryUrl: 'https://provenonce.vercel.app',
+ *     registryUrl: 'https://provenonce.io',
  *   });
  *
  *   await agent.init();           // Birth in Beat time
@@ -32,8 +32,148 @@ interface Beat {
     prev: string;
     timestamp: number;
     nonce?: string;
+    anchor_hash?: string;
 }
-declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string): Beat;
+declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string, anchorHash?: string): Beat;
+/** Result from a check-in submission */
+interface CheckinResult {
+    ok: boolean;
+    total_beats: number;
+    beats_accepted: number;
+    global_beat: number;
+    status?: string;
+    beats_behind?: number;
+}
+/** Result from a spawn request */
+interface SpawnResult {
+    ok: boolean;
+    eligible: boolean;
+    child_hash?: string;
+    progress_pct?: number;
+    deficit?: number;
+}
+/** Agent status from the registry */
+interface AgentStatus {
+    already_initialized: boolean;
+    total_beats: number;
+    genesis_hash: string;
+    status: string;
+    genesis?: {
+        hash: string;
+        prev: string;
+        timestamp: number;
+    };
+    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) */
+    address: string;
+    /** Wallet chain: 'solana' or 'ethereum' */
+    chain: string;
+}
+/** Result from registering an agent */
+interface RegistrationResult {
+    hash: string;
+    api_key: string;
+    secret: string;
+    type: 'root' | 'agent';
+    parent: string | null;
+    depth: number;
+    name: string;
+    metadata?: Record<string, unknown> | null;
+    signature: string;
+    explorer_url?: string;
+    /** Wallet chain: 'solana', 'ethereum', or null (no wallet) */
+    wallet_chain?: string | null;
+    beat?: {
+        genesis_hash: string;
+        difficulty: number;
+        status: string;
+    };
+    /** Wallet info — only present for root agents with wallets */
+    wallet?: WalletInfo;
+}
+/**
+ * Register a new agent on the Provenonce registry.
+ *
+ * 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: '...',
+ *     walletChain: 'ethereum',
+ *     walletAddress: '0x...',
+ *     walletSignFn: (msg) => wallet.signMessage(msg),
+ *   });
+ *
+ * Solana operator (Model B, two-phase):
+ *   const creds = await register('my-org', {
+ *     registryUrl: '...',
+ *     walletModel: 'operator',
+ *     operatorWalletAddress: '<base58>',
+ *     operatorSignFn: (msg) => signWithWallet(msg),
+ *   });
+ *
+ * Child agent (no wallet):
+ *   const creds = await register('worker-1', {
+ *     registryUrl: '...',
+ *     parentHash: parentCreds.hash,
+ *     parentApiKey: parentCreds.api_key,
+ *   });
+ */
+declare function register(name: string, options?: {
+    registryUrl?: string;
+    parentHash?: string;
+    parentApiKey?: string;
+    registrationSecret?: 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 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) */
+    walletAddress?: string;
+    /** Async function to sign a message with an Ethereum wallet (EIP-191 personal_sign). Returns 0x-prefixed 65-byte hex sig. */
+    walletSignFn?: (message: string) => Promise<string>;
+    /** Operator's Solana wallet address (base58). Required when walletModel='operator'. */
+    operatorWalletAddress?: string;
+    /** Function to sign a message with the operator's Solana wallet. Required when walletModel='operator'. */
+    operatorSignFn?: (message: string) => Promise<string>;
+    /** Optional agent metadata (arbitrary JSON object, max 4KB). Returned in /verify and /status. */
+    metadata?: Record<string, unknown>;
+}): Promise<RegistrationResult>;
 interface BeatAgentConfig {
     /** API key from registration (pvn_...) */
     apiKey: string;
@@ -46,11 +186,11 @@ interface BeatAgentConfig {
     /** Callback when heartbeat ticks */
     onPulse?: (beats: Beat[], totalBeats: number) => void;
     /** Callback when check-in completes */
-    onCheckin?: (result: any) => void;
+    onCheckin?: (result: CheckinResult) => void;
     /** Callback on error */
     onError?: (error: Error, context: string) => void;
     /** Callback when status changes */
-    onStatusChange?: (status: string, details: any) => void;
+    onStatusChange?: (status: string, details: Record<string, unknown>) => void;
     /** Enable verbose logging */
     verbose?: boolean;
 }
@@ -65,6 +205,7 @@ declare class BeatAgent {
     private status;
     private heartbeatInterval;
     private globalBeat;
+    private globalAnchorHash;
     constructor(config: BeatAgentConfig);
     /**
      * Initialize the agent's Beat chain.
@@ -82,6 +223,8 @@ declare class BeatAgent {
      * 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.
      *
@@ -120,11 +263,11 @@ declare class BeatAgent {
      * Request to spawn a child agent.
      * Requires sufficient accumulated beats (Temporal Gestation).
      */
-    requestSpawn(childName?: string, childHash?: string): Promise<any>;
+    requestSpawn(childName?: string, childHash?: string): Promise<SpawnResult>;
     /**
      * Get this agent's full beat status from the registry.
      */
-    getStatus(): Promise<any>;
+    getStatus(): Promise<AgentStatus>;
     /**
      * Get local state (no network call).
      */
@@ -147,9 +290,9 @@ declare class BeatAgent {
  * Compute N sequential VDF beats.
  * Returns only the last beat (for lightweight usage).
  */
-declare function computeBeatsLite(startHash: string, startIndex: number, count: number, difficulty?: number): {
+declare function computeBeatsLite(startHash: string, startIndex: number, count: number, difficulty?: number, anchorHash?: string): {
     lastBeat: Beat;
     elapsed: number;
 };
 
-export { type Beat, BeatAgent, type BeatAgentConfig, computeBeat, computeBeatsLite };
+export { type AgentStatus, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, type RegistrationResult, type SpawnResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };