openshard-shared 1.0.1

package/README.md

@@ -0,0 +1,11 @@
+# @openshard/shared
+
+> Shared utilities, types, constants, Prometheus metrics, and payment verification helpers for the OpenShard ecosystem.
+
+This package provides common foundational code consumed across buyer proxies, seller nodes, registry servers, and CLI tools in the OpenShard monorepo.
+
+## Modules
+
+- `prometheus.js`: Shared Prometheus registry, metric formatting, and monitoring wrappers.
+- `payments.js`: Cryptographic helpers, EIP-712 structured data signing, USDC formatting utilities, and x402 verification logic.
+- `index.js`: Common constants, networking defaults, port mappings, and error formatting structures.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "openshard-shared",
+  "version": "1.0.1",
+  "description": "Shared types, constants, and utilities for the anteseed network",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "echo 'shared has no build step'"
+  },
+  "dependencies": {
+    "viem": "^2.21.19"
+  },
+  "keywords": [],
+  "license": "ISC"
+}

package/src/index.js

@@ -0,0 +1,57 @@
+// ─── Shared constants & types for the anteseed network ───────────────────────
+
+export const REGISTRY_PORT = 9000;
+export const BUYER_PORT    = 8377;
+export const SELLER_PORT   = 8378; // default; each seller can override via env
+
+// ─── Provider capability advertised to the registry ──────────────────────────
+
+/**
+ * @typedef {Object} ServicePricing
+ * @property {number} inputUsdPerMillion
+ * @property {number} cachedInputUsdPerMillion
+ * @property {number} outputUsdPerMillion
+ */
+
+/**
+ * @typedef {Object} ServiceDefinition
+ * @property {string}   id              - buyer-facing model name, e.g. "claude-sonnet-4-6"
+ * @property {string}   upstreamModel   - actual model name sent to the upstream API
+ * @property {string[]} categories      - ["chat","coding","math"]
+ * @property {ServicePricing} pricing
+ */
+
+/**
+ * @typedef {Object} ProviderAdvertisement
+ * @property {string}              peerId       - hex public key / node identity
+ * @property {string}              endpoint     - http://host:port the buyer connects to
+ * @property {ServiceDefinition[]} services
+ * @property {number}              registeredAt - unix ms
+ * @property {number}              lastSeen     - unix ms
+ */
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the peer heartbeat is still considered "live"
+ * (seen within the last 60 seconds).
+ * @param {ProviderAdvertisement} peer
+ */
+export function isAlive(peer) {
+  return Date.now() - peer.lastSeen < 60_000;
+}
+
+/**
+ * Build a standard error body used across all Fastify nodes.
+ * @param {string} code    - machine-readable error code
+ * @param {string} message - human-readable detail
+ */
+export function errorBody(code, message) {
+  return { error: { code, message } };
+}
+
+// ─── Re-export payment utilities ─────────────────────────────────────────────
+export * from './payments.js';
+
+// ─── Re-export prometheus utilities ───────────────────────────────────────────
+export * from './prometheus.js';

package/src/payments.js

@@ -0,0 +1,217 @@
+/**
+ * openshard_ggshared — payments.js
+ *
+ * EIP-712 signing utilities for ReserveAuth and SpendingAuth messages.
+ * Used by both the buyer proxy (signing) and the seller node (verification).
+ *
+ * Requires: viem  (npm install viem)
+ */
+
+import {
+  createWalletClient,
+  createPublicClient,
+  http,
+  keccak256,
+  toBytes,
+  concat,
+  encodeAbiParameters,
+  parseAbiParameters,
+  recoverTypedDataAddress,
+  parseUnits,
+  formatUnits
+} from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base, baseSepolia } from 'viem/chains';
+import { hardhat } from 'viem/chains';
+
+// ─── USDC constants ───────────────────────────────────────────────────────────
+
+/** USDC on Base mainnet */
+export const USDC_BASE_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+/** USDC on Base Sepolia */
+export const USDC_SEPOLIA_ADDRESS = '0x4eF7a082726B9E4fd136ED58B212F435b7b17594';
+
+/** USDC decimals */
+export const USDC_DECIMALS = 6;
+
+/** Convert human USDC amount (e.g. "1.5") to USDC base units (BigInt) */
+export const parseUsdc = (amount) => parseUnits(String(amount), USDC_DECIMALS);
+/** Convert USDC base units back to human-readable string */
+export const formatUsdc = (amount) => formatUnits(amount, USDC_DECIMALS);
+
+// ─── EIP-712 domain builder ───────────────────────────────────────────────────
+
+/**
+ * Builds the EIP-712 domain object for OpenshardDeposits contract.
+ * @param {string}  contractAddress - deployed OpenshardDeposits address
+ * @param {number}  chainId
+ */
+export function buildDomain(contractAddress, chainId) {
+  return {
+    name: 'OpenShardPayments',
+    version: '1',
+    chainId,
+    verifyingContract: contractAddress
+  };
+}
+
+// ─── Type definitions (viem format) ──────────────────────────────────────────
+
+export const RESERVE_AUTH_TYPES = {
+  ReserveAuth: [
+    { name: 'channelId', type: 'bytes32' },
+    { name: 'buyer', type: 'address' },
+    { name: 'seller', type: 'address' },
+    { name: 'maxAmount', type: 'uint256' },
+    { name: 'deadline', type: 'uint256' }
+  ]
+};
+
+export const SPENDING_AUTH_TYPES = {
+  SpendingAuth: [
+    { name: 'channelId', type: 'bytes32' },
+    { name: 'cumulativeAmount', type: 'uint256' },
+    { name: 'metadataHash', type: 'bytes32' }
+  ]
+};
+
+// ─── Channel ID generation ────────────────────────────────────────────────────
+
+/**
+ * Deterministic channel ID derived from buyer + seller addresses and a nonce.
+ * @param {string} buyerAddress
+ * @param {string} sellerAddress
+ * @param {number} nonce  - monotonically increasing per buyer-seller pair
+ * @returns {`0x${string}`} bytes32 hex
+ */
+export function buildChannelId(buyerAddress, sellerAddress, nonce) {
+  return keccak256(
+    encodeAbiParameters(
+      parseAbiParameters('address buyer, address seller, uint256 nonce'),
+      [buyerAddress, sellerAddress, BigInt(nonce)]
+    )
+  );
+}
+
+// ─── Metadata hash ────────────────────────────────────────────────────────────
+
+/**
+ * Build the metadata hash included in each SpendingAuth.
+ * Captures the token counts and request fingerprint.
+ *
+ * @param {{ inputTokens: number, outputTokens: number, requestId: string }} meta
+ * @returns {`0x${string}`}
+ */
+export function buildMetadataHash({ inputTokens, outputTokens, requestId }) {
+  return keccak256(
+    encodeAbiParameters(
+      parseAbiParameters('uint256 inputTokens, uint256 outputTokens, string requestId'),
+      [BigInt(inputTokens), BigInt(outputTokens), requestId]
+    )
+  );
+}
+
+// ─── Signing (buyer side) ─────────────────────────────────────────────────────
+
+/**
+ * Sign a ReserveAuth message with the buyer's private key.
+ * The seller will submit this signature on-chain to lock buyer funds.
+ *
+ * @param {{ privateKey: string, contractAddress: string, chainId: number }} opts
+ * @param {{ channelId: string, seller: string, maxAmount: bigint, deadline: bigint }} params
+ * @returns {Promise<string>} EIP-712 hex signature
+ */
+export async function signReserveAuth({ privateKey, contractAddress, chainId }, params) {
+  const account = privateKeyToAccount(privateKey);
+  const domain = buildDomain(contractAddress, chainId);
+
+  return account.signTypedData({
+    domain,
+    types: RESERVE_AUTH_TYPES,
+    primaryType: 'ReserveAuth',
+    message: {
+      channelId: params.channelId,
+      buyer: account.address,
+      seller: params.seller,
+      maxAmount: params.maxAmount,
+      deadline: params.deadline
+    }
+  });
+}
+
+/**
+ * Sign a SpendingAuth message.
+ * Called by the buyer after each successful inference request.
+ *
+ * @param {{ privateKey: string, contractAddress: string, chainId: number }} opts
+ * @param {{ channelId: string, cumulativeAmount: bigint, metadataHash: string }} params
+ * @returns {Promise<string>} EIP-712 hex signature
+ */
+export async function signSpendingAuth({ privateKey, contractAddress, chainId }, params) {
+  const account = privateKeyToAccount(privateKey);
+  const domain = buildDomain(contractAddress, chainId);
+
+  return account.signTypedData({
+    domain,
+    types: SPENDING_AUTH_TYPES,
+    primaryType: 'SpendingAuth',
+    message: {
+      channelId: params.channelId,
+      cumulativeAmount: params.cumulativeAmount,
+      metadataHash: params.metadataHash
+    }
+  });
+}
+
+// ─── Verification (seller side) ───────────────────────────────────────────────
+
+/**
+ * Recover the signer address from a ReserveAuth signature.
+ * Seller uses this to verify the buyer's authorization before calling reserve().
+ *
+ * @param {{ contractAddress: string, chainId: number }} opts
+ * @param {{ channelId: string, buyer: string, seller: string, maxAmount: bigint, deadline: bigint }} params
+ * @param {string} signature
+ * @returns {Promise<string>} recovered signer address
+ */
+export async function recoverReserveAuthSigner({ contractAddress, chainId }, params, signature) {
+  return recoverTypedDataAddress({
+    domain: buildDomain(contractAddress, chainId),
+    types: RESERVE_AUTH_TYPES,
+    primaryType: 'ReserveAuth',
+    message: params,
+    signature
+  });
+}
+
+/**
+ * Recover the signer address from a SpendingAuth signature.
+ *
+ * @param {{ contractAddress: string, chainId: number }} opts
+ * @param {{ channelId: string, cumulativeAmount: bigint, metadataHash: string }} params
+ * @param {string} signature
+ * @returns {Promise<string>} recovered signer address
+ */
+export async function recoverSpendingAuthSigner({ contractAddress, chainId }, params, signature) {
+  return recoverTypedDataAddress({
+    domain: buildDomain(contractAddress, chainId),
+    types: SPENDING_AUTH_TYPES,
+    primaryType: 'SpendingAuth',
+    message: params,
+    signature
+  });
+}
+
+// ─── Chain helpers ────────────────────────────────────────────────────────────
+
+export const CHAINS = {
+  'base': base,
+  'base-sepolia': baseSepolia,
+  'localhost': hardhat
+};
+
+export function getChain(name) {
+  const chain = CHAINS[name];
+  if (!chain) throw new Error(`Unknown chain: ${name}. Supported: ${Object.keys(CHAINS).join(', ')}`);
+  return chain;
+}

package/src/prometheus.js

@@ -0,0 +1,169 @@
+/**
+ * openshard_ggshared — prometheus.js
+ *
+ * Minimal Prometheus text format builder.
+ * No external dependencies — just string building.
+ *
+ * Supports: Counter, Gauge, Histogram
+ */
+
+// ─── Metric types ─────────────────────────────────────────────────────────────
+
+class Counter {
+  constructor(name, help, labelNames = []) {
+    this.name       = name;
+    this.help       = help;
+    this.labelNames = labelNames;
+    this._values    = new Map();
+  }
+
+  _key(labels) { return JSON.stringify(labels ?? {}); }
+
+  inc(labels = {}, value = 1) {
+    const k = this._key(labels);
+    this._values.set(k, (this._values.get(k) ?? 0) + value);
+  }
+
+  render() {
+    const lines = [
+      `# HELP ${this.name} ${this.help}`,
+      `# TYPE ${this.name} counter`
+    ];
+    for (const [key, val] of this._values) {
+      const labels = JSON.parse(key);
+      lines.push(`${this.name}${renderLabels(labels)} ${val}`);
+    }
+    return lines.join('\n');
+  }
+}
+
+class Gauge {
+  constructor(name, help, labelNames = []) {
+    this.name       = name;
+    this.help       = help;
+    this.labelNames = labelNames;
+    this._values    = new Map();
+  }
+
+  _key(labels) { return JSON.stringify(labels ?? {}); }
+
+  set(labels = {}, value) {
+    this._values.set(this._key(labels), value);
+  }
+
+  inc(labels = {}, value = 1) {
+    const k = this._key(labels);
+    this._values.set(k, (this._values.get(k) ?? 0) + value);
+  }
+
+  dec(labels = {}, value = 1) {
+    const k = this._key(labels);
+    this._values.set(k, (this._values.get(k) ?? 0) - value);
+  }
+
+  render() {
+    const lines = [
+      `# HELP ${this.name} ${this.help}`,
+      `# TYPE ${this.name} gauge`
+    ];
+    for (const [key, val] of this._values) {
+      const labels = JSON.parse(key);
+      lines.push(`${this.name}${renderLabels(labels)} ${val}`);
+    }
+    return lines.join('\n');
+  }
+}
+
+class Histogram {
+  /**
+   * @param {string}   name
+   * @param {string}   help
+   * @param {number[]} buckets  - upper bounds in ascending order
+   */
+  constructor(name, help, buckets = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]) {
+    this.name       = name;
+    this.help       = help;
+    this.buckets    = [...buckets, Infinity];
+    this.labelNames = [];
+    this._data      = new Map(); // labelKey → { counts[], sum, total }
+  }
+
+  _key(labels) { return JSON.stringify(labels ?? {}); }
+
+  observe(labels = {}, value) {
+    const k = this._key(labels);
+    let d = this._data.get(k);
+    if (!d) {
+      d = { counts: new Array(this.buckets.length).fill(0), sum: 0, total: 0 };
+      this._data.set(k, d);
+    }
+    for (let i = 0; i < this.buckets.length; i++) {
+      if (value <= this.buckets[i]) d.counts[i]++;
+    }
+    d.sum   += value;
+    d.total += 1;
+  }
+
+  render() {
+    const lines = [
+      `# HELP ${this.name} ${this.help}`,
+      `# TYPE ${this.name} histogram`
+    ];
+    for (const [key, d] of this._data) {
+      const labels = JSON.parse(key);
+      const baseLabel = renderLabels(labels);
+      for (let i = 0; i < this.buckets.length; i++) {
+        const le = this.buckets[i] === Infinity ? '+Inf' : String(this.buckets[i]);
+        const bucketLabels = renderLabels({ ...labels, le });
+        lines.push(`${this.name}_bucket${bucketLabels} ${d.counts[i]}`);
+      }
+      lines.push(`${this.name}_sum${baseLabel} ${d.sum}`);
+      lines.push(`${this.name}_count${baseLabel} ${d.total}`);
+    }
+    return lines.join('\n');
+  }
+}
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+export class PrometheusRegistry {
+  constructor() {
+    this._metrics = [];
+  }
+
+  counter(name, help, labelNames = []) {
+    const m = new Counter(name, help, labelNames);
+    this._metrics.push(m);
+    return m;
+  }
+
+  gauge(name, help, labelNames = []) {
+    const m = new Gauge(name, help, labelNames);
+    this._metrics.push(m);
+    return m;
+  }
+
+  histogram(name, help, buckets, labelNames = []) {
+    const m = new Histogram(name, help, buckets);
+    m.labelNames = labelNames;
+    this._metrics.push(m);
+    return m;
+  }
+
+  /**
+   * Render all metrics in Prometheus text format.
+   * @returns {string}
+   */
+  format() {
+    return this._metrics.map(m => m.render()).join('\n\n') + '\n';
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function renderLabels(obj) {
+  const entries = Object.entries(obj);
+  if (entries.length === 0) return '';
+  const inner = entries.map(([k, v]) => `${k}="${String(v).replace(/"/g, '\\"')}"`).join(',');
+  return `{${inner}}`;
+}