@provenonce/beats-client 0.4.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

@@ -77,12 +77,33 @@ async function verifyEd25519(payload, signatureBase64, publicKey) {
 
 /**
  * Recompute an anchor's hash from its fields (B-3).
- * Requires Node.js crypto — not available in browsers.
- * Returns true if the recomputed hash matches anchor.hash.
- *
- * A-4: If solana_entropy is present, uses the v2 domain-prefixed nonce.
+ * V3: If solana_entropy is present, uses binary-canonical single SHA-256.
+ * V1 legacy: string-based hash with difficulty iteration (Node.js only).
  */
-const ANCHOR_DOMAIN_PREFIX = 'provenonce:anchor:v2';
+const ANCHOR_DOMAIN_PREFIX = 'PROVENONCE_BEATS_V1';
+
+function hexToUint8Array(hex) {
+  const arr = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < arr.length; i++) {
+    arr[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return arr;
+}
+
+function u64beBytes(n) {
+  const buf = new Uint8Array(8);
+  const hi = Math.floor(n / 0x100000000);
+  const lo = n >>> 0;
+  buf[0] = (hi >>> 24) & 0xff;
+  buf[1] = (hi >>> 16) & 0xff;
+  buf[2] = (hi >>> 8) & 0xff;
+  buf[3] = hi & 0xff;
+  buf[4] = (lo >>> 24) & 0xff;
+  buf[5] = (lo >>> 16) & 0xff;
+  buf[6] = (lo >>> 8) & 0xff;
+  buf[7] = lo & 0xff;
+  return buf;
+}
 
 async function recomputeAnchorHash(anchor) {
   if (!anchor || !HEX64.test(anchor.hash) || !HEX64.test(anchor.prev_hash)) return false;
@@ -91,11 +112,41 @@ async function recomputeAnchorHash(anchor) {
   if (!Number.isInteger(anchor.utc) || anchor.utc < 0) return false;
   if (!Number.isInteger(anchor.epoch) || anchor.epoch < 0) return false;
 
+  if (anchor.solana_entropy) {
+    // V3: binary-canonical single SHA-256
+    const prefix = new TextEncoder().encode(ANCHOR_DOMAIN_PREFIX);    // 19 bytes
+    const prev = hexToUint8Array(anchor.prev_hash);                    // 32 bytes
+    const idx = u64beBytes(anchor.beat_index);                         // 8 bytes
+    const entropy = decodeBase58(anchor.solana_entropy);               // 32 bytes
+
+    const preimage = new Uint8Array(prefix.length + prev.length + idx.length + entropy.length);
+    preimage.set(prefix, 0);
+    preimage.set(prev, prefix.length);
+    preimage.set(idx, prefix.length + prev.length);
+    preimage.set(entropy, prefix.length + prev.length + idx.length);
+
+    // Web Crypto path
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle) {
+      try {
+        const digest = await subtle.digest('SHA-256', preimage);
+        const hashArr = Array.from(new Uint8Array(digest));
+        const computed = hashArr.map(b => b.toString(16).padStart(2, '0')).join('');
+        return computed === anchor.hash;
+      } catch {
+        // Fall through to Node.js
+      }
+    }
+
+    // Node.js fallback
+    const { createHash } = await import('node:crypto');
+    const computed = createHash('sha256').update(preimage).digest('hex');
+    return computed === anchor.hash;
+  }
+
+  // V1 legacy: string-based hash with difficulty iteration
   const { createHash } = await import('node:crypto');
-  // A-4: v2 nonce includes solana_entropy; legacy nonce for pre-A4 anchors
-  const nonce = anchor.solana_entropy
-    ? `${ANCHOR_DOMAIN_PREFIX}:${anchor.utc}:${anchor.epoch}:${anchor.solana_entropy}`
-    : `anchor:${anchor.utc}:${anchor.epoch}`;
+  const nonce = `anchor:${anchor.utc}:${anchor.epoch}`;
   const seed = `${anchor.prev_hash}:${anchor.beat_index}:${nonce}`;
   let current = createHash('sha256').update(seed, 'utf8').digest('hex');
   for (let i = 0; i < anchor.difficulty; i++) {
@@ -479,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.4.0",
+  "version": "1.0.0",
   "description": "Minimal client for the public Provenonce Beats service",
   "type": "module",
   "main": "index.mjs",