joinhive 2.0.1 → 2.2.0

package/shared/x402-client.mjs

@@ -0,0 +1,28 @@
+// shared/x402-client — the paying side of x402, in one function.
+//
+// GET (or POST) a priced resource; on 402, read what the server accepts, sign an
+// EIP-3009 authorization for the cheapest option this payer will accept, and
+// retry with the PAYMENT-SIGNATURE header. Returns the server's response.
+import { parsePaymentRequired, signExactPayment, HEADERS } from './x402.mjs';
+
+// fetchFn(url, {method, headers, body}) -> a Response-like { status, headers:{get(name)}, ... }.
+// signer: an ethers Wallet (the payer). Options:
+//   maxValue     refuse to pay more than this (base units, string/bigint)
+//   chooseFrom   (accepts[]) -> the entry to pay (default: first `exact`)
+//   validForSecs authorization lifetime
+export const payAndFetch = async (fetchFn, url, signer, { method = 'GET', body, headers = {}, maxValue, chooseFrom, validForSecs = 600 } = {}) => {
+  const first = await fetchFn(url, { method, headers, body });
+  if (first.status !== 402) return first; // free, or a non-payment error — pass through
+
+  const reqHeader = first.headers.get(HEADERS.REQUIRED);
+  if (!reqHeader) throw new Error('402 without a PAYMENT-REQUIRED header');
+  const { accepts } = parsePaymentRequired(reqHeader);
+  if (!Array.isArray(accepts) || !accepts.length) throw new Error('402 offered no payment options');
+
+  const pick = (chooseFrom ? chooseFrom(accepts) : accepts.find((a) => a.scheme === 'exact')) || accepts[0];
+  if (!pick) throw new Error('no acceptable payment scheme (need exact)');
+  if (maxValue != null && BigInt(pick.amount) > BigInt(maxValue)) throw new Error(`price ${pick.amount} exceeds maxValue ${maxValue}`);
+
+  const sig = await signExactPayment(signer, pick, { validForSecs });
+  return fetchFn(url, { method, headers: { ...headers, [HEADERS.SIGNATURE]: sig }, body });
+};

package/shared/x402.mjs

@@ -0,0 +1,72 @@
+// shared/x402 — the x402 payment protocol, `exact` scheme, over EIP-3009.
+//
+// x402 turns HTTP 402 into a working payment: a server answers a paid request
+// with `402` + a PAYMENT-REQUIRED header describing what it accepts; the client
+// signs a stablecoin authorization (EIP-3009 transferWithAuthorization — gasless,
+// no prior approval) and retries with a PAYMENT-SIGNATURE header; the server (or
+// a facilitator) verifies and settles it on-chain. Hive uses this for A2A: a bee
+// pays another bee in JELLY (EIP-3009 via JellyV3) or test-USDC to invoke work.
+//
+// This module is the shared codec + the sign/verify half (pure, testable).
+// On-chain settle lives in server/x402-facilitator.mjs.
+import { randomBytes } from 'node:crypto';
+import { verifyTypedData, getAddress } from 'ethers';
+
+const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64');
+const unb64 = (s) => JSON.parse(Buffer.from(String(s), 'base64').toString('utf8'));
+
+export const HEADERS = { REQUIRED: 'payment-required', SIGNATURE: 'payment-signature', RESPONSE: 'payment-response' };
+
+// A fresh 32-byte authorization nonce (any unique bytes32; not sequential).
+export const randomNonce = () => '0x' + randomBytes(32).toString('hex');
+
+// EIP-712 typed-data pieces for the `exact` scheme (EIP-3009 TransferWithAuthorization).
+export const exactTypes = { TransferWithAuthorization: [
+  { name: 'from', type: 'address' }, { name: 'to', type: 'address' }, { name: 'value', type: 'uint256' },
+  { name: 'validAfter', type: 'uint256' }, { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
+] };
+// domain must match the token's EIP-712 domain (JellyV3 = {name:'Jelly',version:'1'}).
+export const exactDomain = ({ asset, chainId, name = 'Jelly', version = '1' }) => ({ name, version, chainId, verifyingContract: getAddress(asset) });
+
+// ---- server: what to accept -------------------------------------------------------
+// accepts[] entries: {scheme:'exact', network, asset, amount, payTo, name?, version?, maxTimeoutSecs?, description?, resource?}
+export const buildPaymentRequired = ({ accepts, error = '' }) => b64({ x402Version: 1, accepts, error });
+export const parsePaymentRequired = (header) => unb64(header);
+
+// ---- client: sign an authorization -> a payment payload ---------------------------
+// signer: an ethers Wallet (or anything with signTypedData). Returns the base64
+// PAYMENT-SIGNATURE header value.
+export const signExactPayment = async (signer, req, { validForSecs = 600, nowSec = Math.floor(Date.now() / 1000) } = {}) => {
+  const from = getAddress(await signer.getAddress());
+  const auth = {
+    from, to: getAddress(req.payTo), value: String(req.amount),
+    validAfter: String(nowSec - 5), validBefore: String(nowSec + validForSecs), nonce: req.nonce || randomNonce(),
+  };
+  const domain = exactDomain(req);
+  const signature = await signer.signTypedData(domain, exactTypes, auth);
+  return b64({ x402Version: 1, scheme: 'exact', network: req.network, asset: req.asset, authorization: auth, signature });
+};
+export const parsePaymentPayload = (header) => unb64(header);
+
+// ---- verify (facilitator/server, off-chain part) ----------------------------------
+// Confirms the signature recovers to `authorization.from`, and that the amount,
+// recipient, and validity window satisfy the requirement. Nonce-unused + payer
+// balance are confirmed ON-CHAIN at settle (this can't see them). -> {valid, from, reason}
+export const verifyExact = (payload, req, { nowSec = Math.floor(Date.now() / 1000) } = {}) => {
+  try {
+    if (!payload || payload.scheme !== 'exact') return { valid: false, reason: 'scheme-mismatch' };
+    const a = payload.authorization || {};
+    if (getAddress(a.to) !== getAddress(req.payTo)) return { valid: false, reason: 'wrong-recipient' };
+    if (BigInt(a.value) < BigInt(req.amount)) return { valid: false, reason: 'underpaid' };
+    if (getAddress(payload.asset) !== getAddress(req.asset)) return { valid: false, reason: 'wrong-asset' };
+    if (nowSec <= Number(a.validAfter)) return { valid: false, reason: 'not-yet-valid' };
+    if (nowSec >= Number(a.validBefore)) return { valid: false, reason: 'expired' };
+    const recovered = verifyTypedData(exactDomain(req), exactTypes, a, payload.signature);
+    if (getAddress(recovered) !== getAddress(a.from)) return { valid: false, reason: 'bad-signature' };
+    return { valid: true, from: getAddress(a.from) };
+  } catch (e) { return { valid: false, reason: `malformed: ${String(e.message).slice(0, 60)}` }; }
+};
+
+// ---- response ---------------------------------------------------------------------
+export const buildPaymentResponse = ({ success, txHash, network, payer }) => b64({ success, txHash, network, payer });
+export const parsePaymentResponse = (header) => unb64(header);