archipelagoandClaude Fable 5
2277fc4684
A Minibits token could not be redeemed on framework-pt: the mint answered POST /v1/swap with a bare 422, which the RPC sanitizer turned into "Operation failed. Check server logs for details." The journal had the real reason: inputs[0].id: NUT02: ID length invalid, expected 8 bytes (short/v1) or 33 bytes (v2) The token carried keyset id 01fc0ec0e59cd6fa — exactly the first 8 bytes of the mint's active 33-byte id 01fc0ec0e59cd6fa01b7a88f…a821. NUT-02 v2 ids are 33 bytes behind a 0x01 version byte; the sending wallet cut it to the 8 bytes that were the whole id under v1. The mint reads the version, expects 33 bytes, and rejects it — so the length complaint is right even though 8 bytes is legal for a 0x00-prefixed v1 id. The id only names which keyset signed a proof, and the short form is a prefix of the full one, so it can be repaired: before swapping, any 8-byte 0x01-prefixed id is expanded against GET /v1/keysets (new MintClient::get_keysets — it lists inactive keysets too, and coins from a retired keyset stay spendable). Preferring the active keyset on a prefix tie. Attempting this is safe: an id naming the wrong keyset fails signature verification at the mint and no coins move. Anything already valid, or with no unambiguous match, is passed through so the mint's own error still reaches the operator. Token decoding now also checks keyset ids locally, so an id that is not hex or is neither NUT-02 length fails with a message naming the format instead of a raw 422 from the mint. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Archipelago
Self-sovereign Bitcoin node OS and manifest-driven app platform.
Archipelago is a bootable personal server OS for Bitcoin infrastructure,
self-hosted apps, mesh communication, decentralized identity, and federation.
Apps are packaged as declarative manifest.yml files and run as rootless
Podman containers managed by the Rust backend.
What is here
core/- Rust workspace: backend API, container runtime, security, OpenWrt helpers, and performance/resource management.neode-ui/- Vue 3 + TypeScript frontend.apps/- app manifests and custom app container sources.docker/- supporting container build contexts for UI companion surfaces.image-recipe/- bootable image/ISO build inputs.Android/- Android companion app.scripts/- development, release, deployment, and validation tooling.docs/- architecture, app packaging, operations, API, and roadmap docs.
Platform model
Archipelago is built as a developer-ready app platform, not a fixed appliance:
- Apps are declared in
apps/<app-id>/manifest.yml. - The Rust parser in
core/container/src/manifest.rsis the canonical schema. - The orchestrator compiles manifests to rootless Podman/Quadlet runtime state.
- App data lives under
/var/lib/archipelago/<app-id>/. - Secrets are generated or read from
/var/lib/archipelago/secrets/and injected through Podman secrets rather than static environment values. - Release and app catalogs are signed and verified against a pinned trust anchor.
Start with:
- Architecture
- Developer Guide
- App Developer Guide
- App Manifest Spec
- Nostr Git Source Hosting Plan
- Troubleshooting
Quick start
Frontend
cd neode-ui
npm install
npm start
The dev UI runs at http://localhost:8100 with a mock backend on :5959.
Backend
cd core
cargo build
cargo test --all-features
Linux is the supported backend runtime and release-build target. macOS is fine for frontend work and many Rust compile/test loops, but host integration tests that touch Podman, systemd, networking, or image build paths require Linux.
App manifests
./scripts/validate-app-manifest.sh apps/filebrowser/manifest.yml
python3 scripts/generate-app-catalog.py
python3 scripts/check-app-catalog-drift.py --release --strict
scripts/generate-app-catalog.py requires Python with PyYAML installed.
Documentation map
The full, grouped index lives at docs/README.md. The most common entry points:
| Doc | Purpose |
|---|---|
| Architecture | System layers, crates, data paths, security model |
| Developer Guide | Local setup, code workflow, testing |
| API Reference | JSON-RPC API overview |
| App Developer Guide | How to package and test apps |
| App Manifest Spec | Manifest schema and validation rules |
| Nostr Git Source Hosting Plan | ngit/NIP-34 contribution workflow and maintainer model |
| Apps README | Packaged app catalog overview |
| Image Recipe | Bootable image build flow |
| Roadmap | Shipped, in-progress, and planned work |
| Archive | Historical plans, audits, and handoffs |
Contributing
Read CONTRIBUTING.md before opening a pull request. For security issues, follow SECURITY.md and do not open a public issue.
License
Archipelago is licensed under the MIT License. Third-party notices are listed in NOTICE and generated license inventories in component release artifacts.