@provenonce/sdk 0.6.0 → 0.8.0

package/README.md

@@ -17,7 +17,7 @@ import { register } from '@provenonce/sdk';
 
 // Root registration (one-time)
 const creds = await register('my-agent-v1', {
-  registryUrl: 'https://provenonce.vercel.app',
+  registryUrl: 'https://provenonce.io',
   registrationSecret: process.env.REGISTRATION_SECRET, // required in production
 });
 
@@ -27,7 +27,7 @@ console.log(creds.secret);  // save — shown only once
 
 // Child registration (requires parent credentials)
 const child = await register('worker-1', {
-  registryUrl: 'https://provenonce.vercel.app',
+  registryUrl: 'https://provenonce.io',
   parentHash: creds.hash,
   parentApiKey: creds.api_key,
 });
@@ -40,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,
 });
 
@@ -109,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
@@ -65,6 +65,28 @@ 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) */
+    address: string;
+    /** Wallet chain: 'solana' or 'ethereum' */
+    chain: string;
+}
 /** Result from registering an agent */
 interface RegistrationResult {
     hash: string;
@@ -74,21 +96,56 @@ interface RegistrationResult {
     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.
  *
- * Root registration (no parent):
- *   const creds = await register('my-org', { registryUrl: '...' });
+ * 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 registration:
+ * Child agent (no wallet):
  *   const creds = await register('worker-1', {
  *     registryUrl: '...',
  *     parentHash: parentCreds.hash,
@@ -100,6 +157,22 @@ declare function register(name: string, options?: {
     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_...) */
@@ -150,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.
      *
@@ -220,4 +295,4 @@ declare function computeBeatsLite(startHash: string, startIndex: number, count:
     elapsed: number;
 };
 
-export { type AgentStatus, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, type RegistrationResult, type SpawnResult, computeBeat, computeBeatsLite, register };
+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
@@ -65,6 +65,28 @@ 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) */
+    address: string;
+    /** Wallet chain: 'solana' or 'ethereum' */
+    chain: string;
+}
 /** Result from registering an agent */
 interface RegistrationResult {
     hash: string;
@@ -74,21 +96,56 @@ interface RegistrationResult {
     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.
  *
- * Root registration (no parent):
- *   const creds = await register('my-org', { registryUrl: '...' });
+ * 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 registration:
+ * Child agent (no wallet):
  *   const creds = await register('worker-1', {
  *     registryUrl: '...',
  *     parentHash: parentCreds.hash,
@@ -100,6 +157,22 @@ declare function register(name: string, options?: {
     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_...) */
@@ -150,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.
      *
@@ -220,4 +295,4 @@ declare function computeBeatsLite(startHash: string, startIndex: number, count:
     elapsed: number;
 };
 
-export { type AgentStatus, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, type RegistrationResult, type SpawnResult, computeBeat, computeBeatsLite, register };
+export { type AgentStatus, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, type RegistrationResult, type SpawnResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };