Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]

### Added
- Run a Pubky Swaps provider on this stack's LND and Electrum (`pubky-swaps` profile) for the apps' swap route journeys
- Run a local Spark regtest network on this chain (`spark` profile, `./spark`): the last public Spark operators and the Spark service provider that matches them, patched for Spark SDK 0.28 wallets, mempool.space, and commands to stop operators, mine to timelock maturity, fund addresses and read an exit's on-chain state
- Deploy Bitkit's public regtest staging without Blocktank from `staging/`, replacing `*.stag0.blocktank.to`
- Add local Orchestra and LayerZero providers with bridge lifecycle controls, real Arbitrum credits/refunds and a Core bridge smoke suite
Expand Down
33 changes: 33 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ payment controls, proof verification, the optional Shop overlay and simulation l
- **Homegate**: Pubky Homeserver signup gatekeeper with local admin API mock
- **Pubky marketplace fixture** (opt-in `marketplace` profile): Pubky testnet, Paykit Server and a purchase driver for the marketplace wallet journey
- **Payment Request fixture** (opt-in `payment-requests` profile): rc8 issuer and controlled peer on the marketplace Pubky testnet
- **Pubky Swaps provider** (opt-in `pubky-swaps` profile): the swap route's counterparty on this stack's LND and Electrum, for the apps' swap route journeys
- **Spark regtest** (opt-in `spark` profile, `./spark`): Spark operators, the Spark service provider and mempool.space on this chain, for local Spark development, offline E2E and emergency-exit tests

## Quick Start
Expand Down Expand Up @@ -726,6 +727,38 @@ The `spark` profile runs a Spark network of your own on this chain: three Spark
4. Run `./spark mine` once per package, until the app waits for the timelock.
5. Run `./spark mature`, then `./spark mine` for the refunds and the sweep to Savings.

#### Pubky Swaps

The `pubky-swaps` profile runs a Pubky Swaps provider (`coreyphillips/pubky-swap` at `f45e204`, the commit bitkit-core's Pubky Swaps client pins) on this stack's LND and Electrum. It is the counterparty of the apps' swap route: a Spending-only wallet pays a contact's on-chain address by paying the provider's hold invoice over Lightning, and the provider pays the address on chain. The apps' journeys `paykit-swap-route.xml` (J1) and `paykit-swap-restore.xml` (J2) use it with the `marketplace` and `payment-requests` fixtures. They land in each app's `journeys/` with the swap route ([synonymdev/bitkit-ios#1170](https://github.com/synonymdev/bitkit-ios/pull/1170), [synonymdev/bitkit-android#1732](https://github.com/synonymdev/bitkit-android/pull/1732)).

```bash
docker compose up -d # chain, Electrum, LND, LNURL server
./bitcoin-cli fund # mature coins for the chain's wallet
./bitcoin-cli send 1 "$(docker compose exec -T lnd lncli --lnddir /home/lnd/.lnd --network regtest newaddress p2wkh | jq -r .address)" -m 6
docker compose --profile pubky-swaps up -d --build pubky-swap # first build takes a while
docker compose logs pubky-swap | grep "Provider pubky" # the provider's pubky: save it as a contact in the wallet
./pubky-marketplace up && ./pubky-marketplace seed # Pubky testnet and homeserver the apps sign up on
docker compose --profile marketplace --profile payment-requests up -d --no-build fixture-issuer rc56-peer
curl -s 127.0.0.1:23012/health | jq -r .pubky # the on-chain-only contact J1 pays
```

- **Provider.** It shares LND's network namespace, so it dials LND's gRPC on `127.0.0.1:10009` with the TLS cert and admin macaroon LND wrote to `./lnd`, and it waits for the macaroon on a fresh stack. It offers swaps of 10,000 to 1,000,000 sats (base fee 100 sats, 2,500 ppm, one confirmation) and runs with `--no-homeserver`, so a wallet finds it only among its contacts. Wallets reach it over iroh by its pubky, which needs outbound internet. Its throwaway Pubky identity is made on first start and kept in the `pubky_swap_data` volume, so the pubky survives restarts; remove the volume for a new one. Its claims and refunds go through LND's on-chain wallet, funded above.
- **Wallet.** Build the app with the marketplace fixture's homeserver (see [Pubky Marketplace Journey](#pubky-marketplace-journey)) and the swap route on (`PUBKY_SWAPS_ROUTES=true` on Android). Create a new wallet, open a 500,000-sat channel from `curl -H 'Host: 127.0.0.1:23010' 127.0.0.1:23010/generate/channel` (start the `lnurl-pay` fixture with `docker compose --profile lnurl-pay up -d --build --wait lnurl-server-fixture`), leave Savings empty, create a Pubky profile, and save the provider's and the `fixture-issuer`'s pubkys as contacts.
- **Issuer contact.** J1 pays the `fixture-issuer` as a saved contact, which needs the issuer linked to the wallet and holding the wallet's private payment list. After saving the contact, link the issuer to the wallet and sync until it reports the link, then send the wallet its payment list:

```bash
TO_APP=$(jq -nc --arg pubky "$APP_PUBKY" '{peer_pubky:$pubky,peer_path:"bitkit/wallet"}')
curl -fsS -X POST http://127.0.0.1:23012/link -H 'content-type: application/json' -d "$TO_APP" | jq
curl -fsS -X POST http://127.0.0.1:23012/sync -H 'content-type: application/json' -d "$TO_APP" | jq # repeat while the app advances its handshake
curl -fsS -X POST http://127.0.0.1:23012/endpoints -H 'content-type: application/json' -d "$(jq -c '. + {action:"restore"}' <<<"$TO_APP")" | jq # private_payment_list.sent is 1
```

Without the payment list, tapping the contact shows that it hasn't enabled payments.
- **Android emulator.** Run `adb reverse tcp:<port> tcp:<port>` for 6286, 6287, 6288, 15411, 15412, 60001, 23735, 23000 and 23010 before the first launch.
- **iOS simulator.** The `127.0.0.1` URLs work as they are.
- **Mining.** The provider's lockup confirms with `./bitcoin-cli mine 1`; the wallet's claim needs one more block.
- **Logs.** `docker compose logs -f pubky-swap` shows `hold invoice accepted`, `HTLC funded; awaiting client claim` and `client claimed; hold invoice settled` for a swap that completes.

#### Pubky Marketplace Journey

Use this section for the Bitkit marketplace wallet journey (`journeys/pubky-marketplace` in [bitkit-ios](https://github.com/synonymdev/bitkit-ios/tree/master/journeys/pubky-marketplace) and [bitkit-android](https://github.com/synonymdev/bitkit-android/tree/master/journeys/pubky-marketplace)). The `marketplace` profile adds the integration fixture that the journey lists: a Pubky testnet, Paykit Server `722ef268` (v0.1.0-rc4) with `/setup` and `x-bitkit-claim=watch-only-account-v1`, and a purchase driver. That revision emits the Pubky grant auth URL (`pubkyauth://signin_grant` with `cid` and `cpk`) that the apps' Paykit SDK (0.1.0-rc55) requires; the merge of [pubky/paykit-server#2](https://github.com/pubky/paykit-server/pull/2) (`867fc883`) emits the legacy URL, which the apps reject. It reuses this stack's regtest `bitcoind` and Electrum on `tcp://127.0.0.1:60001`. A plain `docker compose up -d` does not start it, and `./pubky-marketplace` starts only the chain and fixture services, so run it without the full stack. It needs Docker, `git`, `curl` and `jq` on the host, and outbound internet during the first build and during setup approval (see the setup relay note in [docs/pubky-marketplace.md](docs/pubky-marketplace.md)).
Expand Down
21 changes: 21 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -646,6 +646,26 @@ services:
FIXTURE_PORT: 3013
BITCOIN_RPC_URL: http://bitcoind:43782

# Pubky Swaps provider (profile "pubky-swaps"), the swap route's counterparty in the apps' J1 and J2 journeys: it takes a
# wallet's hold invoice on LND and pays the contact's address on chain. It shares LND's network namespace, so it dials LND's
# gRPC on 127.0.0.1 with the TLS cert LND wrote; the apps reach it over iroh by its pubky, which it logs on start. Its
# throwaway identity is made on first start and kept in the pubky_swap_data volume. See README "Pubky Swaps".
pubky-swap:
profiles: [pubky-swaps]
image: bitkit-docker/pubky-swap:${PUBKY_SWAP_TAG:-f45e204}
build:
context: ./pubky-swap
args:
PUBKY_SWAP_REV: ${PUBKY_SWAP_REV:-f45e204ee7646dc91983d90e4782d40760b6c72b}
restart: unless-stopped
network_mode: service:lnd
depends_on:
- lnd
- electrs
volumes:
- './lnd:/lnd:ro'
- 'pubky_swap_data:/data'

# ---------------------------------------------------------------------------
# Shop on staging with our own Paykit Server (profile "shop-mixed"). Paykit Server v0.1.0-rc11 (662dca06, paykit-rs ad3c7224 =
# v0.1.0-rc72, the version the Bitkit send-fix builds pin) resolves Pubky on mainnet, so it serves Synonym's staging homeserver,
Expand Down Expand Up @@ -1023,6 +1043,7 @@ volumes:
shop_mixed_postgres_data:
shop_mixed_state:
shop_order_postgres_data:
pubky_swap_data:

secrets:
usdt_upstream:
Expand Down
22 changes: 22 additions & 0 deletions pubky-swap/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
FROM rust:1.98.1-bookworm@sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e AS builder
# The LND backend compiles LND's protos.
RUN apt-get update && apt-get install -y --no-install-recommends protobuf-compiler \
&& rm -rf /var/lib/apt/lists/*
# The pubky-swap commit bitkit-core's Pubky Swaps client pins (swap-common in its Cargo.toml).
ARG PUBKY_SWAP_REV=f45e204ee7646dc91983d90e4782d40760b6c72b
WORKDIR /usr/src/pubky-swap
RUN git init -q . && git fetch -q --depth 1 https://github.com/coreyphillips/pubky-swap "$PUBKY_SWAP_REV" \
&& git checkout -q FETCH_HEAD
# No cache mounts: the QA boxes build without BuildKit, and this image is built rarely.
RUN cargo build --release --locked -p swap-provider --features full \
&& install -Dm755 target/release/swap-provider /out/swap-provider
COPY keygen /usr/src/keygen
RUN cd /usr/src/keygen && cargo build --release --locked \
&& install -Dm755 target/release/pubky-swap-keygen /out/pubky-swap-keygen

FROM debian:bookworm-slim@sha256:3783cc01769c7b2b1b83a5c5ad96c815348e28ed7da68e2e3687004faa906251
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /out/ /usr/local/bin/
COPY entrypoint.sh /usr/local/bin/pubky-swap-entrypoint
ENTRYPOINT ["/usr/local/bin/pubky-swap-entrypoint"]
36 changes: 36 additions & 0 deletions pubky-swap/entrypoint.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
#!/bin/sh
# Runs the Pubky Swaps provider on bitkit-docker's LND and Electrum. Its Pubky identity is a throwaway phrase made on first
# start and kept in the data volume, so the pubky the apps save as a contact survives restarts.
set -eu
phrase=/data/recovery-phrase
if [ ! -s "$phrase" ]; then
umask 077
pubky-swap-keygen > "$phrase"
fi
export PUBKY_SWAP_RECOVERY_PHRASE__FILE="$phrase"
macaroon=/lnd/data/chain/bitcoin/regtest/admin.macaroon
until [ -s "$macaroon" ]; do
echo "waiting for LND's macaroon"
sleep 2
done
# the provider connects to Electrum once at startup, and runs without its chain watcher if Electrum is not up yet
until bash -c 'exec 3<>/dev/tcp/electrs/60001' 2>/dev/null; do
echo "waiting for Electrum"
sleep 2
done
exec swap-provider \
--network regtest \
--directions submarine,reverse \
--min-amount 10000 \
--max-amount 1000000 \
--base-fee 100 \
--fee-ppm 2500 \
--confirmations 1 \
--wallet lnd \
--lnd-address https://127.0.0.1:10009 \
--lnd-cert /lnd/tls.cert \
--lnd-macaroon "$macaroon" \
--electrum-url tcp://electrs:60001 \
--data-dir /data \
--no-homeserver \
"$@"
225 changes: 225 additions & 0 deletions pubky-swap/keygen/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 8 additions & 0 deletions pubky-swap/keygen/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[package]
name = "pubky-swap-keygen"
version = "0.1.0"
edition = "2021"
publish = false

[dependencies]
bip39 = { version = "2.2", features = ["rand"] }
4 changes: 4 additions & 0 deletions pubky-swap/keygen/src/main.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
//! Prints a fresh 12-word BIP39 phrase: the regtest provider's throwaway Pubky identity.
fn main() {
println!("{}", bip39::Mnemonic::generate(12).expect("12 words is a valid length"));
}