@provenonce/beats-client 0.5.0 → 1.0.0

package/index.d.ts

@@ -117,10 +117,78 @@ export interface VerifyApiResponse {
   [key: string]: unknown;
 }
 
+export interface BeatObject {
+  index: number;
+  hash: string;
+  prev: string;
+  timestamp: number;
+  nonce?: string;
+  anchor_hash?: string;
+}
+
+export interface SpotCheck {
+  index: number;
+  hash: string;
+  prev: string;
+  nonce?: string;
+}
+
+export interface WorkProofRequest {
+  from_beat: number;
+  to_beat: number;
+  from_hash: string;
+  to_hash: string;
+  beats_computed: number;
+  difficulty: number;
+  anchor_index: number;
+  anchor_hash?: string;
+  spot_checks: SpotCheck[];
+}
+
+export interface WorkProofReceiptPayload {
+  type: 'work_proof';
+  beats_verified: number;
+  difficulty: number;
+  anchor_index: number;
+  anchor_hash: string | null;
+  utc: number;
+}
+
+export interface WorkProofResponse {
+  ok: boolean;
+  valid: boolean;
+  receipt?: WorkProofReceiptPayload;
+  signature?: string;
+  public_key?: string;
+  spot_checks_verified?: number;
+  reason?: string;
+  failed_indices?: number[];
+  _note?: string;
+}
+
+export interface KeyInfo {
+  public_key_base58: string;
+  public_key_hex: string;
+  signing_context: string;
+  purpose: string;
+}
+
+export interface KeyResponse {
+  /** Timestamp receipt key (backward compat) */
+  public_key_base58: string;
+  public_key_hex: string;
+  algorithm: string;
+  keys: {
+    timestamp: KeyInfo;
+    work_proof: KeyInfo;
+  };
+  _note?: string;
+}
+
 export interface BeatsClient {
   getHealth(): Promise<HealthResponse>;
   getAnchor(opts?: AnchorOptions): Promise<AnchorResponse>;
-  getKey(): Promise<{ public_key_base58: string; public_key_hex: string; algorithm: string; purpose?: string; _note?: string }>;
+  getKey(): Promise<KeyResponse>;
   verify(payload: unknown): Promise<VerifyApiResponse>;
   timestampHash(hash: string): Promise<TimestampResponse>;
 
@@ -143,8 +211,57 @@ export interface BeatsClient {
   /** Returns true if chain continuity is broken and resync() is required. */
   isBroken(): boolean;
 
+  /**
+   * Submit a work proof to the Beats service and receive a signed receipt.
+   * The receipt certifies N beats at difficulty D anchored to a global beat.
+   * Policy-free: the caller (Registry or any consumer) decides what N means.
+   */
+  submitWorkProof(proof: WorkProofRequest): Promise<WorkProofResponse>;
+
+  /**
+   * Verify a work-proof receipt signature offline.
+   * Uses the work_proof key from GET /api/v1/beat/key (distinct from timestamp key).
+   */
+  verifyWorkProofReceipt(
+    receiptResponse: WorkProofResponse,
+    opts?: { publicKey?: string },
+  ): Promise<boolean>;
+
   /** Internal: resolve public key from cache or auto-fetch. */
   _resolveKey(): Promise<string | null>;
 }
 
 export declare function createBeatsClient(options?: BeatsClientOptions): BeatsClient;
+
+// ============ STANDALONE COMPUTE (Node.js only) ============
+
+/**
+ * Compute a single beat — sequential SHA-256 hash chain.
+ * Node.js only (uses node:crypto). Not browser-compatible.
+ *
+ * @param prevHash    Previous beat hash (64 hex)
+ * @param beatIndex   Beat index (monotonically increasing)
+ * @param difficulty  Hash iterations per beat (default 1000)
+ * @param nonce       Optional entropy
+ * @param anchorHash  Optional global anchor hash to weave in
+ */
+export declare function computeBeat(
+  prevHash: string,
+  beatIndex: number,
+  difficulty?: number,
+  nonce?: string,
+  anchorHash?: string,
+): Promise<BeatObject>;
+
+/**
+ * Compute the genesis beat for a local chain.
+ * Deterministic from caller-provided seed + domain prefix.
+ * Node.js only.
+ *
+ * @param seed          Unique identifier (e.g. agent hash)
+ * @param domainPrefix  Namespace prefix (default: 'beats:genesis:v1:')
+ */
+export declare function createGenesisBeat(
+  seed: string,
+  domainPrefix?: string,
+): Promise<BeatObject>;

package/index.mjs

@@ -530,5 +530,141 @@ export function createBeatsClient({
         return null;
       }
     },
+
+    // ---- Work Proof ----
+
+    /**
+     * Submit a work proof to the Beats service and receive a signed receipt.
+     *
+     * @param {object} proof
+     *   @param {number}   proof.from_beat      Starting beat index
+     *   @param {number}   proof.to_beat        Ending beat index
+     *   @param {string}   proof.from_hash      Hash at from_beat (64 hex)
+     *   @param {string}   proof.to_hash        Hash at to_beat (64 hex)
+     *   @param {number}   proof.beats_computed to_beat - from_beat
+     *   @param {number}   proof.difficulty     Hash iterations per beat
+     *   @param {number}   proof.anchor_index   Global anchor index woven in
+     *   @param {string}   [proof.anchor_hash]  Anchor hash woven in (64 hex)
+     *   @param {Array}    proof.spot_checks    Spot-checked beats for verification
+     *     @param {number}  .index              Beat index
+     *     @param {string}  .hash               Hash at this beat (64 hex)
+     *     @param {string}  .prev               Previous hash (64 hex)
+     *     @param {string}  [.nonce]            Optional nonce
+     *
+     * @returns {Promise<WorkProofResponse>}
+     */
+    submitWorkProof(proof) {
+      return request('/api/v1/beat/work-proof', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(proof),
+      });
+    },
+
+    /**
+     * Verify a work-proof receipt signature (offline).
+     * Uses the work_proof key from GET /api/v1/beat/key, not the timestamp key.
+     *
+     * @param {object} receiptResponse  The full response from submitWorkProof()
+     * @param {object} [opts]
+     *   @param {string} [opts.publicKey]  Override: hex or base58 work-proof public key
+     */
+    async verifyWorkProofReceipt(receiptResponse, opts = {}) {
+      const payload = receiptResponse?.receipt;
+      const signature = receiptResponse?.signature;
+      if (!payload || !signature) return false;
+
+      // Resolve work-proof public key: param > cached from /key endpoint
+      let key = opts.publicKey;
+      if (!key) {
+        try {
+          const keyData = await this.getKey();
+          key = keyData?.keys?.work_proof?.public_key_hex ||
+                keyData?.keys?.work_proof?.public_key_base58;
+        } catch {
+          return false;
+        }
+      }
+      if (!key) return false;
+
+      try {
+        return await verifyEd25519(payload, signature, key);
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+// ============ STANDALONE COMPUTE (Node.js only) ============
+
+/**
+ * Compute a single beat — sequential SHA-256 hash chain.
+ *
+ * Each beat requires `difficulty` sequential hash iterations.
+ * Because SHA-256 output feeds the next input, this cannot be
+ * parallelized. This is the CPU-work primitive for local beat chains.
+ *
+ * Node.js only: uses node:crypto. Not available in browser environments.
+ *
+ * @param {string}  prevHash    Previous beat hash (64 hex)
+ * @param {number}  beatIndex   Beat index (monotonically increasing)
+ * @param {number}  [difficulty=1000]  Hash iterations per beat
+ * @param {string}  [nonce]     Optional entropy
+ * @param {string}  [anchorHash]  Global anchor hash to weave in
+ * @returns {{ index, hash, prev, timestamp, nonce?, anchor_hash? }}
+ */
+export async function computeBeat(prevHash, beatIndex, difficulty = 1000, nonce, anchorHash) {
+  if (typeof prevHash !== 'string' || prevHash.length === 0) {
+    throw new Error('computeBeat: prevHash must be a non-empty string');
+  }
+  if (!Number.isInteger(beatIndex) || beatIndex < 0) {
+    throw new Error('computeBeat: beatIndex must be a non-negative integer');
+  }
+  const d = Math.max(1, Math.min(Number.isFinite(difficulty) ? Math.floor(difficulty) : 1000, 1_000_000));
+
+  const { createHash } = await import('node:crypto');
+
+  const seed = anchorHash
+    ? `${prevHash}:${beatIndex}:${nonce || ''}:${anchorHash}`
+    : `${prevHash}:${beatIndex}:${nonce || ''}`;
+
+  let current = createHash('sha256').update(seed, 'utf8').digest('hex');
+  for (let i = 0; i < d; i++) {
+    current = createHash('sha256').update(current, 'utf8').digest('hex');
+  }
+
+  return {
+    index: beatIndex,
+    hash: current,
+    prev: prevHash,
+    timestamp: Date.now(),
+    nonce,
+    anchor_hash: anchorHash,
+  };
+}
+
+/**
+ * Compute the genesis beat for a local chain.
+ * Deterministic from caller-provided seed + optional domain prefix.
+ *
+ * Node.js only.
+ *
+ * @param {string} seed          Unique identifier for this chain (e.g. agent hash)
+ * @param {string} [domainPrefix='beats:genesis:v1:']  Namespace prefix
+ */
+export async function createGenesisBeat(seed, domainPrefix = 'beats:genesis:v1:') {
+  if (!seed || typeof seed !== 'string') {
+    throw new Error('createGenesisBeat: seed must be a non-empty string');
+  }
+  const { createHash } = await import('node:crypto');
+  const genesisHash = createHash('sha256')
+    .update(`${domainPrefix}${seed}`, 'utf8')
+    .digest('hex');
+  return {
+    index: 0,
+    hash: genesisHash,
+    prev: '0'.repeat(64),
+    timestamp: Date.now(),
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provenonce/beats-client",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Minimal client for the public Provenonce Beats service",
   "type": "module",
   "main": "index.mjs",