@ironbridgefoundation/gitlawb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IronBridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @ironbridgefoundation/gitlawb
+
+An x402 pay-rail SDK that bounds an agent's spend **below the LLM** and emits a
+**re-verifiable** USDC payment receipt.
+
+It builds the HTTP `402 Payment Required` descriptor for a paid call and a
+matching receipt you can re-check. The payment is a single Base-mainnet USDC
+charge split into two legs:
+
+- **dev leg** → **your own wallet** (you pass it in)
+- **fee leg** → the IronBridge treasury Safe (the cost of using the rail; `450`
+  bps by default, set `feeBps: 0` for a self-hosted / no-fee rail)
+
+## Install
+
+```bash
+npm install @ironbridgefoundation/gitlawb
+```
+
+## Usage
+
+```js
+import { charge } from "@ironbridgefoundation/gitlawb";
+
+// Point the payout at YOUR wallet — never an IronBridge address.
+const gate = charge({
+  price: "0.10",
+  receiver: "0xYourWalletAddressHere0000000000000000000",
+  label: "lookup",
+});
+
+// gate.status === 402
+// gate.body.splits === [
+//   { leg: "dev",            to: "0xYourWallet…", usdc: "0.095500" },
+//   { leg: "ironbridge_fee", to: "0x5Bb0…1680",   usdc: "0.004500", fee_bps: 450 },
+// ]
+```
+
+Verify a receipt is internally consistent (splits sum to price, dev leg pays
+the stated receiver):
+
+```js
+import { verifyReceipt } from "@ironbridgefoundation/gitlawb";
+
+const { ok, reasons } = verifyReceipt(gate);
+// ok === true
+```
+
+Optional dependency-free Express-style gate:
+
+```js
+import { x402Middleware } from "@ironbridgefoundation/gitlawb";
+
+app.get(
+  "/paid-route",
+  x402Middleware({
+    price: "0.10",
+    receiver: "0xYourWallet…",
+    label: "lookup",
+    // verify: async (req) => await yourLaneVerifier(req), // return true once paid
+  }),
+  handler
+);
+```
+
+## What it does
+
+- Computes the exact two-leg USDC split (6-decimal strings) the same way the
+  live GITLAWB lane does: `dev = price * (1 - feeBps/10000)`,
+  `fee = price * feeBps/10000`.
+- Builds the `402` descriptor your server returns to require payment.
+- Verifies receipt **structure and arithmetic** so you can re-check that the
+  math is honest.
+
+## What it does NOT do
+
+- It **holds no private keys** and **custodies no funds**.
+- It makes **no network calls** inside `charge()` — it only builds the
+  descriptor and verifies receipt math.
+- `verifyReceipt()` checks structure/arithmetic only. It does **not** and
+  **cannot** confirm on-chain settlement. To prove a payment actually cleared,
+  re-POST to the live lane with the on-chain tx hash and let the lane verifier
+  read the Base receipt:
+
+  ```
+  POST https://ironbridge.foundation/api/pay/gitlawb/<your-wallet>/<label>
+  X-IB-Payment-Tx: <base-tx-hash>
+  ```
+
+## Constants (exported)
+
+- `USDC_ADDRESS` — Base USDC `0x8335…2913`
+- `IRONBRIDGE_FEE_RECEIVER` — IronBridge treasury Safe `0x5Bb0…1680`
+- `CHAIN_ID` — `8453` (Base mainnet)
+- `DEFAULT_FEE_BPS` — `450`
+
+## License
+
+MIT © 2026 IronBridge — https://ironbridge.foundation

package/index.js

@@ -0,0 +1,316 @@
+/**
+ * @ironbridgefoundation/gitlawb
+ *
+ * x402 pay-rail SDK. It builds the HTTP 402 "Payment Required" descriptor for a
+ * paid agent call and a matching, re-verifiable receipt. The payment is a single
+ * Base-mainnet USDC transfer split into two legs:
+ *
+ *   - dev  leg  -> YOUR own wallet (the `receiver` you pass in)
+ *   - fee  leg  -> the IronBridge treasury Safe (the cost of using the rail)
+ *
+ * This package holds NO private keys, custodies NO funds, and makes NO network
+ * calls inside `charge()`. It only computes the descriptor + verifies receipt
+ * arithmetic. It NEVER defaults the dev leg to an IronBridge address: if you do
+ * not supply `receiver`, `charge()` throws.
+ *
+ * The split math mirrors the live lane verbatim:
+ *   POST https://ironbridge.foundation/api/pay/gitlawb/<wallet>/<label>
+ *     dev = price * (1 - feeBps/10000)
+ *     fee = price * feeBps/10000
+ *   amounts emitted as 6-decimal USDC strings.
+ *
+ * @module @ironbridgefoundation/gitlawb
+ */
+
+'use strict';
+
+/** Base mainnet USDC contract (6 decimals). For reference / integrators. */
+export const USDC_ADDRESS = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+
+/** IronBridge treasury Safe — the fee (rail) leg recipient. Fixed, public, holds no key here. */
+export const IRONBRIDGE_FEE_RECEIVER = '0x5Bb0a8A570F73eE0575043B8A9c33b28D6891680';
+
+/** Base mainnet chain id. */
+export const CHAIN_ID = 8453;
+
+/** Default rail fee in basis points — matches the live GITLAWB lane (450 bps = 4.5%). */
+export const DEFAULT_FEE_BPS = 450;
+
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+
+/**
+ * Convert a USDC amount (string or number) to integer micro-units (6dp).
+ * Avoids float drift by string-parsing the decimal portion.
+ * @param {string|number} price
+ * @returns {bigint} micro-units (price * 1e6)
+ */
+export function toMicros(price) {
+  const s = String(price).trim();
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new Error(`gitlawb: invalid price "${price}" (expected non-negative decimal USDC)`);
+  }
+  const [whole, frac = ''] = s.split('.');
+  if (frac.length > 6) {
+    throw new Error(`gitlawb: price "${price}" has more than 6 decimal places (USDC is 6dp)`);
+  }
+  const fracPadded = (frac + '000000').slice(0, 6);
+  return BigInt(whole) * 1000000n + BigInt(fracPadded || '0');
+}
+
+/**
+ * Format integer micro-units back to a fixed 6-decimal USDC string.
+ * @param {bigint} micros
+ * @returns {string} e.g. "0.095500"
+ */
+export function microsToUsdc(micros) {
+  const neg = micros < 0n;
+  const m = neg ? -micros : micros;
+  const whole = m / 1000000n;
+  const frac = (m % 1000000n).toString().padStart(6, '0');
+  return `${neg ? '-' : ''}${whole.toString()}.${frac}`;
+}
+
+/**
+ * Build the x402 payment-required descriptor for a paid call.
+ *
+ * @param {object} opts
+ * @param {string|number} opts.price   USDC price for the call (e.g. "0.10").
+ * @param {string} opts.receiver       YOUR developer wallet (0x… 40-hex). REQUIRED.
+ *                                      The dev leg is paid here. Never defaults to IronBridge.
+ * @param {string} [opts.label]        Free-form label for the call (notary/audit reference).
+ * @param {number} [opts.feeBps]       Rail fee in bps. Default 450 (matches live lane).
+ *                                      Pass 0 for a self-hosted / no-fee rail.
+ * @returns {{status: number, body: object}} HTTP 402 descriptor with two-leg split.
+ *
+ * @example
+ * import { charge } from '@ironbridgefoundation/gitlawb';
+ * const gate = charge({ price: '0.10', receiver: '0xYourWallet…', label: 'lookup' });
+ * // -> { status: 402, body: { ... splits: [dev, ironbridge_fee] } }
+ */
+export function charge({ price, receiver, label = '', feeBps = DEFAULT_FEE_BPS } = {}) {
+  if (receiver == null || receiver === '') {
+    throw new Error(
+      'gitlawb: `receiver` is required — pass YOUR own wallet address. ' +
+      'This SDK never defaults the dev payout to an IronBridge address.'
+    );
+  }
+  if (typeof receiver !== 'string' || !ADDR_RE.test(receiver)) {
+    throw new Error(`gitlawb: invalid receiver address "${receiver}" (expected 0x + 40 hex)`);
+  }
+  if (receiver.toLowerCase() === IRONBRIDGE_FEE_RECEIVER.toLowerCase()) {
+    throw new Error(
+      'gitlawb: `receiver` must be YOUR wallet, not the IronBridge fee/Safe address.'
+    );
+  }
+  if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 10000) {
+    throw new Error(`gitlawb: invalid feeBps "${feeBps}" (expected integer 0..10000)`);
+  }
+
+  const priceMicros = toMicros(price);
+  const feeMicros = (priceMicros * BigInt(feeBps)) / 10000n;
+  const devMicros = priceMicros - feeMicros;
+
+  const splits = [
+    { leg: 'dev', to: receiver, usdc: microsToUsdc(devMicros) },
+  ];
+  // Only include the fee leg when there is a fee (feeBps:0 == self-hosted/no-fee rail).
+  if (feeMicros > 0n) {
+    splits.push({
+      leg: 'ironbridge_fee',
+      to: IRONBRIDGE_FEE_RECEIVER,
+      usdc: microsToUsdc(feeMicros),
+      fee_bps: feeBps,
+    });
+  }
+
+  return {
+    status: 402,
+    body: {
+      error: 'Payment Required',
+      price_usdc: Number(microsToUsdc(priceMicros)),
+      network: 'base',
+      asset: 'USDC',
+      receiver,
+      label,
+      splits,
+    },
+  };
+}
+
+/**
+ * Re-verify a receipt (or the body of a `charge()` result) is internally
+ * consistent: the split legs sum exactly to the stated price and the dev leg
+ * pays the stated receiver.
+ *
+ * HONEST SCOPE: this checks STRUCTURE and ARITHMETIC only. It does NOT and
+ * CANNOT confirm on-chain settlement — to prove a payment actually cleared,
+ * re-POST to the live lane with the tx hash and let the lane verifier read the
+ * Base receipt. This helper is the "the math/shape is sound" check.
+ *
+ * @param {object} receipt        Either a `charge()` return ({status, body}) or its `body`.
+ * @returns {{ok: boolean, reasons: string[]}}  ok=true if consistent; reasons lists failures.
+ */
+export function verifyReceipt(receipt) {
+  const reasons = [];
+  if (receipt == null || typeof receipt !== 'object') {
+    return { ok: false, reasons: ['receipt is not an object'] };
+  }
+  const body = receipt.body && typeof receipt.body === 'object' ? receipt.body : receipt;
+
+  if (!Array.isArray(body.splits) || body.splits.length === 0) {
+    return { ok: false, reasons: ['receipt has no splits[]'] };
+  }
+  if (body.price_usdc == null) {
+    reasons.push('receipt missing price_usdc');
+  }
+  if (!body.receiver || !ADDR_RE.test(String(body.receiver))) {
+    reasons.push('receipt missing/invalid receiver');
+  }
+
+  let sumMicros = 0n;
+  let devLeg = null;
+  let feeLeg = null;
+  for (const s of body.splits) {
+    if (!s || typeof s.usdc !== 'string' || !s.to) {
+      reasons.push('a split is malformed (needs {leg,to,usdc})');
+      continue;
+    }
+    let m;
+    try {
+      m = toMicros(s.usdc);
+    } catch (e) {
+      reasons.push(`split ${s.leg}: ${e.message}`);
+      continue;
+    }
+    sumMicros += m;
+    if (s.leg === 'dev') devLeg = s;
+    if (s.leg === 'ironbridge_fee') feeLeg = s;
+  }
+
+  if (!devLeg) {
+    reasons.push('no dev leg present');
+  } else if (body.receiver && devLeg.to.toLowerCase() !== String(body.receiver).toLowerCase()) {
+    reasons.push('dev leg recipient does not match receiver');
+  }
+
+  if (feeLeg) {
+    if (feeLeg.to.toLowerCase() !== IRONBRIDGE_FEE_RECEIVER.toLowerCase()) {
+      reasons.push('fee leg recipient is not the IronBridge fee receiver');
+    }
+    if (feeLeg.fee_bps != null) {
+      // cross-check the fee leg amount against its declared bps
+      let priceM;
+      try {
+        priceM = toMicros(body.price_usdc);
+        const expectFee = (priceM * BigInt(feeLeg.fee_bps)) / 10000n;
+        if (toMicros(feeLeg.usdc) !== expectFee) {
+          reasons.push('fee leg amount does not match fee_bps * price');
+        }
+      } catch (e) {
+        reasons.push(`fee_bps cross-check failed: ${e.message}`);
+      }
+    }
+  }
+
+  if (body.price_usdc != null) {
+    let priceMicros;
+    try {
+      priceMicros = toMicros(body.price_usdc);
+      if (sumMicros !== priceMicros) {
+        reasons.push(
+          `splits sum ${microsToUsdc(sumMicros)} != price_usdc ${microsToUsdc(priceMicros)}`
+        );
+      }
+    } catch (e) {
+      reasons.push(`price_usdc parse failed: ${e.message}`);
+    }
+  }
+
+  return { ok: reasons.length === 0, reasons };
+}
+
+/**
+ * Optional dependency-free Express-style middleware that gates a route behind
+ * the x402 descriptor. Until a payment proof is presented it responds 402 with
+ * the descriptor body. It does NOT verify on-chain settlement itself — wire the
+ * `verify` callback to the live lane (or your own verifier) for that.
+ *
+ * @param {object} opts                Same shape as `charge()` opts (price, receiver, label, feeBps).
+ * @param {(req:any)=>(boolean|Promise<boolean>)} [opts.verify]  Optional: return true if paid.
+ * @returns {(req:any,res:any,next:Function)=>void}
+ */
+export function x402Middleware(opts = {}) {
+  const { verify, ...chargeOpts } = opts;
+  return async function gitlawbGate(req, res, next) {
+    try {
+      if (typeof verify === 'function') {
+        const paid = await verify(req);
+        if (paid) return next();
+      }
+      const descriptor = charge(chargeOpts);
+      res.status(descriptor.status).json(descriptor.body);
+    } catch (e) {
+      // Surface config errors loudly rather than silently 402-ing.
+      res.status(500).json({ error: 'gitlawb config error', detail: e.message });
+    }
+  };
+}
+
+export default { charge, verifyReceipt, x402Middleware, toMicros, microsToUsdc };
+
+/* --------------------------------------------------------------------------
+ * Inline self-test:  node index.js --self-test
+ * Proves the split math and receipt verifier against the live-lane numbers.
+ * No network, no keys, exits 0 on PASS / 1 on FAIL.
+ * ------------------------------------------------------------------------ */
+if (import.meta.url === `file://${process.argv[1]}` && process.argv.includes('--self-test')) {
+  let failures = 0;
+  const assert = (cond, msg) => {
+    if (!cond) { failures++; console.error('FAIL:', msg); }
+    else { console.log('ok  :', msg); }
+  };
+
+  const DEV = '0x000000000000000000000000000000000000dEaD';
+
+  // 1) live-lane numbers: 0.10 USDC, 450 bps -> dev 0.095500, fee 0.004500
+  const r = charge({ price: '0.10', receiver: DEV, label: 'lookup' });
+  assert(r.status === 402, 'charge() returns status 402');
+  const dev = r.body.splits.find(s => s.leg === 'dev');
+  const fee = r.body.splits.find(s => s.leg === 'ironbridge_fee');
+  assert(dev && dev.usdc === '0.095500', `dev leg = 0.095500 (got ${dev && dev.usdc})`);
+  assert(fee && fee.usdc === '0.004500', `fee leg = 0.004500 (got ${fee && fee.usdc})`);
+  assert(fee && fee.to === IRONBRIDGE_FEE_RECEIVER, 'fee leg pays IronBridge Safe');
+  assert(dev && dev.to === DEV, 'dev leg pays the supplied receiver');
+  assert(fee && fee.fee_bps === 450, 'fee leg carries fee_bps 450');
+  const sum = toMicros(dev.usdc) + toMicros(fee.usdc);
+  assert(sum === 100000n, `legs sum to 0.100000 (got ${microsToUsdc(sum)})`);
+
+  // 2) verifyReceipt accepts the honest receipt
+  const v = verifyReceipt(r);
+  assert(v.ok === true, `verifyReceipt accepts honest receipt (reasons: ${v.reasons.join('; ')})`);
+
+  // 3) verifyReceipt rejects a tampered receipt (dev leg inflated)
+  const tampered = JSON.parse(JSON.stringify(r));
+  tampered.body.splits.find(s => s.leg === 'dev').usdc = '0.099999';
+  const vt = verifyReceipt(tampered);
+  assert(vt.ok === false, 'verifyReceipt rejects tampered (inflated dev) receipt');
+
+  // 4) receiver is required — never defaults to IronBridge
+  let threw = false;
+  try { charge({ price: '0.10' }); } catch (_) { threw = true; }
+  assert(threw, 'charge() throws when receiver is missing (no IronBridge default)');
+
+  // 5) feeBps:0 -> single dev leg, no fee leg
+  const noFee = charge({ price: '0.10', receiver: DEV, feeBps: 0 });
+  assert(noFee.body.splits.length === 1 && noFee.body.splits[0].leg === 'dev',
+    'feeBps:0 yields a single dev leg (self-hosted/no-fee)');
+  assert(verifyReceipt(noFee).ok === true, 'verifyReceipt accepts no-fee receipt');
+
+  // 6) refuse receiver == fee Safe
+  let threw2 = false;
+  try { charge({ price: '0.10', receiver: IRONBRIDGE_FEE_RECEIVER }); } catch (_) { threw2 = true; }
+  assert(threw2, 'charge() refuses receiver == IronBridge fee Safe');
+
+  console.log(failures === 0 ? '\nSELF-TEST PASS' : `\nSELF-TEST FAIL (${failures})`);
+  process.exit(failures === 0 ? 0 : 1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ironbridgefoundation/gitlawb",
+  "version": "0.1.0",
+  "description": "x402 pay-rail SDK that bounds an agent's spend below the LLM and emits a re-verifiable USDC payment receipt.",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node index.js --self-test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "IronBridge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ironbridge-foundation/ironbridge-gitlawb.git"
+  },
+  "homepage": "https://ironbridge.foundation",
+  "keywords": [
+    "x402",
+    "payments",
+    "usdc",
+    "base",
+    "agent",
+    "pay-rail",
+    "receipt",
+    "gitlawb",
+    "ironbridge"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}