From 934504c96d016642dc47290972d4eee1f56aa312 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20H=C3=B8iby?= Date: Thu, 4 Jun 2026 09:59:38 +0200 Subject: [PATCH] docs: add README + Open BSV LICENSE Add a clean OSS-facing README documenting the Margin orchestrator (canonical AIP via WAB two-phase signing), its endpoints, development workflow, and configuration. Add the canonical Open BSV License (this repo does on-chain AIP signing = blockchain code) and align the package.json license field accordingly. Co-Authored-By: Claude Opus 4.8 (1M context) --- LICENSE | 26 +++++++++++++++++++++++ README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- 3 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3ceeb50 --- /dev/null +++ b/LICENSE @@ -0,0 +1,26 @@ +Open BSV License + +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: + +1. This permission notice shall be included in all copies or substantial + portions of the Software. + +2. The Software, and any software that is derived from the Software or parts + thereof, can only be used on the Bitcoin SV blockchains. The Bitcoin SV + blockchains are defined, for purposes of this license, as the Bitcoin + blockchain containing block height #556767 with hash + 000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b and the + test blockchains that are compatible with it. + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7927660 --- /dev/null +++ b/README.md @@ -0,0 +1,58 @@ +# margin-api + +[![CI](https://github.com/kryp2/margin-api/actions/workflows/ci.yml/badge.svg)](https://github.com/kryp2/margin-api/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/license-Open%20BSV-blue.svg)](LICENSE) + +Orchestrator service for the Margin browser extension. It canonicalizes a target URL, builds a Bitcoin Schema draft, and produces a canonical AIP-signed `OP_RETURN` by coordinating two-phase signing with the Wallet Authentication Backend (WAB), then broadcasts the resulting transaction through an overlay service using a sponsor wallet. + +## How it works + +A single `POST /post` request drives the full pipeline: + +1. Canonicalize the submitted URL into a stable context URN. +2. Resolve the user's signing identity from WAB (`/auth/margin/identity`) — no signing yet. +3. Assemble the canonical AIP preimage (B + MAP + AIP header) with the resolved pubkey. +4. Send the preimage to WAB (`/auth/margin/sign`) for a `sha256`/DER signature (BRC-77 lane). +5. Append the signature to finalize the `OP_RETURN` script. +6. Build the transaction with the sponsor wallet and submit it to the overlay. + +This two-phase split is required because the canonical AIP preimage must include the signing identity before the signature is computed. + +## Endpoints + +- `GET /health` — liveness plus sponsor-wallet status (address, balance, readiness). +- `POST /post` — body `{ url, comment, id_token }`; returns `{ txid, script_hex, context_urn, signing_address, signing_pubkey, app }`. Rate-limited and capped at a 500-character comment (free tier). + +## Development + +```bash +npm install # install dependencies +npm run dev # run locally with ts-node-dev (auto-reload) +npm run build # compile TypeScript to dist/ +npm test # run the Jest test suite +npm run lint # type-check only (tsc --noEmit) +``` + +## Configuration + +All configuration comes from environment variables (see `src/config.ts`): + +| Variable | Default | Description | +| --- | --- | --- | +| `PORT` | `8080` | HTTP listen port | +| `BSV_NETWORK` | `main` | `main` or `test` | +| `WAB_BASE_URL` | `https://wab.peck.to` | Wallet Authentication Backend | +| `OVERLAY_BASE_URL` | `https://overlay.peck.to` | Overlay service base URL | +| `OVERLAY_TOPIC` | `peck-schema` | Overlay topic to submit to | +| `MARGIN_APP_NAME` | `margin` | App name written into the MAP record | +| `CORS_ORIGINS` | `*` | Comma-separated allowed origins, or `*` | + +The sponsor wallet is configured via the `SPONSOR_PRIVATE_KEY_HEX`, `SPONSOR_INITIAL_UTXO`, and `SPONSOR_PARENT_TX_HEX` secrets. + +## Deployment + +A `Dockerfile` (multi-stage Node 20 build) and `cloudbuild.yaml` are provided for building and deploying to Cloud Run. + +## License + +[Open BSV License](LICENSE). diff --git a/package.json b/package.json index be304d7..3800be8 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "margin-api", "version": "0.1.0", "description": "Margin orchestrator: canonicalize URL → build draft → sign via WAB → assemble OP_RETURN", - "license": "MIT", + "license": "Open BSV", "main": "dist/index.js", "scripts": { "build": "tsc -p tsconfig.json",