Merge pull request #27 from Permissionless-Software-Foundation/ct-unstable

fix(full node): Debugging config settings

.env-example

@@ -0,0 +1,44 @@
+# START INFRASTRUCTURE SETUP
+
+# Full Node Connection
+RPC_BASEURL=http://172.17.0.1:8332
+RPC_USERNAME=bitcoin
+RPC_PASSWORD=password
+
+# Fulcrum Indexer
+FULCRUM_API=http://172.17.0.1:3001/v1
+
+# SLP Indexer
+SLP_INDEXER_API=http://localhost:5010
+
+# REST API URL for wallet operations
+LOCAL_RESTURL=http://localhost:5942/v6
+
+# END INFRASTRUCTURE SETUP
+
+# Public base URL for apiDoc HTML (optional; used by Docker entrypoint before `npm run docs`).
+#APIDOC_URL=https://api.example.com
+
+
+# START ACCESS CONTROL
+
+PORT=5942
+
+# x402 payments required to access this API?
+X402_ENABLED=true
+# Also gates discovery endpoints:
+# /.well-known/x402, /openapi.json, /swagger.json, /llms.txt, /.well-known/agent.json
+SERVER_BCH_ADDRESS=bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d
+FACILITATOR_URL=http://localhost:4345/facilitator
+X402_PRICE_SAT=200
+
+# Basic Authentication required to access this API?
+USE_BASIC_AUTH=true
+BASIC_AUTH_TOKEN=some-random-token
+
+# END ACCESS CONTROL
+
+# PSF token liquidity price proxy (GET /v6/price/psf). Off by default.
+#PSF_LIQUIDITY_PROXY_ENABLED=true
+#PSF_LIQUIDITY_URL=http://192.168.0.126:5000
+

.env-local

@@ -1,13 +0,0 @@
-# Full Node Connection
-RPC_BASEURL=http://172.17.0.1:8332
-RPC_USERNAME=bitcoin
-RPC_PASSWORD=password
-
-# x402 payments required to access this API?
-X402_ENABLED=false
-
-# Fulcrum Indexer
-FULCRUM_API=http://192.168.2.127:3001
-
-# SLP Indexer
-SLP_INDEXER_API=http://192.168.2.127:5010

README.md

@@ -1,30 +1,265 @@
 # psf-bch-api
 
-This is a REST API for communicating with Bitcoin Cash infrastructure. It replaces [bch-api](https://github.com/Permissionless-Software-Foundation/bch-api), and it implements [x402-bch protocol](https://github.com/x402-bch/x402-bch) to handle payments to access the API.
+[![License](https://img.shields.io/npm/l/@psf/bch-js)](https://github.com/Permissionless-Software-Foundation/psf-bch-api/blob/master/LICENSE.md)
+[![js-standard-style](https://img.shields.io/badge/javascript-standard%20code%20style-green.svg?style=flat-square)](https://github.com/feross/standard)
+
+This is a REST API server for communicating with Bitcoin Cash (BCH) blockchain infrastructure. It is written in node.js JavaScript using the [Express.js](https://expressjs.com/) framework and follows the [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) design pattern. It replaces the legacy [bch-api](https://github.com/Permissionless-Software-Foundation/bch-api) and implements the [x402-bch protocol](https://github.com/x402-bch/x402-bch) for optional per-call payments.
+
+psf-bch-api is the heart of the [Cash Stack](https://cashstack.info), a full software stack for building blockchain-based applications. It creates a single web2 REST API interface that abstracts away the complexity of the underlying blockchain infrastructure, so that application developers can interact with the blockchain through simple HTTP calls.
+
+![psf-bch-api software stack](./bch-api-dependency-graph.png)
+
+psf-bch-api depends on three pieces of back end infrastructure:
+
+- **[BCHN Full Node](https://cashstack.info/docs/back-end/bchn-full-node)** - the base blockchain node that validates transactions and blocks.
+- **[Fulcrum Indexer](https://cashstack.info/docs/back-end/fulcrum-indexer)** - an address indexer that tracks balances, transaction histories, and UTXOs.
+- **[SLP Token Indexer](https://cashstack.info/docs/back-end/slp-indexer/slp-indexer-software)** - tracks all SLP tokens on the blockchain.
+
+Front-end applications interact with psf-bch-api through libraries such as [bch-js](https://github.com/Permissionless-Software-Foundation/bch-js) or [bch-consumer](https://www.npmjs.com/package/bch-consumer).
+
+High-level documentation about the full Cash Stack is available at [CashStack.info](https://cashstack.info). Interactive API reference documentation is served by the running server at its root URL (e.g. `http://localhost:5942/`), and a live version can be found at [bch.fullstack.cash](https://bch.fullstack.cash/).
+
+## The .env File
+
+All runtime configuration is driven by a `.env` file in the project root. An example is provided at `.env-example`. To get started:
+
+`cp .env-example .env`
+
+Then edit `.env` to match your environment. The file is organized into two sections:
+
+### Infrastructure Setup
+
+These variables tell psf-bch-api where to find the back end services it depends on:
+
+- `RPC_BASEURL` - URL of the BCHN full node JSON-RPC interface. Default: `http://127.0.0.1:8332`
+- `RPC_USERNAME` - RPC username for the full node.
+- `RPC_PASSWORD` - RPC password for the full node.
+- `FULCRUM_API` - URL of the Fulcrum indexer REST API.
+- `SLP_INDEXER_API` - URL of the SLP Token Indexer REST API.
+- `LOCAL_RESTURL` - The REST API URL used internally for wallet operations. Default: `http://127.0.0.1:5942/v6/`
+
+### Access Control Settings
+
+These variables control who can access the API and how they pay for it. The three access-control use cases are described in detail in the [Access Control](#access-control) section below.
+
+- `PORT` - Port the server listens on. Default: `5942`
+- `X402_ENABLED` - Enable x402-bch per-call payment middleware. Default: `true`
+- `SERVER_BCH_ADDRESS` - BCH address that receives x402 payments. Default: `bitcoincash:qqsrke9lh257tqen99dkyy2emh4uty0vky9y0z0lsr`
+- `FACILITATOR_URL` - URL of the x402-bch facilitator service. Default: `http://localhost:4345/facilitator`
+- `X402_PRICE_SAT` - Price in satoshis charged per API call via x402. Default: `200`
+- `USE_BASIC_AUTH` - Enable Bearer token authentication middleware. Default: `false`
+- `BASIC_AUTH_TOKEN` - The expected Bearer token value.
+
+## Access Control
+
+psf-bch-api supports three major access-control configurations. Which one you choose depends on your deployment scenario. The behavior is controlled entirely by the `X402_ENABLED` and `USE_BASIC_AUTH` environment variables.
+
+### 1. No Rate Limits (Open Access)
+
+Set both access-control flags to `false`:
+
+```
+X402_ENABLED=false
+USE_BASIC_AUTH=false
+```
+
+All API endpoints are publicly accessible without any authentication or payment. This is the simplest configuration, ideal for **local development** or **private, trusted networks** where access control is handled at the network level (e.g. behind a firewall or VPN).
+
+### 2. Bearer Token Authentication
+
+Set `USE_BASIC_AUTH=true` and `X402_ENABLED=false`:
+
+```
+X402_ENABLED=false
+USE_BASIC_AUTH=true
+BASIC_AUTH_TOKEN=my-secret-token
+```
+
+Every API request (except `/health` and `/`) must include an `Authorization` header with a valid Bearer token:
+
+```
+Authorization: Bearer my-secret-token
+```
+
+Requests without a valid token receive an HTTP `401 Unauthorized` response. This is the best option when you want to **restrict access to a known set of users or services** (e.g. an organization's internal apps) without requiring cryptocurrency payments.
+
+### 3. x402-bch Per-Call Payments
+
+Set `X402_ENABLED=true`:
+
+```
+X402_ENABLED=true
+SERVER_BCH_ADDRESS=bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d
+FACILITATOR_URL=http://localhost:4345/facilitator
+X402_PRICE_SAT=200
+```
+
+Every API call under the `/v6` prefix requires a BCH micro-payment. When a request arrives without a valid `X-PAYMENT` header, the server responds with HTTP `402 Payment Required` and includes the payment details. Client libraries that support the x402-bch protocol (like [bch-js](https://github.com/Permissionless-Software-Foundation/bch-js)) can handle payments automatically.
+
+This is the right choice for **public, monetized APIs** where you want to charge per call.
+
+When `X402_ENABLED=true`, the server also exposes machine-discovery endpoints:
+
+- `/.well-known/x402` - x402-bch v2 payment discovery manifest
+- `/openapi.json` - OpenAPI 3 projection generated from apiDoc annotations
+- `/swagger.json` - Swagger 2.0 compatibility projection
+- `/llms.txt` - LLM-oriented markdown index of service metadata
+- `/.well-known/agent.json` - draft agent manifest describing API actions
+
+When `X402_ENABLED=false`, these discovery endpoints return `404`.
+
+#### Combined: x402 + Bearer Token
+
+You can enable both at the same time:
+
+```
+X402_ENABLED=true
+USE_BASIC_AUTH=true
+BASIC_AUTH_TOKEN=my-secret-token
+```
+
+In this mode, requests that present a valid Bearer token bypass the x402 payment requirement. All other requests must pay. This allows you to give **free access to trusted clients** (via the Bearer token) while still **monetizing public access** via x402.
+
+## Development
+
+This is a standard node.js project. To set up a development environment:
+
+1. Clone the repository:
+
+`git clone https://github.com/Permissionless-Software-Foundation/psf-bch-api && cd psf-bch-api`
+
+2. Install dependencies:
+
+`npm install`
+
+3. Create your configuration file:
+
+`cp .env-example .env`
+
+4. Edit `.env` to point to your back end infrastructure (full node, Fulcrum, SLP indexer). For local development you will likely want to disable access control:
+
+```
+X402_ENABLED=false
+USE_BASIC_AUTH=false
+```
+
+5. Start the server:
+
+`npm start`
+
+The server will start on port `5942` by default (or whatever you set in `PORT`). API documentation is available at `http://localhost:5942/`.
+
+### Generating API Docs
+
+The API reference documentation is generated by [apiDoc](https://apidocjs.com/) from inline annotations in the source code. To regenerate:
+
+`npm run docs`
+
+The output is written to the `docs/` directory and served by the running server at its root URL.
+
+To regenerate API docs plus discovery artifacts (`openapi.json`, `swagger.json`, `llms.txt`, and `agent.json` payload source):
+
+`npm run docs:all`
+
+This runs apiDoc first, then generates `docs/discovery-artifacts.json` from the same annotation source.
+
+A live version can be found at [bch.fullstack.cash](https://bch.fullstack.cash/).
+
+## Production (Docker)
+
+A Docker setup is provided in the `production/docker/` directory for production deployments. The target OS is Ubuntu Linux.
+
+1. Install [Docker and Docker Compose](https://docs.docker.com/engine/install/ubuntu/).
+
+2. Navigate to the Docker directory:
+
+`cd production/docker`
+
+3. Create and configure the `.env` file. An example is provided:
+
+`cp .env-example .env`
+
+Edit `.env` to match your production infrastructure. Note that inside a Docker container, `localhost` refers to the container itself. Use `172.17.0.1` (the default Docker bridge gateway) to reach services running on the host machine:
+
+```
+RPC_BASEURL=http://172.17.0.1:8332
+FULCRUM_API=http://172.17.0.1:3001/v1
+SLP_INDEXER_API=http://172.17.0.1:5010
+```
+
+Set `APIDOC_URL` to the public base URL for your deployment (for example `https://api.example.com` or your subdomain). The container entrypoint applies this value to `apidoc.json` and the `apidoc` section of `package.json`, then runs `npm run docs` before starting the server so generated HTML matches each instance. The compose file mounts `./.env` to `/home/safeuser/psf-bch-api/.env` so it matches `dotenv.config()` in the app.
+
+4. Build the Docker image:
+
+`docker-compose build --no-cache`
+
+5. Start the container:
+
+`docker-compose up -d`
+
+The container maps host port `5942` to container port `5942`. The `.env` file is mounted into the container as a volume, so you can update configuration without rebuilding.
+
+To view logs:
+
+`docker logs -f psf-bch-api`
+
+To stop the container:
+
+`docker-compose down`
+
+A helper script `cleanup-images.sh` is provided to remove dangling Docker images after rebuilds.
+
+## Testing
+
+The project includes both unit tests and integration tests. Tests use [Mocha](https://mochajs.org/) as the test runner, [Chai](https://www.chaijs.com/) for assertions, and [Sinon](https://sinonjs.org/) for mocking. Code coverage is provided by [c8](https://github.com/bcoe/c8).
+
+### Unit Tests
+
+Unit tests are located in `test/unit/` and cover adapters, controllers, and use cases. They do not require any running infrastructure. To run:
+
+`npm test`
+
+This will first lint the code with [Standard](https://standardjs.com/), then execute all unit tests with code coverage.
+
+To generate an HTML coverage report:
+
+`npm run coverage`
+
+The report is written to the `coverage/` directory.
+
+### Integration Tests
+
+Integration tests are located in `test/integration/` and require the back end infrastructure (full node, Fulcrum, SLP indexer) to be running. To run:
+
+`npm run test:integration`
+
+Integration tests have a 25-second timeout per test to accommodate network calls.
+
+## Configuration Reference
+
+All configuration values are read from environment variables (via the `.env` file). The complete list:
+
+- `PORT` - Server listen port. Default: `5942`
+- `NODE_ENV` - Environment (`development` or `production`). Default: `development`
+- `API_PREFIX` - URL prefix for all REST endpoints. Default: `/v6`
+- `LOG_LEVEL` - Winston logging level. Default: `info`
+- `RPC_BASEURL` - Full node JSON-RPC URL. Default: `http://127.0.0.1:8332`
+- `RPC_USERNAME` - Full node RPC username.
+- `RPC_PASSWORD` - Full node RPC password.
+- `RPC_TIMEOUT_MS` - Full node RPC request timeout in ms. Default: `15000`
+- `FULCRUM_API` - Fulcrum indexer REST API URL.
+- `FULCRUM_TIMEOUT_MS` - Fulcrum API request timeout in ms. Default: `15000`
+- `SLP_INDEXER_API` - SLP Token Indexer REST API URL.
+- `SLP_INDEXER_TIMEOUT_MS` - SLP Indexer API request timeout in ms. Default: `15000`
+- `LOCAL_RESTURL` - Internal REST URL for wallet operations. Default: `http://127.0.0.1:5942/v6/`
+- `IPFS_GATEWAY` - IPFS gateway hostname. Default: `p2wdb-gateway-678.fullstack.cash`
+- `X402_ENABLED` - Enable x402-bch payment middleware. Default: `true`
+- `SERVER_BCH_ADDRESS` - BCH address for x402 payments. Default: `bitcoincash:qqsrke9lh257tqen99dkyy2emh4uty0vky9y0z0lsr`
+- `FACILITATOR_URL` - x402-bch facilitator service URL. Default: `http://localhost:4345/facilitator`
+- `X402_PRICE_SAT` - Satoshis charged per API call via x402. Default: `200`
+- `USE_BASIC_AUTH` - Enable Bearer token authentication. Default: `false`
+- `BASIC_AUTH_TOKEN` - Expected Bearer token value.
 
 ## License
 
 [MIT](./LICENSE.md)
-
-## x402-bch Payments
-
-All REST endpoints exposed under the `/v6` prefix are protected by the [`x402-bch-express`](https://www.npmjs.com/package/x402-bch-express) middleware. Each API call requires a BCH payment authorization for **2000 satoshis**. The middleware advertises payment requirements via HTTP 402 responses and validates incoming `X-PAYMENT` headers with a configured Facilitator.
-
-### Configuration
-
-Environment variables control the payment flow:
-
-- `X402_ENABLED` — set to `false` (case-insensitive) to disable the middleware. Defaults to enabled.
-- `SERVER_BCH_ADDRESS` — BCH cash address that receives funding transactions. Defaults to `bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d`.
-- `FACILITATOR_URL` — Root URL of the facilitator service (e.g., `http://localhost:4345/facilitator`).
-- `X402_PRICE_SAT` — Optional; override the satoshi price per call (defaults to `2000`).
-
-When `X402_ENABLED=false`, the server continues to operate without payment headers for local development or trusted deployments.
-
-### Manual Verification
-
-1. Start or point to an `x402-bch` facilitator service (the example facilitator listens at `http://localhost:4345/facilitator`).
-2. Run the API server with the default configuration: `npm start`.
-3. Call a protected endpoint without an `X-PAYMENT` header, e.g. `curl -i http://localhost:5942/v6/full-node/control/getNetworkInfo`. The server will respond with HTTP `402` and include payment requirements.
-4. Restart the server with `X402_ENABLED=false npm start` to confirm that the same request now bypasses the middleware (useful for local development without payments).
-

bin/server.js

@@ -15,7 +15,9 @@ import { dirname, join } from 'path'
 import config from '../src/config/index.js'
 import Controllers from '../src/controllers/index.js'
 import wlogger from '../src/adapters/wlogger.js'
-import { buildX402Routes, getX402Settings } from '../src/config/x402.js'
+import { buildX402Routes, getX402Settings, getBasicAuthSettings } from '../src/config/x402.js'
+import { basicAuthMiddleware } from '../src/middleware/basic-auth.js'
+import DiscoveryRouter from '../src/controllers/discovery/router.js'
 
 // Load environment variables
 dotenv.config()
@@ -58,8 +60,10 @@ class Server {
     try {
       // Create an Express instance.
       const app = express()
+      app.set('trust proxy', true)
 
       const x402Settings = getX402Settings()
+      const basicAuthSettings = getBasicAuthSettings()
 
       // MIDDLEWARE START
       app.use(express.json())
@@ -72,28 +76,107 @@ class Server {
         allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With']
       }))
 
-      // Wrap all endpoints in x402 middleware. This handles payments for the API calls.
+      // URL normalization middleware - collapse multiple slashes
-      if (x402Settings.enabled) {
+      app.use((req, res, next) => {
+        if (req.url && req.url.includes('//')) {
+          // Split URL into path and query string
+          const [path, queryString] = req.url.split('?')
+          // Collapse multiple consecutive slashes into a single slash
+          const normalizedPath = path.replace(/\/+/g, '/')
+          // Reconstruct req.url with normalized path (req.path is read-only and will auto-update)
+          req.url = queryString ? `${normalizedPath}?${queryString}` : normalizedPath
+        }
+        next()
+      })
+
+      // Apply basic auth middleware if enabled
+      // This must run before x402 middleware to set req.locals.basicAuthValid
+      if (basicAuthSettings.enabled) {
+        wlogger.info('Basic auth middleware enabled')
+        app.use(basicAuthMiddleware)
+      }
+
+      // Apply x402 middleware based on configuration
+      // Logic:
+      // - If X402_ENABLED=true AND USE_BASIC_AUTH=true: Apply x402 conditionally (bypass if basic auth valid)
+      // - If X402_ENABLED=true AND USE_BASIC_AUTH=false: Apply x402 unconditionally (no basic auth bypass)
+      // - If X402_ENABLED=false AND USE_BASIC_AUTH=true: Require basic auth only
+      // - If X402_ENABLED=false AND USE_BASIC_AUTH=false: No access control
+
+      // Apply access control middleware based on configuration
+      if (x402Settings.enabled && basicAuthSettings.enabled) {
+        // X402_ENABLED=true AND USE_BASIC_AUTH=true: Apply x402 conditionally
         const routes = buildX402Routes(this.config.apiPrefix)
         const facilitatorOptions = x402Settings.facilitatorUrl
           ? { url: x402Settings.facilitatorUrl }
           : undefined
 
-        wlogger.info(`x402 middleware enabled; enforcing ${x402Settings.priceSat} satoshis per request`)
+        wlogger.info(`x402 middleware enabled with basic auth bypass; enforcing ${x402Settings.priceSat} satoshis per request (unless basic auth provided)`)
-        app.use(
+
-          x402PaymentMiddleware(
+        // Create conditional x402 middleware that bypasses if basic auth is valid
+        const conditionalX402Middleware = (req, res, next) => {
+          // If basic auth is valid, bypass x402
+          if (req.locals?.basicAuthValid === true) {
+            return next()
+          }
+
+          // Otherwise, apply x402 middleware
+          return x402PaymentMiddleware(
             x402Settings.serverAddress,
             routes,
             facilitatorOptions
-          )
+          )(req, res, next)
-        )
+        }
+
+        app.use(conditionalX402Middleware)
+      } else if (x402Settings.enabled && !basicAuthSettings.enabled) {
+        // X402_ENABLED=true AND USE_BASIC_AUTH=false: Apply x402 unconditionally (no basic auth bypass)
+        const routes = buildX402Routes(this.config.apiPrefix)
+        const facilitatorOptions = x402Settings.facilitatorUrl
+          ? { url: x402Settings.facilitatorUrl }
+          : undefined
+
+        wlogger.info(`x402 middleware enabled (basic auth disabled); enforcing ${x402Settings.priceSat} satoshis per request`)
+
+        // Apply x402 middleware unconditionally - no basic auth bypass
+        app.use(x402PaymentMiddleware(
+          x402Settings.serverAddress,
+          routes,
+          facilitatorOptions
+        ))
+      } else if (basicAuthSettings.enabled && !x402Settings.enabled) {
+        // USE_BASIC_AUTH=true AND X402_ENABLED=false: Require basic auth, reject unauthenticated requests
+        wlogger.info('Basic auth enforcement enabled (x402 disabled)')
+
+        // Middleware that rejects requests without valid basic auth
+        const requireBasicAuthMiddleware = (req, res, next) => {
+          // Skip auth check for health endpoint and root
+          if (req.path === '/health' || req.path === '/') {
+            return next()
+          }
+
+          // If basic auth is valid, allow the request
+          if (req.locals?.basicAuthValid === true) {
+            return next()
+          }
+
+          // Reject unauthenticated requests
+          wlogger.warn(`Unauthenticated request rejected: ${req.method} ${req.path}`)
+          return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Valid Bearer token required in Authorization header'
+          })
+        }
+
+        app.use(requireBasicAuthMiddleware)
       } else {
-        wlogger.info('x402 middleware disabled via configuration')
+        // X402_ENABLED=false AND USE_BASIC_AUTH=false: No access control middleware
+        wlogger.info('No access control middleware enabled')
       }
 
       // Endpoint logging middleware
       app.use((req, res, next) => {
-        console.log(`Endpoint called: ${req.method} ${req.path}`)
+        console.log(`Endpoint called: ${req.method} ${req.path} by ${req.ip}`)
         res.on('finish', () => {
           console.log(`Endpoint responded: ${req.method} ${req.path} - ${res.statusCode}`)
         })
@@ -102,7 +185,10 @@ class Server {
 
       // Request logging middleware
       app.use((req, res, next) => {
-        wlogger.info(`${req.method} ${req.path}`)
+        wlogger.info(`${req.method} ${req.path}`, {
+          client_ip: req.ip,
+          remote_address: req.socket?.remoteAddress || null
+        })
         next()
       })
 
@@ -131,6 +217,8 @@ class Server {
 
       // Attach REST API controllers to the app.
       this.controllers.attachRESTControllers(app)
+      const discoveryRouter = new DiscoveryRouter()
+      discoveryRouter.attach(app)
 
       // Initialize any other controller libraries.
       this.controllers.initControllers()
@@ -165,6 +253,11 @@ class Server {
         wlogger.info(`Server started on port ${this.config.port}`)
       })
 
+      // Explicit timeout settings reduce stale keep-alive socket reuse races.
+      this.server.keepAliveTimeout = this.config.serverKeepAliveTimeoutMs
+      this.server.headersTimeout = this.config.serverHeadersTimeoutMs
+      this.server.requestTimeout = this.config.serverRequestTimeoutMs
+
       this.server.on('error', (err) => {
         console.error('Server error:', err)
         wlogger.error('Server error:', err)

dev-docs/update-logs/2026-03-16.md

@@ -0,0 +1,21 @@
+# 2026-03-16 Update Log
+
+## Summary
+
+Reduced noisy error logging for common SLP transaction misses in the `/v6/slp/txid` path.
+
+## Changes Made
+
+- Updated `src/use-cases/slp-use-cases.js` in `getTxid()`:
+  - Added a guard for expected missing-record errors (`404` + `Key not found in database`).
+  - Skips `wlogger.error()` for that specific, common case.
+  - Still rethrows the error so API response behavior is unchanged.
+- Updated `src/controllers/rest-api/slp/controller.js` in `handleError()`:
+  - Added the same guard to suppress duplicate error-level logs for the same expected case.
+  - Keeps normal error logging for all other errors.
+
+## Outcome
+
+- The common "Key not found in database" case no longer pollutes error logs.
+- Unexpected failures continue to be logged at error level.
+- Client-facing status and error message behavior remains unchanged.

dev-docs/update-logs/2026-03-17.md

@@ -0,0 +1,76 @@
+# 2026-03-17 Update Log
+
+## Summary
+
+Enhanced REST request logging to capture client network identity in Winston logs, enabled proxy-aware IP resolution, and reduced Fulcrum error-log noise for expected missing-transaction requests.
+
+## Changes Made
+
+- Updated `bin/server.js`:
+  - Set Express proxy handling with `app.set('trust proxy', true)`.
+  - Kept the current Winston request message format (`"${req.method} ${req.path}"`).
+  - Added structured Winston metadata fields to request logs:
+    - `client_ip` from `req.ip`
+    - `remote_address` from `req.socket.remoteAddress`
+- Updated `src/adapters/fulcrum-api.js`:
+  - Added parsing helpers to normalize Fulcrum error messages from multiple response shapes.
+  - Mapped common daemon missing-TX error (`No such mempool or blockchain transaction`) to:
+    - status `404`
+    - message `Transaction not found`
+- Updated `src/use-cases/fulcrum-use-cases.js`:
+  - Removed duplicate error logging in `getTransactionDetails()` and now rethrows adapter errors without a second error-level log.
+- Updated `src/controllers/rest-api/fulcrum/controller.js`:
+  - Added TXID validation (`64`-character hex) for `GET /v6/fulcrum/tx/data/:txid`.
+  - Updated `handleError()` logging policy:
+    - `Transaction not found` (`404`) logs at `info`
+    - other `4xx` logs at `warn`
+    - `5xx` logs at `error`
+
+## Useful Fields Available for REST Request Logging
+
+- Routing and request basics:
+  - `method` (`req.method`)
+  - `path` (`req.path`)
+  - `original_url` (`req.originalUrl`)
+  - `query` (`req.query`)
+- Client network identity:
+  - `client_ip` (`req.ip`)
+  - `forwarded_ips` (`req.ips`, when behind one or more proxies)
+  - `remote_address` (`req.socket.remoteAddress`)
+- HTTP and transport:
+  - `protocol` (`req.protocol`)
+  - `secure` (`req.secure`)
+  - `http_version` (`req.httpVersion`)
+  - `host` (`req.get('host')`)
+  - `origin` (`req.get('origin')`)
+  - `referer` (`req.get('referer')`)
+  - `user_agent` (`req.get('user-agent')`)
+- Request/response performance and size:
+  - `status_code` (`res.statusCode`, from `res.on('finish')`)
+  - `duration_ms` (elapsed time between request start and response finish)
+  - `request_size_bytes` (`req.get('content-length')`)
+  - `response_size_bytes` (`res.getHeader('content-length')`)
+- App-specific request context in this codebase:
+  - `basic_auth_valid` (`req.locals.basicAuthValid`)
+  - x402 decision/bypass status (derived from middleware path and config)
+
+## Already Logging
+
+- In Winston request logs:
+  - `message` with method + path (for example `GET /v6/full-node/blockchain/getBlockCount`)
+  - `client_ip`
+  - `remote_address`
+  - `timestamp` (from Winston timestamp formatter)
+  - `level`
+- In console endpoint logs:
+  - Request line with method, path, and `req.ip`
+  - Response line with method, path, and final `res.statusCode`
+
+## Outcome
+
+- Request logs now preserve existing behavior while adding IP attribution fields.
+- `trust proxy` ensures `req.ip` is proxy-aware when the server is deployed behind a reverse proxy.
+- The project now has a documented list of high-value request fields for future logging expansion.
+- Fulcrum missing-transaction lookups now return cleaner API semantics (`404 Transaction not found`).
+- Duplicate error logs for a single missing TX lookup were removed.
+- Invalid TXIDs are rejected early with a `400` validation error.

dev-docs/update-logs/2026-04-01.md

@@ -0,0 +1,72 @@
+# 2026-04-01 Update Log
+
+## Summary
+
+Added x402-gated discovery endpoints for agent/tool self-discovery, built a docs-derived artifact pipeline from apiDoc annotations, and documented the new flow and behavior.
+
+## Changes Made
+
+- Added new discovery controller/router:
+  - `src/controllers/discovery/controller.js`
+  - `src/controllers/discovery/router.js`
+- Added five root-path discovery endpoints:
+  - `GET /.well-known/x402`
+  - `GET /openapi.json`
+  - `GET /swagger.json`
+  - `GET /llms.txt`
+  - `GET /.well-known/agent.json`
+- Added x402-enabled gating:
+  - All five endpoints now return `404` when `X402_ENABLED=false`.
+  - When enabled, payloads are returned with x402-bch v2-oriented metadata.
+- Added apiDoc-derived document builder:
+  - `src/discovery/build-documents.js`
+  - Parses `@api` annotations and builds OpenAPI, Swagger, llms, and agent documents.
+  - Uses `docs/discovery-artifacts.json` if present, otherwise builds in-process.
+- Added artifact generation script:
+  - `scripts/build-discovery-artifacts.js`
+  - Writes `docs/discovery-artifacts.json`
+- Updated npm scripts in `package.json`:
+  - `docs:discovery`
+  - `docs:all` (runs `docs` then `docs:discovery`)
+- Wired discovery routes into server bootstrap:
+  - `bin/server.js`
+- Added tests:
+  - `test/unit/controllers/discovery-controller-unit.js`
+  - `test/unit/controllers/discovery-router-unit.js`
+  - `test/unit/controllers/discovery-documents-unit.js`
+- Updated docs/config examples:
+  - `README.md` (discovery endpoints + docs workflow)
+  - `.env-example` (x402 gating note for discovery endpoints)
+
+## Why This Was Changed
+
+- Endpoint probes for discovery paths are common from API tooling and AI agents.
+- Serving structured discovery metadata improves machine interoperability for:
+  - API clients and SDK tooling (`openapi.json`, `swagger.json`)
+  - LLM retrieval workflows (`llms.txt`)
+  - Agent capability discovery (`agent.json`)
+  - x402 payment discovery (`/.well-known/x402`)
+- Gating by `X402_ENABLED` keeps discovery aligned with monetization mode and avoids advertising payment surfaces when x402 is disabled.
+
+## Validation Notes
+
+- Lint passed.
+- New discovery-focused unit tests passed.
+- Full `npm test` run showed one pre-existing timeout failure in `test/unit/use-cases/price-use-cases-unit.js` unrelated to discovery endpoint changes.
+
+## References
+
+- Local protocol spec:
+  - `../x402-bch/specs/x402-bch-specification-v2.2.md`
+- OpenAPI Specification:
+  - https://spec.openapis.org/oas/latest.html
+- Swagger / OpenAPI 2.0:
+  - https://swagger.io/specification/v2/
+- llms.txt proposal:
+  - https://www.llmstxt.org/index.html
+- Agent manifest draft reference:
+  - https://agentwebprotocol.org/spec
+- x402 HTTP 402 background:
+  - https://docs.x402.org/core-concepts/http-402
+- x402 DNS discovery draft:
+  - https://www.ietf.org/archive/id/draft-jeftovic-x402-dns-discovery-00.html

dev-docs/update-logs/2026-04-02.md

@@ -0,0 +1,19 @@
+# 2026-04-02 Update Log
+
+## Summary
+
+Docker deployments now run `npm run docs` at container start via an entrypoint script, and optionally apply `APIDOC_URL` from the environment so apiDoc HTML matches each deployment subdomain or public URL.
+
+## Changes Made
+
+- Added `scripts/patch-apidoc-from-env.js` to set `apidoc.json` and `package.json` `apidoc.url` from `APIDOC_URL` (dotenv loads the project `.env`, same path as `bin/server.js`).
+- Added `production/docker/entrypoint.sh` to run the patch script, `npm run docs`, then `exec npm start`.
+- Updated `production/docker/Dockerfile` to remove build-time `npm run docs`, copy the entrypoint and patch script from the build context, and use `ENTRYPOINT` for the shell script.
+- Updated `production/docker/docker-compose.yml` to use build `context: ../..` and `dockerfile: production/docker/Dockerfile` so COPY paths resolve from the repository root.
+- Compose mounts `./.env` at `/home/safeuser/psf-bch-api/.env` so the app and entrypoint share one file (not `/home/safeuser/.env`).
+- Documented `APIDOC_URL` in `.env-example`, `production/docker/.env-example`, and `README.md` (Production Docker section).
+
+## Outcome
+
+- Operators can set `APIDOC_URL` in the mounted `.env` (for example `https://api.example.com`) per instance without rebuilding the image for each subdomain.
+- The HTML apiDoc bundle is regenerated on every container start so it stays aligned with the configured URL.

package.json

@@ -1,11 +1,13 @@
 {
   "name": "psf-bch-api",
-  "version": "1.0.0",
+  "version": "7.0.0",
-  "main": "index.js",
+  "main": "psf-bch-api.js",
   "type": "module",
   "scripts": {
     "start": "node bin/server.js",
     "docs": "./node_modules/.bin/apidoc -i src/ -o docs",
+    "docs:discovery": "node scripts/build-discovery-artifacts.js",
+    "docs:all": "npm run docs && npm run docs:discovery",
     "lint": "standard --env mocha --fix",
     "test": "npm run lint && TEST=unit c8 mocha 'test/unit/**/*.js' --exit",
     "test:integration": "mocha --timeout 25000 'test/integration/**/*.js' --exit",
@@ -15,16 +17,17 @@
   "license": "MIT",
   "description": "REST API proxy to Bitcoin Cash infrastructure",
   "dependencies": {
-    "@psf/bch-js": "6.8.3",
+    "@psf/bch-js": "7.1.14",
     "axios": "1.7.7",
     "cors": "2.8.5",
     "dotenv": "16.3.1",
     "express": "5.1.0",
-    "minimal-slp-wallet": "5.13.3",
+    "minimal-slp-wallet": "7.1.5",
+    "psffpp": "1.2.1",
     "slp-token-media": "1.2.10",
     "winston": "3.11.0",
     "winston-daily-rotate-file": "4.7.1",
-    "x402-bch-express": "1.1.1"
+    "x402-bch-express": "2.0.0"
   },
   "devDependencies": {
     "apidoc": "1.2.0",

production/data/.gitkeep

@@ -0,0 +1 @@
+

production/docker/.env-example

@@ -0,0 +1,45 @@
+# START INFRASTRUCTURE SETUP
+
+# Full Node Connection
+RPC_BASEURL=http://172.17.0.1:8332
+RPC_USERNAME=bitcoin
+RPC_PASSWORD=password
+
+# Fulcrum Indexer
+FULCRUM_API=http://172.17.0.1:3001/v1
+
+# SLP Indexer
+SLP_INDEXER_API=http://172.17.0.1:5020
+
+# REST API URL for wallet operations
+LOCAL_RESTURL=http://172.17.0.1:5942/v6
+
+# END INFRASTRUCTURE SETUP
+
+# Public base URL for apiDoc HTML (set per deployment / subdomain).
+# Applied at container start before `npm run docs`. Example: https://api.example.com
+#APIDOC_URL=https://api.example.com
+
+
+# START ACCESS CONTROL
+
+PORT=5942
+
+# x402 payments required to access this API?
+X402_ENABLED=false
+#X402_ENABLED=true
+#SERVER_BCH_ADDRESS=bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d
+#FACILITATOR_URL=http://localhost:4345/facilitator
+#X402_PRICE_SAT=200
+
+# Basic Authentication required to access this API?
+USE_BASIC_AUTH=false
+#USE_BASIC_AUTH=true
+#BASIC_AUTH_TOKEN=some-random-token
+
+# END ACCESS CONTROL
+
+# PSF token liquidity price proxy (GET /v6/price/psf). Off by default.
+#PSF_LIQUIDITY_PROXY_ENABLED=true
+#PSF_LIQUIDITY_URL=http://192.168.0.126:5000
+

production/docker/Dockerfile

@@ -2,8 +2,6 @@
 #
 
 #IMAGE BUILD COMMANDS
-# ct-base-ubuntu = ubuntu 18.04 + nodejs v10 LTS
-#FROM christroutner/ct-base-ubuntu
 FROM ubuntu:22.04
 MAINTAINER Chris Troutner <chris.troutner@gmail.com>
 
@@ -47,39 +45,28 @@ RUN runuser -l safeuser -c "npm config set prefix '~/.npm-global'"
 
 # Clone the rest.bitcoin.com repository
 WORKDIR /home/safeuser
-RUN git clone https://github.com/christroutner/REST2NOSTR
+RUN git clone https://github.com/Permissionless-Software-Foundation/psf-bch-api
 
 # Switch to the desired branch. `master` is usually stable,
 # and `stage` has the most up-to-date changes.
-WORKDIR /home/safeuser/REST2NOSTR
+WORKDIR /home/safeuser/psf-bch-api
 
-# For development: switch to unstable branch
+RUN git checkout ct-unstable
-#RUN git checkout pin-ipfs
 
 # Install dependencies
 RUN npm install
+RUN npm install minimal-slp-wallet
 
-# Generate the API docs
+# Runtime entrypoint + apidoc URL patch (see production/docker/entrypoint.sh).
-RUN npm run docs
+# API docs are generated at container start so APIDOC_URL can be set per deployment.
+COPY production/docker/entrypoint.sh /home/safeuser/psf-bch-api/entrypoint.sh
+COPY scripts/patch-apidoc-from-env.js /home/safeuser/psf-bch-api/scripts/patch-apidoc-from-env.js
+RUN chmod +x /home/safeuser/psf-bch-api/entrypoint.sh
 
-#VOLUME /home/safeuser/keys
+# Runtime `.env` is provided by docker-compose (mount at psf-bch-api/.env), not baked into the image.
 
-# Make leveldb folders
+ENTRYPOINT ["/home/safeuser/psf-bch-api/entrypoint.sh"]
-#RUN mkdir leveldb
-#WORKDIR /home/safeuser/psf-slp-indexer/leveldb
-#RUN mkdir current
-#RUN mkdir zips
-#RUN mkdir backup
-#WORKDIR /home/safeuser/psf-slp-indexer/leveldb/zips
-#COPY restore-auto.sh restore-auto.sh
-#WORKDIR /home/safeuser/psf-slp-indexer
 
-# Expose the port the API will be served on.
+# Used to debug the container.
-#EXPOSE 5011
+#COPY temp.js temp.js
-
+#CMD ["node", "temp.js"]
-# Start the application.
-#COPY start-production.sh start-production.sh
-VOLUME start-rest2nostr.sh
-CMD ["./start-rest2nostr.sh"]
-
-#CMD ["npm", "start"]

production/docker/docker-compose.yml

@@ -1,9 +1,11 @@
 # Start the service with the command 'docker-compose up -d'
 
 services:
-    rest2nostr:
+    psf-bch-api:
-      build: .
+      build:
-      container_name: rest2nostr
+        context: ../..
+        dockerfile: production/docker/Dockerfile
+      container_name: psf-bch-api
       logging:
         driver: 'json-file'
         options:
@@ -15,5 +17,8 @@ services:
       ports:
         - '5942:5942' # <host port>:<container port>
       volumes:
-        - ./start-rest2nostr.sh:/home/safeuser/REST2NOSTR/start-rest2nostr.sh
+        #- ./start-rest2nostr.sh:/home/safeuser/REST2NOSTR/start-rest2nostr.sh
+        - ./.env:/home/safeuser/psf-bch-api/.env
+        - ../data:/home/safeuser/psf-bch-api/production/data
+        - ../data/logs:/home/safeuser/psf-bch-api/logs
       restart: always

production/docker/entrypoint.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+
+cd /home/safeuser/psf-bch-api
+
+node scripts/patch-apidoc-from-env.js
+
+npm run docs
+
+exec npm start

production/docker/start-rest2nostr.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-
-npm start

scripts/build-discovery-artifacts.js

@@ -0,0 +1,21 @@
+/*
+  Build discovery endpoint artifacts from apiDoc source annotations.
+*/
+
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+
+import { buildDiscoveryDocuments } from '../src/discovery/build-documents.js'
+
+function main () {
+  const outputPath = resolve(process.cwd(), 'docs/discovery-artifacts.json')
+  const docs = buildDiscoveryDocuments()
+
+  mkdirSync(dirname(outputPath), { recursive: true })
+  writeFileSync(outputPath, `${JSON.stringify(docs, null, 2)}\n`)
+
+  // eslint-disable-next-line no-console
+  console.log(`Wrote discovery artifacts to ${outputPath}`)
+}
+
+main()

scripts/patch-apidoc-from-env.js

@@ -0,0 +1,41 @@
+/*
+  Applies APIDOC_URL from the environment to apidoc.json and package.json (apidoc.url).
+  Loads dotenv from the project root `.env` (same file as `dotenv.config()` in bin/server.js).
+  Exits without changes when APIDOC_URL is unset or empty.
+*/
+
+import dotenv from 'dotenv'
+import { readFileSync, writeFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const root = resolve(__dirname, '..')
+
+dotenv.config({ path: resolve(root, '.env') })
+
+const url = process.env.APIDOC_URL
+if (url === undefined || url === null || String(url).trim() === '') {
+  process.exit(0)
+}
+
+const normalized = String(url).trim()
+
+function patchApidocJson () {
+  const path = resolve(root, 'apidoc.json')
+  const data = JSON.parse(readFileSync(path, 'utf8'))
+  data.url = normalized
+  data.sampleUrl = normalized
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`)
+}
+
+function patchPackageJson () {
+  const path = resolve(root, 'package.json')
+  const data = JSON.parse(readFileSync(path, 'utf8'))
+  if (!data.apidoc) data.apidoc = {}
+  data.apidoc.url = normalized
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`)
+}
+
+patchApidocJson()
+patchPackageJson()

src/adapters/fulcrum-api.js

@@ -65,17 +65,28 @@ class FulcrumAPIAdapter {
       // Attempt to extract error message from response data
       if (err.response && err.response.data) {
         const data = err.response.data
+        const status = err.response.status || 400
+        const message = this._extractErrorMessage(data)
+
+        if (this._isCommonMissingTxError(message)) {
+          return this._formatError('Transaction not found', 404)
+        }
+
+        if (message) {
+          return this._formatError(message, status)
+        }
+
         // Handle structured error responses
         if (data.error) {
-          return this._formatError(data.error, err.response.status || 400)
+          return this._formatError(data.error, status)
         }
         // Handle string error messages
         if (typeof data === 'string') {
-          return this._formatError(data, err.response.status || 400)
+          return this._formatError(data, status)
         }
         // Handle object responses that might contain error info
         if (typeof data === 'object' && data.message) {
-          return this._formatError(data.message, err.response.status || 400)
+          return this._formatError(data.message, status)
         }
         // Fallback to returning the status
         return this._formatError('Fulcrum API error', err.response.status || 500)
@@ -119,6 +130,25 @@ class FulcrumAPIAdapter {
       status: status || 500
     }
   }
+
+  _extractErrorMessage (data) {
+    if (!data) return ''
+
+    if (typeof data === 'string') return data
+
+    if (typeof data === 'object') {
+      if (typeof data.error === 'string') return data.error
+      if (data.error && typeof data.error === 'object' && data.error.message) return data.error.message
+      if (data.message) return data.message
+    }
+
+    return ''
+  }
+
+  _isCommonMissingTxError (message = '') {
+    return typeof message === 'string' &&
+      message.includes('No such mempool or blockchain transaction')
+  }
 }
 
 export default FulcrumAPIAdapter

src/adapters/full-node-rpc.js

@@ -39,6 +39,7 @@ class FullNodeRPCAdapter {
 
   async call (method, params = [], requestId) {
     const id = requestId || `${this.requestIdPrefix}-${method}`
+    console.log('full-node-rpc.js/call(): this.http.defaults.baseURL: ', this.http.defaults.baseURL)
 
     try {
       const response = await this.http.post('', {

src/config/env/common.js

@@ -26,21 +26,44 @@ const normalizeBoolean = (value, defaultValue) => {
   return defaultValue
 }
 
-// By default, the price per API call is 2000 satoshis.
+// By default, the price per API call is 200 satoshis.
 // But the user can override this value by setting the X402_PRICE_SAT environment variable.
 const parsedPriceSat = Number(process.env.X402_PRICE_SAT)
-const priceSat = Number.isFinite(parsedPriceSat) && parsedPriceSat > 0 ? parsedPriceSat : 2000
+const priceSat = Number.isFinite(parsedPriceSat) && parsedPriceSat > 0 ? parsedPriceSat : 200
 
 const x402Defaults = {
   enabled: normalizeBoolean(process.env.X402_ENABLED, true),
   facilitatorUrl: process.env.FACILITATOR_URL || 'http://localhost:4345/facilitator',
-  serverAddress: process.env.SERVER_BCH_ADDRESS || 'bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d',
+  serverAddress: process.env.SERVER_BCH_ADDRESS || 'bitcoincash:qqsrke9lh257tqen99dkyy2emh4uty0vky9y0z0lsr',
   priceSat
 }
 
+const basicAuthDefaults = {
+  enabled: normalizeBoolean(process.env.USE_BASIC_AUTH, false),
+  token: process.env.BASIC_AUTH_TOKEN || ''
+}
+
+const psfLiquidityUrlEnv = process.env.PSF_LIQUIDITY_URL
+const psfLiquidityProxyBaseUrl =
+  psfLiquidityUrlEnv !== undefined &&
+  psfLiquidityUrlEnv !== null &&
+  String(psfLiquidityUrlEnv).trim() !== ''
+    ? String(psfLiquidityUrlEnv).trim().replace(/\/$/, '')
+    : 'http://192.168.0.126:5000'
+
+const psfLiquidityProxyDefaults = {
+  enabled: normalizeBoolean(process.env.PSF_LIQUIDITY_PROXY_ENABLED, false),
+  baseUrl: psfLiquidityProxyBaseUrl
+}
+
 export default {
   // Server port
-  port: process.env.PORT || 5942,
+  port: parseInt(process.env.PORT, 10) || 5942,
+
+  // HTTP server connection lifecycle configuration.
+  serverKeepAliveTimeoutMs: Number(process.env.SERVER_KEEPALIVE_TIMEOUT_MS || 3000),
+  serverHeadersTimeoutMs: Number(process.env.SERVER_HEADERS_TIMEOUT_MS || 65000),
+  serverRequestTimeoutMs: Number(process.env.SERVER_REQUEST_TIMEOUT_MS || 120000),
 
   // Environment
   env: process.env.NODE_ENV || 'development',
@@ -73,13 +96,17 @@ export default {
   },
 
   // REST API URL for wallet operations
-  restURL: process.env.REST_URL || process.env.LOCAL_RESTURL || 'http://127.0.0.1:3000/v5/',
+  restURL: process.env.REST_URL || process.env.LOCAL_RESTURL || 'http://127.0.0.1:5942/v6/',
 
   // IPFS Gateway URL
   ipfsGateway: process.env.IPFS_GATEWAY || 'p2wdb-gateway-678.fullstack.cash',
 
   x402: x402Defaults,
 
+  basicAuth: basicAuthDefaults,
+
+  psfLiquidityProxy: psfLiquidityProxyDefaults,
+
   // Version
   version
 }

src/config/x402.js

@@ -26,7 +26,7 @@ export function buildX402Routes (apiPrefix = '/v6') {
       price: config.x402.priceSat,
       network: NETWORK,
       config: {
-        description: `${DEFAULT_DESCRIPTION} (2000 satoshis)`,
+        description: `${DEFAULT_DESCRIPTION} (${config.x402.priceSat} satoshis)`,
         maxTimeoutSeconds: DEFAULT_TIMEOUT_SECONDS
       }
     }
@@ -41,3 +41,10 @@ export function getX402Settings () {
     priceSat: config.x402?.priceSat
   }
 }
+
+export function getBasicAuthSettings () {
+  return {
+    enabled: Boolean(config.basicAuth?.enabled),
+    token: config.basicAuth?.token || ''
+  }
+}

src/controllers/discovery/controller.js

@@ -0,0 +1,152 @@
+/*
+  Controller for discovery and machine-readable metadata endpoints.
+*/
+
+import config from '../../config/index.js'
+import { getX402Settings } from '../../config/x402.js'
+import { getDiscoveryDocuments } from '../../discovery/build-documents.js'
+
+const BCH_MAINNET_CAIP2 = 'bip122:000000000000000000651ef99cb9fcbe'
+const BCH_NATIVE_ASSET = '0x0000000000000000000000000000000000000001'
+const X402_TIMEOUT_SECONDS = 60
+
+class DiscoveryController {
+  constructor (localConfig = {}) {
+    this.getX402Settings = localConfig.getX402Settings || getX402Settings
+    this.getDiscoveryDocuments = localConfig.getDiscoveryDocuments || getDiscoveryDocuments
+    this.apiPrefix = localConfig.apiPrefix || config.apiPrefix
+
+    this.x402Manifest = this.x402Manifest.bind(this)
+    this.openapi = this.openapi.bind(this)
+    this.swagger = this.swagger.bind(this)
+    this.llmsTxt = this.llmsTxt.bind(this)
+    this.agentManifest = this.agentManifest.bind(this)
+    this.respondNotFoundWhenDisabled = this.respondNotFoundWhenDisabled.bind(this)
+    this.sendText = this.sendText.bind(this)
+  }
+
+  respondNotFoundWhenDisabled (res) {
+    const { enabled } = this.getX402Settings()
+    if (enabled) return false
+
+    res.status(404).json({
+      error: 'Not found'
+    })
+    return true
+  }
+
+  /**
+   * @api {get} /.well-known/x402 x402-bch resource discovery
+   * @apiName X402Discovery
+   * @apiGroup Discovery
+   * @apiDescription Returns x402-bch v2 resource and payment requirement metadata.
+   */
+  x402Manifest (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const x402 = this.getX402Settings()
+    const apiPrefix = this.apiPrefix || '/v6'
+    const prefixWithSlash = apiPrefix.startsWith('/') ? apiPrefix : `/${apiPrefix}`
+
+    const payload = {
+      x402Version: 2,
+      network: BCH_MAINNET_CAIP2,
+      facilitator: {
+        url: x402.facilitatorUrl
+      },
+      resources: [
+        {
+          resource: `${prefixWithSlash}/*`,
+          type: 'http',
+          x402Version: 2,
+          accepts: [
+            {
+              scheme: 'utxo',
+              network: BCH_MAINNET_CAIP2,
+              amount: String(x402.priceSat),
+              description: `Access to protected psf-bch-api resources (${x402.priceSat} satoshis)`,
+              mimeType: 'application/json',
+              payTo: x402.serverAddress,
+              maxTimeoutSeconds: X402_TIMEOUT_SECONDS,
+              asset: BCH_NATIVE_ASSET,
+              extra: {}
+            }
+          ]
+        }
+      ]
+    }
+
+    return res.status(200).json(payload)
+  }
+
+  /**
+   * @api {get} /openapi.json OpenAPI discovery document
+   * @apiName OpenApiDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns an OpenAPI document generated from apiDoc annotations.
+   */
+  openapi (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return res.status(200).json(docs.openapi)
+  }
+
+  /**
+   * @api {get} /swagger.json Swagger discovery document
+   * @apiName SwaggerDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns a Swagger 2.0 compatibility document generated from apiDoc annotations.
+   */
+  swagger (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return res.status(200).json(docs.swagger)
+  }
+
+  /**
+   * @api {get} /llms.txt LLM discovery file
+   * @apiName LlmsDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns an llms.txt markdown index for AI tooling discovery.
+   */
+  llmsTxt (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return this.sendText(res, docs.llms)
+  }
+
+  /**
+   * @api {get} /.well-known/agent.json Agent manifest
+   * @apiName AgentManifestDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns a draft agent manifest describing API capabilities.
+   */
+  agentManifest (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return res.status(200).json(docs.agent)
+  }
+
+  sendText (res, text) {
+    res.status(200)
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+
+    if (typeof res.send === 'function') {
+      return res.send(text)
+    }
+
+    if (typeof res.write === 'function') {
+      res.write(text)
+    }
+    if (typeof res.end === 'function') {
+      res.end()
+    }
+    return res
+  }
+}
+
+export default DiscoveryController

src/controllers/discovery/router.js

@@ -0,0 +1,30 @@
+/*
+  Router for discovery and machine-readable metadata endpoints.
+*/
+
+import express from 'express'
+import DiscoveryController from './controller.js'
+
+class DiscoveryRouter {
+  constructor (localConfig = {}) {
+    this.controller = localConfig.controller || new DiscoveryController()
+    this.router = express.Router()
+    this.attach = this.attach.bind(this)
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching DiscoveryRouter.')
+    }
+
+    this.router.get('/.well-known/x402', this.controller.x402Manifest)
+    this.router.get('/openapi.json', this.controller.openapi)
+    this.router.get('/swagger.json', this.controller.swagger)
+    this.router.get('/llms.txt', this.controller.llmsTxt)
+    this.router.get('/.well-known/agent.json', this.controller.agentManifest)
+
+    app.use(this.router)
+  }
+}
+
+export default DiscoveryRouter

src/controllers/rest-api/encryption/controller.js

@@ -0,0 +1,100 @@
+/*
+  REST API Controller for the /encryption routes.
+*/
+
+import wlogger from '../../../adapters/wlogger.js'
+
+class EncryptionRESTController {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Encryption REST Controller.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases || !this.useCases.encryption) {
+      throw new Error(
+        'Instance of Encryption use cases required when instantiating Encryption REST Controller.'
+      )
+    }
+
+    this.encryptionUseCases = this.useCases.encryption
+
+    // Bind functions
+    this.root = this.root.bind(this)
+    this.getPublicKey = this.getPublicKey.bind(this)
+    this.handleError = this.handleError.bind(this)
+  }
+
+  /**
+   * @api {get} /v6/encryption/ Service status
+   * @apiName EncryptionRoot
+   * @apiGroup Encryption
+   *
+   * @apiDescription Returns the status of the encryption service.
+   *
+   * @apiSuccess {String} status Service identifier
+   */
+  async root (req, res) {
+    return res.status(200).json({ status: 'encryption' })
+  }
+
+  /**
+   * @api {get} /v6/encryption/publickey/:address Get public key for a BCH address
+   * @apiName GetPublicKey
+   * @apiGroup Encryption
+   * @apiDescription Searches the blockchain for a public key associated with a
+   * BCH address. Returns an object. If successful, the publicKey property will
+   * contain a hexadecimal representation of the public key.
+   *
+   * @apiParam {String} address BCH address (cash address or legacy format)
+   *
+   * @apiExample Example usage:
+   * curl -X GET "https://api.fullstack.cash/v6/encryption/publickey/bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf" -H "accept: application/json"
+   *
+   * @apiSuccess {Boolean} success Indicates if the operation was successful
+   * @apiSuccess {String} publicKey The public key in hexadecimal format, or "not found"
+   */
+  async getPublicKey (req, res) {
+    try {
+      const address = req.params.address
+
+      // Reject if address is an array
+      if (Array.isArray(address)) {
+        res.status(400)
+        return res.json({
+          success: false,
+          error: 'address can not be an array.'
+        })
+      }
+
+      // Reject if address is missing
+      if (!address) {
+        res.status(400)
+        return res.json({
+          success: false,
+          error: 'address is required.'
+        })
+      }
+
+      const result = await this.encryptionUseCases.getPublicKey({ address })
+
+      return res.status(200).json(result)
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  handleError (err, res) {
+    wlogger.error('Error in EncryptionRESTController:', err)
+
+    const status = err.status || 500
+    const message = err.message || 'Internal server error'
+
+    return res.status(status).json({ success: false, error: message })
+  }
+}
+
+export default EncryptionRESTController

src/controllers/rest-api/encryption/router.js

@@ -0,0 +1,51 @@
+/*
+  REST API router for /encryption routes.
+*/
+
+import express from 'express'
+import EncryptionRESTController from './controller.js'
+
+class EncryptionRouter {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Encryption REST Router.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases) {
+      throw new Error(
+        'Instance of Use Cases library required when instantiating Encryption REST Router.'
+      )
+    }
+
+    const dependencies = {
+      adapters: this.adapters,
+      useCases: this.useCases
+    }
+
+    this.encryptionController = new EncryptionRESTController(dependencies)
+
+    this.apiPrefix = (localConfig.apiPrefix || '').replace(/\/$/, '')
+    this.baseUrl = `${this.apiPrefix}/encryption`
+    if (!this.baseUrl.startsWith('/')) {
+      this.baseUrl = `/${this.baseUrl}`
+    }
+    this.router = express.Router()
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching REST API controllers.')
+    }
+
+    this.router.get('/', this.encryptionController.root)
+    this.router.get('/publickey/:address', this.encryptionController.getPublicKey)
+
+    app.use(this.baseUrl, this.router)
+  }
+}
+
+export default EncryptionRouter

src/controllers/rest-api/fulcrum/controller.js

@@ -4,8 +4,9 @@
 
 import wlogger from '../../../adapters/wlogger.js'
 import BCHJS from '@psf/bch-js'
+import config from '../../../config/index.js'
 
-const bchjs = new BCHJS()
+const bchjs = new BCHJS({ restURL: config.restURL })
 
 class FulcrumRESTController {
   constructor (localConfig = {}) {
@@ -86,6 +87,16 @@ class FulcrumRESTController {
     return cashAddr
   }
 
+  _isValidTxid (txid) {
+    return typeof txid === 'string' && /^[a-fA-F0-9]{64}$/.test(txid)
+  }
+
+  _isCommonMissingTxError (err) {
+    return err?.status === 404 &&
+      typeof err?.message === 'string' &&
+      err.message.includes('Transaction not found')
+  }
+
   /**
    * @api {get} /v6/fulcrum/balance/:address Get balance for a single address
    * @apiName GetBalance
@@ -238,10 +249,10 @@ class FulcrumRESTController {
     try {
       const txid = req.params.txid
 
-      if (typeof txid !== 'string') {
+      if (!this._isValidTxid(txid)) {
         return res.status(400).json({
           success: false,
-          error: 'txid must be a string'
+          error: 'txid must be a 64-character hex string'
         })
       }
 
@@ -423,7 +434,20 @@ class FulcrumRESTController {
 
       const cashAddr = this._validateAndConvertAddress(address)
 
-      const result = await this.fulcrumUseCases.getTransactions({ address: cashAddr, allTxs })
+      // Extract bearer token from request header if present
+      let bearerToken = null
+      if (req.headers && req.headers.authorization) {
+        const parts = req.headers.authorization.split(' ')
+        if (parts.length === 2 && parts[0] === 'Bearer') {
+          bearerToken = parts[1]
+        }
+      }
+
+      const result = await this.fulcrumUseCases.getTransactions({
+        address: cashAddr,
+        allTxs,
+        bearerToken
+      })
       return res.status(200).json(result)
     } catch (err) {
       return this.handleError(err, res)
@@ -469,9 +493,19 @@ class FulcrumRESTController {
         }
       }
 
+      // Extract bearer token from request header if present
+      let bearerToken = null
+      if (req.headers && req.headers.authorization) {
+        const parts = req.headers.authorization.split(' ')
+        if (parts.length === 2 && parts[0] === 'Bearer') {
+          bearerToken = parts[1]
+        }
+      }
+
       const result = await this.fulcrumUseCases.getTransactionsBulk({
         addresses: validatedAddresses,
-        allTxs
+        allTxs,
+        bearerToken
       })
       return res.status(200).json(result)
     } catch (err) {
@@ -551,9 +585,17 @@ class FulcrumRESTController {
   }
 
   handleError (err, res) {
-    wlogger.error('Error in FulcrumRESTController:', err)
-
     const status = err.status || 500
+    const isCommonMissingTxError = this._isCommonMissingTxError(err)
+
+    if (isCommonMissingTxError) {
+      wlogger.info(`Fulcrum transaction not found: ${err.message}`)
+    } else if (status >= 500) {
+      wlogger.error('Error in FulcrumRESTController:', err)
+    } else {
+      wlogger.warn(`Fulcrum client error (${status}): ${err.message}`)
+    }
+
     const message = err.message || 'Internal server error'
 
     return res.status(status).json({ error: message })

src/controllers/rest-api/index.js

@@ -10,8 +10,10 @@
 import BlockchainRouter from './full-node/blockchain/router.js'
 import ControlRouter from './full-node/control/router.js'
 import DSProofRouter from './full-node/dsproof/router.js'
+import EncryptionRouter from './encryption/router.js'
 import FulcrumRouter from './fulcrum/router.js'
 import MiningRouter from './full-node/mining/router.js'
+import PriceRouter from './price/router.js'
 import RawTransactionsRouter from './full-node/rawtransactions/router.js'
 import SlpRouter from './slp/router.js'
 import config from '../../config/index.js'
@@ -69,12 +71,18 @@ class RESTControllers {
     const dsproofRouter = new DSProofRouter(dependencies)
     dsproofRouter.attach(app)
 
+    const encryptionRouter = new EncryptionRouter(dependencies)
+    encryptionRouter.attach(app)
+
     const fulcrumRouter = new FulcrumRouter(dependencies)
     fulcrumRouter.attach(app)
 
     const miningRouter = new MiningRouter(dependencies)
     miningRouter.attach(app)
 
+    const priceRouter = new PriceRouter(dependencies)
+    priceRouter.attach(app)
+
     const rawtransactionsRouter = new RawTransactionsRouter(dependencies)
     rawtransactionsRouter.attach(app)
 

src/controllers/rest-api/price/controller.js

@@ -0,0 +1,121 @@
+/*
+  REST API Controller for the /price routes.
+*/
+
+import wlogger from '../../../adapters/wlogger.js'
+
+class PriceRESTController {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Price REST Controller.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases || !this.useCases.price) {
+      throw new Error(
+        'Instance of Price use cases required when instantiating Price REST Controller.'
+      )
+    }
+
+    this.priceUseCases = this.useCases.price
+
+    // Bind functions
+    this.root = this.root.bind(this)
+    this.getBCHUSD = this.getBCHUSD.bind(this)
+    this.getPsffppWritePrice = this.getPsffppWritePrice.bind(this)
+    this.getPsfLiquidityPrice = this.getPsfLiquidityPrice.bind(this)
+    this.handleError = this.handleError.bind(this)
+  }
+
+  /**
+   * @api {get} /v6/price/ Service status
+   * @apiName PriceRoot
+   * @apiGroup Price
+   *
+   * @apiDescription Returns the status of the price service.
+   *
+   * @apiSuccess {String} status Service identifier
+   */
+  async root (req, res) {
+    return res.status(200).json({ status: 'price' })
+  }
+
+  /**
+   * @api {get} /v6/price/bchusd Get the USD price of BCH
+   * @apiName GetBCHUSD
+   * @apiGroup Price
+   * @apiDescription Get the USD price of BCH from Coinex.
+   *
+   * @apiExample Example usage:
+   * curl -X GET "https://api.fullstack.cash/v6/price/bchusd" -H "accept: application/json"
+   *
+   * @apiSuccess {Number} usd The USD price of BCH
+   */
+  async getBCHUSD (req, res) {
+    try {
+      const price = await this.priceUseCases.getBCHUSD()
+      return res.status(200).json({ usd: price })
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  /**
+   * @api {get} /v6/price/psffpp Get the PSF price for writing to the PSFFPP
+   * @apiName GetPsffppWritePrice
+   * @apiGroup Price
+   * @apiDescription Get the price to pin 1MB of content to the PSFFPP pinning
+   * network on IPFS. The price is denominated in PSF tokens.
+   *
+   * @apiExample Example usage:
+   * curl -X GET "https://api.fullstack.cash/v6/price/psffpp" -H "accept: application/json"
+   *
+   * @apiSuccess {Number} writePrice The price in PSF tokens to write 1MB to PSFFPP
+   */
+  async getPsffppWritePrice (req, res) {
+    try {
+      const writePrice = await this.priceUseCases.getPsffppWritePrice()
+      return res.status(200).json({ writePrice })
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  /**
+   * @api {get} /v6/price/psf PSF token liquidity spot price (proxied)
+   * @apiName GetPsfLiquidityPrice
+   * @apiGroup Price
+   * @apiDescription Proxies GET /price from the PSF token liquidity app when
+   * `PSF_LIQUIDITY_PROXY_ENABLED` is true. Returns 503 when the proxy is disabled.
+   *
+   * @apiExample Example usage:
+   * curl -X GET "https://api.fullstack.cash/v6/price/psf" -H "accept: application/json"
+   *
+   * @apiSuccess {Number} usdPerBCH USD price per 1 BCH
+   * @apiSuccess {Number} bchBalance BCH balance (liquidity app)
+   * @apiSuccess {Number} tokenBalance Effective PSF token balance
+   * @apiSuccess {Number} usdPerToken USD price per 1 PSF token
+   */
+  async getPsfLiquidityPrice (req, res) {
+    try {
+      const payload = await this.priceUseCases.getPsfLiquidityPrice()
+      return res.status(200).json(payload)
+    } catch (err) {
+      return this.handleError(err, res)
+    }
+  }
+
+  handleError (err, res) {
+    wlogger.error('Error in PriceRESTController:', err)
+
+    const status = err.status || 500
+    const message = err.message || 'Internal server error'
+
+    return res.status(status).json({ error: message })
+  }
+}
+
+export default PriceRESTController

src/controllers/rest-api/price/router.js

@@ -0,0 +1,53 @@
+/*
+  REST API router for /price routes.
+*/
+
+import express from 'express'
+import PriceRESTController from './controller.js'
+
+class PriceRouter {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error(
+        'Instance of Adapters library required when instantiating Price REST Router.'
+      )
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases) {
+      throw new Error(
+        'Instance of Use Cases library required when instantiating Price REST Router.'
+      )
+    }
+
+    const dependencies = {
+      adapters: this.adapters,
+      useCases: this.useCases
+    }
+
+    this.priceController = new PriceRESTController(dependencies)
+
+    this.apiPrefix = (localConfig.apiPrefix || '').replace(/\/$/, '')
+    this.baseUrl = `${this.apiPrefix}/price`
+    if (!this.baseUrl.startsWith('/')) {
+      this.baseUrl = `/${this.baseUrl}`
+    }
+    this.router = express.Router()
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching REST API controllers.')
+    }
+
+    this.router.get('/', this.priceController.root)
+    this.router.get('/bchusd', this.priceController.getBCHUSD)
+    this.router.get('/psffpp', this.priceController.getPsffppWritePrice)
+    this.router.get('/psf', this.priceController.getPsfLiquidityPrice)
+
+    app.use(this.baseUrl, this.router)
+  }
+}
+
+export default PriceRouter

src/controllers/rest-api/slp/controller.js

@@ -4,8 +4,9 @@
 
 import wlogger from '../../../adapters/wlogger.js'
 import BCHJS from '@psf/bch-js'
+import config from '../../../config/index.js'
 
-const bchjs = new BCHJS()
+const bchjs = new BCHJS({ restURL: config.restURL })
 
 class SlpRESTController {
   constructor (localConfig = {}) {
@@ -201,12 +202,20 @@ class SlpRESTController {
       const result = await this.slpUseCases.getTokenData({ tokenId, withTxHistory })
       return res.status(200).json(result)
     } catch (err) {
+      console.log('Error in /v6/slp/token/data getTokenData(): ', err)
       return this.handleError(err, res)
     }
   }
 
   handleError (err, res) {
-    wlogger.error('Error in SlpRESTController:', err)
+    const isCommonMissingTxError =
+      err?.status === 404 &&
+      typeof err?.message === 'string' &&
+      err.message.includes('Key not found in database')
+
+    if (!isCommonMissingTxError) {
+      wlogger.error('Error in SlpRESTController:', err)
+    }
 
     const status = err.status || 500
     const message = err.message || 'Internal server error'

src/discovery/build-documents.js

@@ -0,0 +1,223 @@
+/*
+  Build and cache discovery documents from apiDoc-style annotations.
+*/
+
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { resolve } from 'path'
+
+import config from '../config/index.js'
+import { getX402Settings } from '../config/x402.js'
+
+const BCH_MAINNET_CAIP2 = 'bip122:000000000000000000651ef99cb9fcbe'
+const X402_SPEC_VERSION = 2
+
+let cachedDocs = null
+
+function parseApiAnnotations () {
+  const srcRoot = resolve(process.cwd(), 'src/controllers/rest-api')
+  const entries = []
+  const files = walkJsFiles(srcRoot)
+
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8')
+    const blocks = text.match(/\/\*\*[\s\S]*?\*\//g) || []
+
+    for (const block of blocks) {
+      const endpoint = parseBlock(block)
+      if (endpoint) entries.push(endpoint)
+    }
+  }
+
+  return entries
+}
+
+function parseBlock (block) {
+  const methodMatch = block.match(/@api\s+\{([^}]+)\}\s+(\S+)\s+([^\n\r*]+)/)
+  if (!methodMatch) return null
+
+  const method = methodMatch[1].trim().toUpperCase()
+  const path = methodMatch[2].trim()
+  const summary = methodMatch[3].trim()
+
+  const groupMatch = block.match(/@apiGroup\s+([^\n\r*]+)/)
+  const descriptionMatch = block.match(/@apiDescription\s+([^\n\r*][\s\S]*?)(?=\n\s*\*\s*@api|\n\s*\*\/)/)
+  const apiNameMatch = block.match(/@apiName\s+([^\n\r*]+)/)
+
+  return {
+    method,
+    path,
+    summary,
+    group: groupMatch ? groupMatch[1].trim() : 'General',
+    operationId: apiNameMatch ? apiNameMatch[1].trim() : `${method.toLowerCase()}_${path.replace(/[^\w]/g, '_')}`,
+    description: descriptionMatch
+      ? descriptionMatch[1].replace(/\n\s*\*\s?/g, ' ').trim()
+      : summary
+  }
+}
+
+function walkJsFiles (dir) {
+  const output = []
+
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = resolve(dir, item.name)
+    if (item.isDirectory()) {
+      output.push(...walkJsFiles(fullPath))
+      continue
+    }
+
+    if (item.isFile() && fullPath.endsWith('.js')) output.push(fullPath)
+  }
+
+  return output
+}
+
+function normalizePaths (endpoints) {
+  const paths = {}
+
+  for (const endpoint of endpoints) {
+    if (!paths[endpoint.path]) paths[endpoint.path] = {}
+
+    const op = {
+      tags: [endpoint.group],
+      summary: endpoint.summary,
+      description: endpoint.description,
+      operationId: endpoint.operationId,
+      responses: {
+        200: {
+          description: 'Successful response'
+        },
+        402: {
+          description: 'Payment required when x402 is enabled'
+        }
+      },
+      'x-payment-model': 'x402-bch-v2'
+    }
+
+    paths[endpoint.path][endpoint.method.toLowerCase()] = op
+  }
+
+  return paths
+}
+
+function buildOpenApi (paths) {
+  return {
+    openapi: '3.0.3',
+    info: {
+      title: 'psf-bch-api',
+      version: config.version,
+      description: 'OpenAPI projection generated from apiDoc annotations'
+    },
+    servers: [
+      {
+        url: '/'
+      }
+    ],
+    paths
+  }
+}
+
+function buildSwagger (paths) {
+  return {
+    swagger: '2.0',
+    info: {
+      title: 'psf-bch-api',
+      version: config.version,
+      description: 'Swagger projection generated from apiDoc annotations'
+    },
+    basePath: '/',
+    schemes: ['https', 'http'],
+    paths
+  }
+}
+
+function buildLlms (endpoints) {
+  const lines = [
+    '# psf-bch-api',
+    '',
+    '> REST API proxy to Bitcoin Cash infrastructure with optional x402-bch monetized access.',
+    '',
+    '## Discovery',
+    '- [OpenAPI document](/openapi.json): OpenAPI 3 projection generated from apiDoc annotations.',
+    '- [Swagger document](/swagger.json): Swagger 2.0 compatibility projection.',
+    '- [x402 manifest](/.well-known/x402): x402-bch v2 payment requirement discovery.',
+    '- [Agent manifest](/.well-known/agent.json): draft agent capability surface.',
+    '',
+    '## API Groups'
+  ]
+
+  const seen = new Set()
+  for (const endpoint of endpoints) {
+    if (seen.has(endpoint.group)) continue
+    seen.add(endpoint.group)
+    lines.push(`- ${endpoint.group}`)
+  }
+
+  lines.push('', '## Optional', '- [Human docs](/): apiDoc HTML documentation root.')
+  return lines.join('\n')
+}
+
+function buildAgent (endpoints) {
+  const x402 = getX402Settings()
+  const actions = endpoints.map(endpoint => ({
+    id: endpoint.operationId,
+    description: endpoint.summary,
+    auth_required: true,
+    endpoint: endpoint.path,
+    method: endpoint.method
+  }))
+
+  return {
+    awp_version: '0.1',
+    domain: 'localhost',
+    intent: 'Programmatic BCH blockchain API access',
+    capabilities: {
+      batch_actions: false,
+      streaming: false
+    },
+    auth: {
+      type: 'x402-bch-v2',
+      required_for: actions.map(a => a.id),
+      pricing: {
+        amountSat: String(x402.priceSat),
+        payTo: x402.serverAddress,
+        network: BCH_MAINNET_CAIP2,
+        x402Version: X402_SPEC_VERSION
+      }
+    },
+    actions
+  }
+}
+
+export function buildDiscoveryDocuments () {
+  const endpoints = parseApiAnnotations()
+  const paths = normalizePaths(endpoints)
+
+  return {
+    openapi: buildOpenApi(paths),
+    swagger: buildSwagger(paths),
+    llms: buildLlms(endpoints),
+    agent: buildAgent(endpoints)
+  }
+}
+
+export function getDiscoveryDocuments () {
+  if (cachedDocs) return cachedDocs
+
+  const artifactPath = resolve(process.cwd(), 'docs/discovery-artifacts.json')
+  if (existsSync(artifactPath)) {
+    try {
+      cachedDocs = JSON.parse(readFileSync(artifactPath, 'utf8'))
+      return cachedDocs
+    } catch {
+      cachedDocs = buildDiscoveryDocuments()
+      return cachedDocs
+    }
+  }
+
+  cachedDocs = buildDiscoveryDocuments()
+  return cachedDocs
+}
+
+export function resetDiscoveryDocumentCache () {
+  cachedDocs = null
+}

src/middleware/basic-auth.js

@@ -0,0 +1,61 @@
+/*
+  Basic Authentication Middleware
+
+  This middleware validates Bearer tokens from the Authorization header.
+  When a valid token is provided, it sets req.locals.basicAuthValid = true
+  to allow bypassing x402 middleware.
+*/
+
+import config from '../config/index.js'
+import wlogger from '../adapters/wlogger.js'
+
+/**
+ * Middleware function that validates Bearer token authentication
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ */
+export function basicAuthMiddleware (req, res, next) {
+  // Initialize req.locals if it doesn't exist
+  if (!req.locals) {
+    req.locals = {}
+  }
+
+  // Default to false
+  req.locals.basicAuthValid = false
+
+  // Get the configured token
+  const configuredToken = config.basicAuth?.token
+
+  // If no token is configured, skip validation
+  if (!configuredToken) {
+    wlogger.warn('Basic auth enabled but no BASIC_AUTH_TOKEN configured')
+    return next()
+  }
+
+  // Get the Authorization header
+  const authHeader = req.headers.authorization
+
+  // If no Authorization header, continue (x402 will handle unauthorized requests)
+  if (!authHeader) {
+    return next()
+  }
+
+  // Check if it's a Bearer token
+  const parts = authHeader.split(' ')
+  if (parts.length !== 2 || parts[0] !== 'Bearer') {
+    return next()
+  }
+
+  const providedToken = parts[1]
+
+  // Compare tokens
+  if (providedToken === configuredToken) {
+    req.locals.basicAuthValid = true
+    wlogger.verbose(`Basic auth validated for request to ${req.path}`)
+  }
+
+  // Always continue to next middleware
+  // If auth failed, x402 middleware will handle the request
+  next()
+}

src/use-cases/encryption-use-cases.js

@@ -0,0 +1,120 @@
+/*
+  Use cases for encryption-related operations.
+  Retrieves public keys from the blockchain for BCH addresses.
+*/
+
+// Global npm libraries
+import BCHJS from '@psf/bch-js'
+
+// Local libraries
+import wlogger from '../adapters/wlogger.js'
+import config from '../config/index.js'
+
+const bchjs = new BCHJS({ restURL: config.restURL })
+
+class EncryptionUseCases {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+    if (!this.adapters) {
+      throw new Error('Adapters instance required when instantiating Encryption use cases.')
+    }
+
+    this.useCases = localConfig.useCases
+    if (!this.useCases) {
+      throw new Error('UseCases instance required when instantiating Encryption use cases.')
+    }
+
+    // Allow bchjs to be injected for testing
+    this.bchjs = localConfig.bchjs || bchjs
+  }
+
+  /**
+   * Get the public key for a BCH address by searching the blockchain.
+   * Searches the transaction history of the address for a transaction input
+   * that contains the public key.
+   *
+   * @param {Object} params - Parameters object
+   * @param {string} params.address - BCH address (cash address or legacy format)
+   * @returns {Promise<Object>} Object with success status and publicKey if found
+   */
+  async getPublicKey ({ address }) {
+    try {
+      // Convert to cash address format
+      const cashAddr = this.bchjs.Address.toCashAddress(address)
+
+      // Get transaction history for the address
+      const txHistory = await this.useCases.fulcrum.getTransactions({ address: cashAddr })
+
+      // Extract just the TXIDs
+      const txids = txHistory.transactions.map((elem) => elem.tx_hash)
+
+      // Throw error if there is no transaction history
+      if (!txids || txids.length === 0) {
+        throw new Error('No transaction history.')
+      }
+
+      // Loop through the transaction history and search for the public key
+      for (let i = 0; i < txids.length; i++) {
+        const thisTx = txids[i]
+
+        // Get verbose transaction details
+        const txDetails = await this.useCases.rawtransactions.getRawTransaction({
+          txid: thisTx,
+          verbose: true
+        })
+
+        const vin = txDetails.vin
+
+        // Loop through each input
+        for (let j = 0; j < vin.length; j++) {
+          const thisVin = vin[j]
+
+          // Skip if no scriptSig (e.g., coinbase transactions)
+          if (!thisVin.scriptSig || !thisVin.scriptSig.asm) {
+            continue
+          }
+
+          // Extract the script signature
+          const scriptSig = thisVin.scriptSig.asm.split(' ')
+
+          // Extract the public key from the script signature (last element)
+          const pubKey = scriptSig[scriptSig.length - 1]
+
+          // Skip if pubKey is not a valid hex string (basic validation)
+          if (!pubKey || !/^[0-9a-fA-F]+$/.test(pubKey)) {
+            continue
+          }
+
+          try {
+            // Generate cash address from public key
+            const keyBuf = Buffer.from(pubKey, 'hex')
+            const ec = this.bchjs.ECPair.fromPublicKey(keyBuf)
+            const cashAddr2 = this.bchjs.ECPair.toCashAddress(ec)
+
+            // If public keys match, this is the correct public key
+            if (cashAddr === cashAddr2) {
+              return {
+                success: true,
+                publicKey: pubKey
+              }
+            }
+          } catch (err) {
+            // Skip invalid public keys - continue searching
+            continue
+          }
+        }
+      }
+
+      // Public key not found in any transaction
+      return {
+        success: false,
+        publicKey: 'not found'
+      }
+    } catch (err) {
+      wlogger.error('Error in EncryptionUseCases.getPublicKey()', err)
+      throw err
+    }
+  }
+}
+
+export default EncryptionUseCases

src/use-cases/fulcrum-use-cases.js

@@ -4,8 +4,17 @@
 
 import wlogger from '../adapters/wlogger.js'
 import BCHJS from '@psf/bch-js'
+import config from '../config/index.js'
 
-const bchjs = new BCHJS()
+// Use RESTURL (from test) or REST_URL (from psf-bch-api config) or fallback to config
+const restURL = process.env.RESTURL || process.env.REST_URL || process.env.LOCAL_RESTURL || config.restURL
+// Use BCHJSBEARERTOKEN (from test) or BASIC_AUTH_TOKEN (from psf-bch-api config) or fallback to config
+const bearerToken = process.env.BCHJSBEARERTOKEN || process.env.BASIC_AUTH_TOKEN || config.basicAuth.token
+
+const bchjs = new BCHJS({
+  restURL,
+  bearerToken
+})
 
 class FulcrumUseCases {
   constructor (localConfig = {}) {
@@ -53,7 +62,9 @@ class FulcrumUseCases {
   }
 
   async getTransactionDetails ({ txid }) {
-    return this.fulcrum.get(`electrumx/tx/data/${txid}`)
+    const response = await this.fulcrum.get(`electrumx/tx/data/${txid}`)
+    // console.log(`getTransactionDetails() TXID ${txid}: ${JSON.stringify(response, null, 2)}`)
+    return response
   }
 
   async getTransactionDetailsBulk ({ txids, verbose }) {
@@ -90,13 +101,24 @@ class FulcrumUseCases {
     }
   }
 
-  async getTransactions ({ address, allTxs }) {
+  async getTransactions ({ address, allTxs, bearerToken = null }) {
     try {
       const response = await this.fulcrum.get(`electrumx/transactions/${address}`)
 
       // Sort transactions in descending order, so that newest transactions are first.
       if (response.transactions && Array.isArray(response.transactions)) {
-        response.transactions = await this.bchjs.Electrumx.sortAllTxs(response.transactions, 'DESCENDING')
+        // Use bearer token from request if provided, otherwise use the default bchjs instance
+        let bchjsInstance = this.bchjs
+        if (bearerToken) {
+          // Create a temporary bchjs instance with the bearer token from the request
+          const restURL = process.env.RESTURL || process.env.REST_URL || process.env.LOCAL_RESTURL || config.restURL
+          bchjsInstance = new BCHJS({
+            restURL,
+            bearerToken
+          })
+        }
+
+        response.transactions = await bchjsInstance.Electrumx.sortAllTxs(response.transactions, 'DESCENDING')
 
         if (!allTxs) {
           // Return only the first 100 transactions of the history.
@@ -111,16 +133,31 @@ class FulcrumUseCases {
     }
   }
 
-  async getTransactionsBulk ({ addresses, allTxs }) {
+  async getTransactionsBulk ({ addresses, allTxs, bearerToken = null }) {
     try {
       const response = await this.fulcrum.post('electrumx/transactions/', { addresses })
 
       // Sort transactions in descending order for each address entry.
       if (response.transactions && Array.isArray(response.transactions)) {
+        // Use bearer token from request if provided, otherwise use the default bchjs instance
+        let bchjsInstance = this.bchjs
+
+        // console.log('getTransactionsBulk() bearerToken: ', bearerToken)
+        if (bearerToken) {
+          // Create a temporary bchjs instance with the bearer token from the request
+          const restURL = config.restURL
+
+          // console.log('getTransactionsBulk() restURL: ', restURL)
+          bchjsInstance = new BCHJS({
+            restURL,
+            bearerToken
+          })
+        }
+
         for (let i = 0; i < response.transactions.length; i++) {
           const thisEntry = response.transactions[i]
           if (thisEntry.transactions && Array.isArray(thisEntry.transactions)) {
-            thisEntry.transactions = await this.bchjs.Electrumx.sortAllTxs(thisEntry.transactions, 'DESCENDING')
+            thisEntry.transactions = await bchjsInstance.Electrumx.sortAllTxs(thisEntry.transactions, 'DESCENDING')
 
             if (!allTxs && thisEntry.transactions.length > 100) {
               // Extract only the first 100 transactions.

src/use-cases/index.js

@@ -8,8 +8,10 @@
 import BlockchainUseCases from './full-node-blockchain-use-cases.js'
 import ControlUseCases from './full-node-control-use-cases.js'
 import DSProofUseCases from './full-node-dsproof-use-cases.js'
+import EncryptionUseCases from './encryption-use-cases.js'
 import FulcrumUseCases from './fulcrum-use-cases.js'
 import MiningUseCases from './full-node-mining-use-cases.js'
+import PriceUseCases from './price-use-cases.js'
 import RawTransactionsUseCases from './full-node-rawtransactions-use-cases.js'
 import SlpUseCases from './slp-use-cases.js'
 
@@ -27,8 +29,15 @@ class UseCases {
     this.dsproof = new DSProofUseCases({ adapters: this.adapters })
     this.fulcrum = new FulcrumUseCases({ adapters: this.adapters })
     this.mining = new MiningUseCases({ adapters: this.adapters })
+    this.price = new PriceUseCases({ adapters: this.adapters })
     this.rawtransactions = new RawTransactionsUseCases({ adapters: this.adapters })
     this.slp = new SlpUseCases({ adapters: this.adapters })
+
+    // Encryption use cases require access to other use cases (fulcrum, rawtransactions)
+    this.encryption = new EncryptionUseCases({
+      adapters: this.adapters,
+      useCases: this
+    })
   }
 
   // Run any startup Use Cases at the start of the app.

src/use-cases/price-use-cases.js

@@ -0,0 +1,140 @@
+/*
+  Use cases for price-related operations.
+*/
+
+// Global npm libraries
+import axios from 'axios'
+import SlpWallet from 'minimal-slp-wallet'
+import PSFFPP from 'psffpp'
+
+// Local libraries
+import wlogger from '../adapters/wlogger.js'
+import config from '../config/index.js'
+
+class PriceUseCases {
+  constructor (localConfig = {}) {
+    this.adapters = localConfig.adapters
+
+    if (!this.adapters) {
+      throw new Error('Adapters instance required when instantiating Price use cases.')
+    }
+
+    // Get config
+    this.config = localConfig.config || config
+
+    // Coinex API URL for BCH/USDT
+    this.bchCoinexPriceUrl =
+      'https://api.coinex.com/v1/market/ticker?market=bchusdt'
+
+    // Allow axios to be injected for testing
+    this.axios = localConfig.axios || axios
+
+    this.psfLiquidityPriceKeys = [
+      'usdPerBCH',
+      'bchBalance',
+      'tokenBalance',
+      'usdPerToken'
+    ]
+  }
+
+  /**
+   * Get the USD price of BCH from Coinex.
+   * @returns {Promise<number>} The USD price of BCH
+   */
+  async getBCHUSD () {
+    try {
+      // Request options
+      const opt = {
+        method: 'get',
+        baseURL: this.bchCoinexPriceUrl,
+        timeout: 15000
+      }
+
+      const response = await this.axios.request(opt)
+
+      const price = Number(response.data.data.ticker.last)
+
+      return price
+    } catch (err) {
+      wlogger.error('Error in PriceUseCases.getBCHUSD()', err)
+      throw err
+    }
+  }
+
+  /**
+   * Get the PSF price for writing to the PSFFPP.
+   * Returns the price to pin 1MB of content to the PSFFPP pinning
+   * network on IPFS. The price is denominated in PSF tokens.
+   * @returns {Promise<number>} The write price in PSF tokens
+   */
+  async getPsffppWritePrice () {
+    try {
+      const wallet = new SlpWallet(undefined, {
+        interface: 'rest-api',
+        restURL: this.config.restURL
+      })
+      await wallet.walletInfoPromise
+
+      const psffpp = new PSFFPP({ wallet })
+
+      const writePrice = await psffpp.getMcWritePrice()
+
+      return writePrice
+    } catch (err) {
+      wlogger.error('Error in PriceUseCases.getPsffppWritePrice()', err)
+      throw err
+    }
+  }
+
+  /**
+   * Proxies PSF token liquidity spot price from the token-liquidity app (GET /price).
+   * @returns {Promise<Object>} usdPerBCH, bchBalance, tokenBalance, usdPerToken
+   */
+  async getPsfLiquidityPrice () {
+    try {
+      const proxy = this.config.psfLiquidityProxy
+      if (!proxy || !proxy.enabled) {
+        const err = new Error('PSF liquidity price proxy is disabled')
+        err.status = 503
+        throw err
+      }
+
+      const baseUrl = String(proxy.baseUrl).replace(/\/$/, '')
+      const fullUrl = `${baseUrl}/price`
+
+      const opt = {
+        method: 'get',
+        url: fullUrl,
+        timeout: 15000
+      }
+
+      const response = await this.axios.request(opt)
+      const data = response.data
+
+      if (
+        !data ||
+        typeof data !== 'object' ||
+        Array.isArray(data) ||
+        !this.psfLiquidityPriceKeys.every(
+          (k) => typeof data[k] === 'number' && !Number.isNaN(data[k])
+        )
+      ) {
+        const err = new Error('Invalid response from PSF liquidity price service')
+        err.status = 502
+        throw err
+      }
+
+      return {
+        usdPerBCH: data.usdPerBCH,
+        bchBalance: data.bchBalance,
+        tokenBalance: data.tokenBalance,
+        usdPerToken: data.usdPerToken
+      }
+    } catch (err) {
+      wlogger.error('Error in PriceUseCases.getPsfLiquidityPrice()', err)
+      throw err
+    }
+  }
+}
+
+export default PriceUseCases

src/use-cases/slp-use-cases.js

@@ -9,7 +9,7 @@ import SlpTokenMedia from 'slp-token-media'
 import axios from 'axios'
 import config from '../config/index.js'
 
-const bchjs = new BCHJS()
+const bchjs = new BCHJS({ restURL: config.restURL })
 
 class SlpUseCases {
   constructor (localConfig = {}) {
@@ -98,7 +98,14 @@ class SlpUseCases {
     try {
       return await this.slpIndexer.post('slp/tx/', { txid })
     } catch (err) {
-      wlogger.error('Error in SlpUseCases.getTxid()', err)
+      const isCommonMissingTxError =
+        err?.status === 404 &&
+        typeof err?.message === 'string' &&
+        err.message.includes('Key not found in database')
+
+      if (!isCommonMissingTxError) {
+        wlogger.error('Error in SlpUseCases.getTxid()', err)
+      }
       throw err
     }
   }
@@ -259,6 +266,7 @@ class SlpUseCases {
 
       return mutableCid
     } catch (err) {
+      console.log('Error in SlpUseCases.getMutableCid()', err)
       wlogger.error('Error in SlpUseCases.getMutableCid()', err)
       return false
     }
@@ -271,7 +279,9 @@ class SlpUseCases {
       }
 
       // Get transaction data
+      console.log('Decoding OP_RETURN for TXID: ', txid)
       const txData = await this.bchjs.Electrumx.txData(txid)
+      // console.log(`TXID ${txid}: ${JSON.stringify(txData, null, 2)}`)
       let data = false
 
       // Map the vout of the transaction in search of an OP_RETURN
@@ -291,6 +301,7 @@ class SlpUseCases {
 
       return data
     } catch (error) {
+      console.log('Error in SlpUseCases.decodeOpReturn()', error)
       wlogger.error('Error in SlpUseCases.decodeOpReturn()', error)
       throw error
     }

test/unit/adapters/full-node-rpc-unit.js

@@ -26,6 +26,9 @@ describe('#full-node-rpc.js', () => {
   beforeEach(() => {
     sandbox = sinon.createSandbox()
     mockAxiosInstance = {
+      defaults: {
+        baseURL: baseConfig.fullNode.rpcBaseUrl
+      },
       post: sandbox.stub()
     }
     axiosCreateStub = sandbox.stub(axios, 'create').returns(mockAxiosInstance)

test/unit/controllers/discovery-controller-unit.js

@@ -0,0 +1,106 @@
+/*
+  Unit tests for DiscoveryController.
+*/
+
+import { assert } from 'chai'
+
+import DiscoveryController from '../../../src/controllers/discovery/controller.js'
+import { createMockRequest, createMockResponse } from '../mocks/controller-mocks.js'
+
+describe('#discovery-controller.js', () => {
+  const makeController = ({ enabled = true } = {}) => {
+    return new DiscoveryController({
+      apiPrefix: '/v6',
+      getX402Settings: () => ({
+        enabled,
+        facilitatorUrl: 'http://localhost:4345/facilitator',
+        serverAddress: 'bitcoincash:qtestaddress',
+        priceSat: 200
+      }),
+      getDiscoveryDocuments: () => ({
+        openapi: { openapi: '3.0.3', paths: { '/v6/price/bchusd': {} } },
+        swagger: { swagger: '2.0', paths: { '/v6/price/bchusd': {} } },
+        llms: '# psf-bch-api',
+        agent: { awp_version: '0.1', actions: [] }
+      })
+    })
+  }
+
+  describe('x402 disabled gating', () => {
+    it('should return 404 for all discovery endpoints when x402 disabled', async () => {
+      const uut = makeController({ enabled: false })
+      const req = createMockRequest()
+
+      const handlers = [
+        uut.x402Manifest,
+        uut.openapi,
+        uut.swagger,
+        uut.llmsTxt,
+        uut.agentManifest
+      ]
+
+      for (const handler of handlers) {
+        const res = createMockResponse()
+        await handler(req, res)
+        assert.equal(res.statusValue, 404)
+        assert.deepEqual(res.jsonData, { error: 'Not found' })
+      }
+    })
+  })
+
+  describe('x402 enabled responses', () => {
+    it('should return x402 manifest schema fields', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.x402Manifest(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.equal(res.jsonData.x402Version, 2)
+      assert.isArray(res.jsonData.resources)
+      assert.equal(res.jsonData.resources[0].accepts[0].scheme, 'utxo')
+      assert.equal(res.jsonData.resources[0].accepts[0].amount, '200')
+    })
+
+    it('should return openapi and swagger docs', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+
+      const openapiRes = createMockResponse()
+      await uut.openapi(req, openapiRes)
+      assert.equal(openapiRes.statusValue, 200)
+      assert.equal(openapiRes.jsonData.openapi, '3.0.3')
+
+      const swaggerRes = createMockResponse()
+      await uut.swagger(req, swaggerRes)
+      assert.equal(swaggerRes.statusValue, 200)
+      assert.equal(swaggerRes.jsonData.swagger, '2.0')
+    })
+
+    it('should return llms.txt as text/plain', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.llmsTxt(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.equal(res.headers['Content-Type'], 'text/plain; charset=utf-8')
+      assert.equal(res.writeData[0], '# psf-bch-api')
+      assert.isTrue(res.endCalled)
+    })
+
+    it('should return agent manifest json', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.agentManifest(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.equal(res.jsonData.awp_version, '0.1')
+      assert.isArray(res.jsonData.actions)
+    })
+  })
+})

test/unit/controllers/discovery-documents-unit.js

@@ -0,0 +1,25 @@
+/*
+  Unit tests for discovery document builder.
+*/
+
+import { assert } from 'chai'
+
+import { buildDiscoveryDocuments } from '../../../src/discovery/build-documents.js'
+
+describe('#discovery-build-documents.js', () => {
+  it('should build openapi and swagger documents with v6 paths', () => {
+    const docs = buildDiscoveryDocuments()
+
+    assert.property(docs, 'openapi')
+    assert.property(docs, 'swagger')
+    assert.property(docs, 'llms')
+    assert.property(docs, 'agent')
+
+    assert.isString(docs.openapi.openapi)
+    assert.equal(docs.swagger.swagger, '2.0')
+    assert.isAbove(Object.keys(docs.openapi.paths).length, 0)
+
+    const hasV6Path = Object.keys(docs.openapi.paths).some(path => path.startsWith('/v6/'))
+    assert.isTrue(hasV6Path)
+  })
+})

test/unit/controllers/discovery-router-unit.js

@@ -0,0 +1,43 @@
+/*
+  Unit tests for DiscoveryRouter.
+*/
+
+import { assert } from 'chai'
+
+import DiscoveryRouter from '../../../src/controllers/discovery/router.js'
+
+describe('#discovery-router.js', () => {
+  it('should require app object in attach()', () => {
+    const uut = new DiscoveryRouter()
+    assert.throws(() => uut.attach(), /Must pass app object/)
+  })
+
+  it('should register all discovery routes', () => {
+    const calls = []
+    const app = {
+      use: () => {}
+    }
+
+    const mockRouter = {
+      get: (path, handler) => calls.push({ path, handler })
+    }
+
+    const mockController = {
+      x402Manifest: () => {},
+      openapi: () => {},
+      swagger: () => {},
+      llmsTxt: () => {},
+      agentManifest: () => {}
+    }
+
+    const uut = new DiscoveryRouter({ controller: mockController })
+    uut.router = mockRouter
+    uut.attach(app)
+
+    assert.equal(calls.length, 5)
+    assert.deepEqual(
+      calls.map(x => x.path),
+      ['/.well-known/x402', '/openapi.json', '/swagger.json', '/llms.txt', '/.well-known/agent.json']
+    )
+  })
+})

test/unit/controllers/encryption-controller-unit.js

@@ -0,0 +1,203 @@
+/*
+  Unit tests for EncryptionRESTController.
+*/
+
+import { assert } from 'chai'
+import sinon from 'sinon'
+
+import EncryptionRESTController from '../../../src/controllers/rest-api/encryption/controller.js'
+import { createMockRequest, createMockResponse, createMockRequestWithParams } from '../mocks/controller-mocks.js'
+
+describe('#encryption-controller.js', () => {
+  let sandbox
+  let mockAdapters
+  let mockUseCases
+  let uut
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox()
+    mockAdapters = {}
+    mockUseCases = {
+      encryption: {
+        getPublicKey: sandbox.stub().resolves({
+          success: true,
+          publicKey: '02abc123def456789'
+        })
+      }
+    }
+
+    uut = new EncryptionRESTController({
+      adapters: mockAdapters,
+      useCases: mockUseCases
+    })
+  })
+
+  afterEach(() => {
+    sandbox.restore()
+  })
+
+  describe('#constructor()', () => {
+    it('should require adapters', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new EncryptionRESTController({ useCases: mockUseCases })
+      }, /Adapters library required/)
+    })
+
+    it('should require encryption use cases', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new EncryptionRESTController({ adapters: mockAdapters, useCases: {} })
+      }, /Encryption use cases required/)
+    })
+  })
+
+  describe('#root()', () => {
+    it('should return encryption status', async () => {
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.root(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, { status: 'encryption' })
+    })
+  })
+
+  describe('#getPublicKey()', () => {
+    it('should return public key on success', async () => {
+      const req = createMockRequestWithParams({
+        address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf'
+      })
+      const res = createMockResponse()
+
+      await uut.getPublicKey(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, {
+        success: true,
+        publicKey: '02abc123def456789'
+      })
+      assert.isTrue(mockUseCases.encryption.getPublicKey.calledOnce)
+      assert.isTrue(mockUseCases.encryption.getPublicKey.calledWith({
+        address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf'
+      }))
+    })
+
+    it('should return not found when public key is not found', async () => {
+      mockUseCases.encryption.getPublicKey.resolves({
+        success: false,
+        publicKey: 'not found'
+      })
+
+      const req = createMockRequestWithParams({
+        address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf'
+      })
+      const res = createMockResponse()
+
+      await uut.getPublicKey(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        publicKey: 'not found'
+      })
+    })
+
+    it('should reject array addresses', async () => {
+      const req = createMockRequestWithParams({
+        address: ['addr1', 'addr2']
+      })
+      const res = createMockResponse()
+
+      await uut.getPublicKey(req, res)
+
+      assert.equal(res.statusValue, 400)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        error: 'address can not be an array.'
+      })
+      assert.isFalse(mockUseCases.encryption.getPublicKey.called)
+    })
+
+    it('should reject missing address', async () => {
+      const req = createMockRequestWithParams({})
+      const res = createMockResponse()
+
+      await uut.getPublicKey(req, res)
+
+      assert.equal(res.statusValue, 400)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        error: 'address is required.'
+      })
+      assert.isFalse(mockUseCases.encryption.getPublicKey.called)
+    })
+
+    it('should handle errors via handleError', async () => {
+      const error = new Error('No transaction history.')
+      error.status = 400
+      mockUseCases.encryption.getPublicKey.rejects(error)
+
+      const req = createMockRequestWithParams({
+        address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf'
+      })
+      const res = createMockResponse()
+
+      await uut.getPublicKey(req, res)
+
+      assert.equal(res.statusValue, 400)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        error: 'No transaction history.'
+      })
+    })
+
+    it('should default to 500 status for errors without status', async () => {
+      const error = new Error('Internal error')
+      mockUseCases.encryption.getPublicKey.rejects(error)
+
+      const req = createMockRequestWithParams({
+        address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf'
+      })
+      const res = createMockResponse()
+
+      await uut.getPublicKey(req, res)
+
+      assert.equal(res.statusValue, 500)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        error: 'Internal error'
+      })
+    })
+  })
+
+  describe('#handleError()', () => {
+    it('should use error status and message when provided', () => {
+      const error = new Error('Custom error')
+      error.status = 422
+      const res = createMockResponse()
+
+      uut.handleError(error, res)
+
+      assert.equal(res.statusValue, 422)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        error: 'Custom error'
+      })
+    })
+
+    it('should default to 500 and Internal server error', () => {
+      const error = {}
+      const res = createMockResponse()
+
+      uut.handleError(error, res)
+
+      assert.equal(res.statusValue, 500)
+      assert.deepEqual(res.jsonData, {
+        success: false,
+        error: 'Internal server error'
+      })
+    })
+  })
+})

test/unit/controllers/price-controller-unit.js

@@ -0,0 +1,153 @@
+/*
+  Unit tests for PriceRESTController.
+*/
+
+import { assert } from 'chai'
+import sinon from 'sinon'
+
+import PriceRESTController from '../../../src/controllers/rest-api/price/controller.js'
+import { createMockRequest, createMockResponse } from '../mocks/controller-mocks.js'
+
+describe('#price-controller.js', () => {
+  let sandbox
+  let mockAdapters
+  let mockUseCases
+  let uut
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox()
+    mockAdapters = {}
+    mockUseCases = {
+      price: {
+        getBCHUSD: sandbox.stub().resolves(250.5),
+        getPsffppWritePrice: sandbox.stub().resolves(0.08335233),
+        getPsfLiquidityPrice: sandbox.stub().resolves({
+          usdPerBCH: 483.1,
+          bchBalance: 25.65337297,
+          tokenBalance: 39590.96686314,
+          usdPerToken: 0.50532753
+        })
+      }
+    }
+
+    uut = new PriceRESTController({
+      adapters: mockAdapters,
+      useCases: mockUseCases
+    })
+  })
+
+  afterEach(() => {
+    sandbox.restore()
+  })
+
+  describe('#constructor()', () => {
+    it('should require adapters', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new PriceRESTController({ useCases: mockUseCases })
+      }, /Adapters library required/)
+    })
+
+    it('should require price use cases', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new PriceRESTController({ adapters: mockAdapters, useCases: {} })
+      }, /Price use cases required/)
+    })
+  })
+
+  describe('#root()', () => {
+    it('should return price status', async () => {
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.root(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, { status: 'price' })
+    })
+  })
+
+  describe('#getBCHUSD()', () => {
+    it('should return BCH USD price on success', async () => {
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.getBCHUSD(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, { usd: 250.5 })
+      assert.isTrue(mockUseCases.price.getBCHUSD.calledOnce)
+    })
+
+    it('should handle errors via handleError', async () => {
+      const error = new Error('API failure')
+      error.status = 503
+      mockUseCases.price.getBCHUSD.rejects(error)
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.getBCHUSD(req, res)
+
+      assert.equal(res.statusValue, 503)
+      assert.deepEqual(res.jsonData, { error: 'API failure' })
+    })
+  })
+
+  describe('#getPsffppWritePrice()', () => {
+    it('should return PSFFPP write price on success', async () => {
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.getPsffppWritePrice(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, { writePrice: 0.08335233 })
+      assert.isTrue(mockUseCases.price.getPsffppWritePrice.calledOnce)
+    })
+
+    it('should handle errors via handleError', async () => {
+      const error = new Error('PSFFPP failure')
+      error.status = 500
+      mockUseCases.price.getPsffppWritePrice.rejects(error)
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.getPsffppWritePrice(req, res)
+
+      assert.equal(res.statusValue, 500)
+      assert.deepEqual(res.jsonData, { error: 'PSFFPP failure' })
+    })
+  })
+
+  describe('#getPsfLiquidityPrice()', () => {
+    it('should return PSF liquidity price payload on success', async () => {
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.getPsfLiquidityPrice(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.deepEqual(res.jsonData, {
+        usdPerBCH: 483.1,
+        bchBalance: 25.65337297,
+        tokenBalance: 39590.96686314,
+        usdPerToken: 0.50532753
+      })
+      assert.isTrue(mockUseCases.price.getPsfLiquidityPrice.calledOnce)
+    })
+
+    it('should handle errors via handleError', async () => {
+      const error = new Error('proxy off')
+      error.status = 503
+      mockUseCases.price.getPsfLiquidityPrice.rejects(error)
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.getPsfLiquidityPrice(req, res)
+
+      assert.equal(res.statusValue, 503)
+      assert.deepEqual(res.jsonData, { error: 'proxy off' })
+    })
+  })
+})

test/unit/controllers/rest-api-index-unit.js

@@ -9,7 +9,9 @@ import RESTControllers from '../../../src/controllers/rest-api/index.js'
 import BlockchainRouter from '../../../src/controllers/rest-api/full-node/blockchain/router.js'
 import ControlRouter from '../../../src/controllers/rest-api/full-node/control/router.js'
 import DSProofRouter from '../../../src/controllers/rest-api/full-node/dsproof/router.js'
+import EncryptionRouter from '../../../src/controllers/rest-api/encryption/router.js'
 import MiningRouter from '../../../src/controllers/rest-api/full-node/mining/router.js'
+import PriceRouter from '../../../src/controllers/rest-api/price/router.js'
 import RawTransactionsRouter from '../../../src/controllers/rest-api/full-node/rawtransactions/router.js'
 import FulcrumRouter from '../../../src/controllers/rest-api/fulcrum/router.js'
 import SlpRouter from '../../../src/controllers/rest-api/slp/router.js'
@@ -75,6 +77,10 @@ describe('#controllers/rest-api/index.js', () => {
         getMiningInfo: () => {},
         getNetworkHashPS: () => {}
       },
+      price: {
+        getBCHUSD: () => {},
+        getPsffppWritePrice: () => {}
+      },
       rawtransactions: {
         decodeRawTransaction: () => {},
         decodeRawTransactions: () => {},
@@ -95,6 +101,9 @@ describe('#controllers/rest-api/index.js', () => {
         getMutableCid: () => {},
         decodeOpReturn: () => {},
         getCIDData: () => {}
+      },
+      encryption: {
+        getPublicKey: () => {}
       }
     }
   })
@@ -124,8 +133,10 @@ describe('#controllers/rest-api/index.js', () => {
       const blockchainAttachStub = sandbox.stub(BlockchainRouter.prototype, 'attach')
       const controlAttachStub = sandbox.stub(ControlRouter.prototype, 'attach')
       const dsproofAttachStub = sandbox.stub(DSProofRouter.prototype, 'attach')
+      const encryptionAttachStub = sandbox.stub(EncryptionRouter.prototype, 'attach')
       const fulcrumAttachStub = sandbox.stub(FulcrumRouter.prototype, 'attach')
       const miningAttachStub = sandbox.stub(MiningRouter.prototype, 'attach')
+      const priceAttachStub = sandbox.stub(PriceRouter.prototype, 'attach')
       const rawtransactionsAttachStub = sandbox.stub(RawTransactionsRouter.prototype, 'attach')
       const slpAttachStub = sandbox.stub(SlpRouter.prototype, 'attach')
       const restControllers = new RESTControllers({
@@ -142,10 +153,14 @@ describe('#controllers/rest-api/index.js', () => {
       assert.equal(controlAttachStub.getCall(0).args[0], app)
       assert.isTrue(dsproofAttachStub.calledOnce)
       assert.equal(dsproofAttachStub.getCall(0).args[0], app)
+      assert.isTrue(encryptionAttachStub.calledOnce)
+      assert.equal(encryptionAttachStub.getCall(0).args[0], app)
       assert.isTrue(fulcrumAttachStub.calledOnce)
       assert.equal(fulcrumAttachStub.getCall(0).args[0], app)
       assert.isTrue(miningAttachStub.calledOnce)
       assert.equal(miningAttachStub.getCall(0).args[0], app)
+      assert.isTrue(priceAttachStub.calledOnce)
+      assert.equal(priceAttachStub.getCall(0).args[0], app)
       assert.isTrue(rawtransactionsAttachStub.calledOnce)
       assert.equal(rawtransactionsAttachStub.getCall(0).args[0], app)
       assert.isTrue(slpAttachStub.calledOnce)

test/unit/use-cases/encryption-use-cases-unit.js

@@ -0,0 +1,247 @@
+/*
+  Unit tests for EncryptionUseCases.
+*/
+
+import { assert } from 'chai'
+import sinon from 'sinon'
+
+import EncryptionUseCases from '../../../src/use-cases/encryption-use-cases.js'
+
+describe('#encryption-use-cases.js', () => {
+  let sandbox
+  let mockAdapters
+  let mockUseCases
+  let mockBchjs
+  let uut
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox()
+    mockAdapters = {}
+
+    // Mock bchjs
+    mockBchjs = {
+      Address: {
+        toCashAddress: sandbox.stub().returns('bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf')
+      },
+      ECPair: {
+        fromPublicKey: sandbox.stub().returns({}),
+        toCashAddress: sandbox.stub().returns('bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf')
+      }
+    }
+
+    // Mock use cases
+    mockUseCases = {
+      fulcrum: {
+        getTransactions: sandbox.stub().resolves({
+          transactions: [
+            { tx_hash: 'abc123def456' }
+          ]
+        })
+      },
+      rawtransactions: {
+        getRawTransaction: sandbox.stub().resolves({
+          vin: [
+            {
+              scriptSig: {
+                asm: 'signature 02abc123def456789'
+              }
+            }
+          ]
+        })
+      }
+    }
+
+    uut = new EncryptionUseCases({
+      adapters: mockAdapters,
+      useCases: mockUseCases,
+      bchjs: mockBchjs
+    })
+  })
+
+  afterEach(() => {
+    sandbox.restore()
+  })
+
+  describe('#constructor()', () => {
+    it('should require adapters', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new EncryptionUseCases({ useCases: mockUseCases })
+      }, /Adapters instance required/)
+    })
+
+    it('should require useCases', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new EncryptionUseCases({ adapters: mockAdapters })
+      }, /UseCases instance required/)
+    })
+  })
+
+  describe('#getPublicKey()', () => {
+    it('should return public key when found', async () => {
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isTrue(result.success)
+      assert.equal(result.publicKey, '02abc123def456789')
+      assert.isTrue(mockBchjs.Address.toCashAddress.calledOnce)
+      assert.isTrue(mockUseCases.fulcrum.getTransactions.calledOnce)
+      assert.isTrue(mockUseCases.rawtransactions.getRawTransaction.calledOnce)
+    })
+
+    it('should return not found when public key does not match', async () => {
+      // Make the ECPair.toCashAddress return a different address
+      mockBchjs.ECPair.toCashAddress.returns('bitcoincash:qqq000000000000000000000000000000000000000')
+
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isFalse(result.success)
+      assert.equal(result.publicKey, 'not found')
+    })
+
+    it('should throw error when no transaction history', async () => {
+      mockUseCases.fulcrum.getTransactions.resolves({
+        transactions: []
+      })
+
+      try {
+        await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.message, 'No transaction history.')
+      }
+    })
+
+    it('should handle transactions without scriptSig', async () => {
+      mockUseCases.rawtransactions.getRawTransaction.resolves({
+        vin: [
+          { txid: 'coinbase' } // No scriptSig
+        ]
+      })
+
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isFalse(result.success)
+      assert.equal(result.publicKey, 'not found')
+    })
+
+    it('should handle invalid public key hex gracefully', async () => {
+      mockUseCases.rawtransactions.getRawTransaction.resolves({
+        vin: [
+          {
+            scriptSig: {
+              asm: 'signature NOT_VALID_HEX'
+            }
+          }
+        ]
+      })
+
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isFalse(result.success)
+      assert.equal(result.publicKey, 'not found')
+    })
+
+    it('should handle ECPair.fromPublicKey throwing error', async () => {
+      mockBchjs.ECPair.fromPublicKey.throws(new Error('Invalid public key'))
+
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isFalse(result.success)
+      assert.equal(result.publicKey, 'not found')
+    })
+
+    it('should search through multiple transactions', async () => {
+      // First transaction has no matching public key
+      mockUseCases.fulcrum.getTransactions.resolves({
+        transactions: [
+          { tx_hash: 'tx1' },
+          { tx_hash: 'tx2' }
+        ]
+      })
+
+      // Return different data for each tx - first tx has input with non-matching key
+      mockUseCases.rawtransactions.getRawTransaction
+        .onFirstCall().resolves({
+          vin: [
+            {
+              scriptSig: {
+                asm: 'sig 02aaa111bbb222ccc'
+              }
+            }
+          ]
+        })
+        .onSecondCall().resolves({
+          vin: [
+            {
+              scriptSig: {
+                asm: 'sig 02abc123def456789'
+              }
+            }
+          ]
+        })
+
+      // First tx doesn't match, second tx matches
+      mockBchjs.ECPair.toCashAddress
+        .onFirstCall().returns('bitcoincash:qqq000000000000000000000000000000000000000')
+        .onSecondCall().returns('bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf')
+
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isTrue(result.success)
+      assert.equal(result.publicKey, '02abc123def456789')
+      assert.equal(mockUseCases.rawtransactions.getRawTransaction.callCount, 2)
+    })
+
+    it('should search through multiple inputs in a transaction', async () => {
+      mockUseCases.rawtransactions.getRawTransaction.resolves({
+        vin: [
+          {
+            scriptSig: {
+              asm: 'sig 02aaa111bbb222ccc'
+            }
+          },
+          {
+            scriptSig: {
+              asm: 'sig 02abc123def456789'
+            }
+          }
+        ]
+      })
+
+      // First input doesn't match, second input matches
+      mockBchjs.ECPair.toCashAddress
+        .onFirstCall().returns('bitcoincash:qqq000000000000000000000000000000000000000')
+        .onSecondCall().returns('bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf')
+
+      const result = await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+
+      assert.isTrue(result.success)
+      assert.equal(result.publicKey, '02abc123def456789')
+    })
+
+    it('should propagate fulcrum errors', async () => {
+      const error = new Error('Fulcrum API error')
+      mockUseCases.fulcrum.getTransactions.rejects(error)
+
+      try {
+        await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.message, 'Fulcrum API error')
+      }
+    })
+
+    it('should propagate rawtransactions errors', async () => {
+      const error = new Error('RawTransactions API error')
+      mockUseCases.rawtransactions.getRawTransaction.rejects(error)
+
+      try {
+        await uut.getPublicKey({ address: 'bitcoincash:qrdka2205f4hyukutc2g0s6lykperc8nsu5u2ddpqf' })
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.message, 'RawTransactions API error')
+      }
+    })
+  })
+})

test/unit/use-cases/fulcrum-use-cases-unit.js

@@ -24,7 +24,7 @@ describe('#fulcrum-use-cases.js', () => {
     }
 
     // Create a mock BCHJS instance with stubbed sortAllTxs method
-    const mockBchjs = new BCHJS()
+    const mockBchjs = new BCHJS({ restURL: 'http://localhost:5942/v6/' })
     if (!mockBchjs.Electrumx) {
       mockBchjs.Electrumx = {}
     }

test/unit/use-cases/price-use-cases-unit.js

@@ -0,0 +1,199 @@
+/*
+  Unit tests for PriceUseCases.
+*/
+
+import { assert } from 'chai'
+import sinon from 'sinon'
+
+import PriceUseCases from '../../../src/use-cases/price-use-cases.js'
+
+describe('#price-use-cases.js', () => {
+  let sandbox
+  let mockAdapters
+  let mockAxios
+  let mockConfig
+  let uut
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox()
+    mockAdapters = {}
+
+    mockConfig = {
+      restURL: 'http://localhost:3000/v5/'
+    }
+
+    // Mock axios
+    mockAxios = {
+      request: sandbox.stub()
+    }
+
+    uut = new PriceUseCases({
+      adapters: mockAdapters,
+      axios: mockAxios,
+      config: mockConfig
+    })
+  })
+
+  afterEach(() => {
+    sandbox.restore()
+  })
+
+  describe('#constructor()', () => {
+    it('should require adapters', () => {
+      assert.throws(() => {
+        // eslint-disable-next-line no-new
+        new PriceUseCases()
+      }, /Adapters instance required/)
+    })
+  })
+
+  describe('#getBCHUSD()', () => {
+    it('should return BCH price from Coinex API', async () => {
+      const mockPrice = 250.5
+      mockAxios.request.resolves({
+        data: {
+          data: {
+            ticker: {
+              last: mockPrice.toString()
+            }
+          }
+        }
+      })
+
+      const result = await uut.getBCHUSD()
+
+      assert.equal(result, mockPrice)
+      assert.isTrue(mockAxios.request.calledOnce)
+      const callArgs = mockAxios.request.getCall(0).args[0]
+      assert.equal(callArgs.method, 'get')
+      assert.equal(callArgs.baseURL, 'https://api.coinex.com/v1/market/ticker?market=bchusdt')
+      assert.equal(callArgs.timeout, 15000)
+    })
+
+    it('should handle errors', async () => {
+      const error = new Error('API error')
+      mockAxios.request.rejects(error)
+
+      try {
+        await uut.getBCHUSD()
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.message, 'API error')
+      }
+    })
+  })
+
+  describe('#getPsfLiquidityPrice()', () => {
+    const validBody = {
+      usdPerBCH: 483.1,
+      bchBalance: 25.65337297,
+      tokenBalance: 39590.96686314,
+      usdPerToken: 0.50532753
+    }
+
+    it('should reject with 503 when proxy config is missing', async () => {
+      try {
+        await uut.getPsfLiquidityPrice()
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.status, 503)
+        assert.include(err.message, 'disabled')
+      }
+    })
+
+    it('should reject with 503 when proxy is disabled', async () => {
+      mockConfig.psfLiquidityProxy = {
+        enabled: false,
+        baseUrl: 'http://192.168.0.126:5000'
+      }
+
+      try {
+        await uut.getPsfLiquidityPrice()
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.status, 503)
+        assert.include(err.message, 'disabled')
+      }
+    })
+
+    it('should return payload when enabled and upstream returns valid JSON', async () => {
+      mockConfig.psfLiquidityProxy = {
+        enabled: true,
+        baseUrl: 'http://192.168.0.126:5000'
+      }
+      mockAxios.request.resolves({ data: { ...validBody } })
+
+      const result = await uut.getPsfLiquidityPrice()
+
+      assert.deepEqual(result, validBody)
+      assert.isTrue(mockAxios.request.calledOnce)
+      const callArgs = mockAxios.request.getCall(0).args[0]
+      assert.equal(callArgs.method, 'get')
+      assert.equal(callArgs.url, 'http://192.168.0.126:5000/price')
+      assert.equal(callArgs.timeout, 15000)
+    })
+
+    it('should normalize base URL trailing slash before /price', async () => {
+      mockConfig.psfLiquidityProxy = {
+        enabled: true,
+        baseUrl: 'http://example.com:5000/'
+      }
+      mockAxios.request.resolves({ data: { ...validBody } })
+
+      await uut.getPsfLiquidityPrice()
+
+      const callArgs = mockAxios.request.getCall(0).args[0]
+      assert.equal(callArgs.url, 'http://example.com:5000/price')
+    })
+
+    it('should reject with 502 when upstream body is invalid', async () => {
+      mockConfig.psfLiquidityProxy = {
+        enabled: true,
+        baseUrl: 'http://192.168.0.126:5000'
+      }
+      mockAxios.request.resolves({ data: { usdPerBCH: 'not-a-number' } })
+
+      try {
+        await uut.getPsfLiquidityPrice()
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.status, 502)
+        assert.include(err.message, 'Invalid response')
+      }
+    })
+
+    it('should propagate axios errors', async () => {
+      mockConfig.psfLiquidityProxy = {
+        enabled: true,
+        baseUrl: 'http://192.168.0.126:5000'
+      }
+      const error = new Error('network down')
+      mockAxios.request.rejects(error)
+
+      try {
+        await uut.getPsfLiquidityPrice()
+        assert.fail('Should have thrown an error')
+      } catch (err) {
+        assert.equal(err.message, 'network down')
+      }
+    })
+  })
+
+  describe('#getPsffppWritePrice()', () => {
+    it('should handle errors properly', async () => {
+      // Note: Full unit testing of getPsffppWritePrice is difficult due to dynamic imports
+      // of SlpWallet and PSFFPP. Integration tests should verify the full flow.
+      // This test verifies that errors are properly handled and propagated.
+      try {
+        // This will likely fail in unit test environment without proper setup
+        // but we verify error handling works correctly
+        await uut.getPsffppWritePrice()
+        // If it succeeds, that's also acceptable
+      } catch (err) {
+        // Verify error is properly formatted
+        assert.isTrue(err instanceof Error)
+        // Verify error was logged (indirectly through wlogger)
+      }
+    })
+  })
+})

test/unit/use-cases/slp-use-cases-unit.js

@@ -32,7 +32,7 @@ describe('#slp-use-cases.js', () => {
     }
 
     // Create mock BCHJS
-    mockBchjs = new BCHJS()
+    mockBchjs = new BCHJS({ restURL: 'http://localhost:5942/v6/' })
     mockBchjs.Electrumx = {
       txData: sandbox.stub().resolves({
         details: {