Building a Safer Bitcoin Checkout for Zorgax: Per-Intent Addresses, Anti-Replay and Idempotent Payments
Payments are relatively easy to demo.
Payments that remain safe when retries, duplicated events, network failures and real money enter the system are much harder.
We've recently been working on a Bitcoin payment rail for Zorgax, part of the MyZubster ecosystem.
The latest implementation milestone is now complete locally.
The objective wasn't simply:
User → Send BTC → Payment Complete
We wanted a checkout architecture that could eventually support automated services and AI agents without treating blockchain transactions as perfectly ordered HTTP requests.
The result introduces several important safeguards.
1. A Different Bitcoin Address for Every Checkout
One of the most important changes is moving toward per-intent Bitcoin addresses.
Instead of repeatedly exposing the same payment address, each checkout intent receives its own address derived from an Electrum-compatible watch-only wallet.
Conceptually:
Checkout #001
↓
BTC Address A
Checkout #002
↓
BTC Address B
Checkout #003
↓
BTC Address C
This makes payment reconciliation much cleaner.
When Bitcoin arrives at Address B, the system already knows which checkout intent it belongs to.
It also improves privacy compared with repeatedly publishing the same Bitcoin address.
2. Watch-Only Architecture
The checkout system is designed around a watch-only wallet.
That's an important security boundary.
The application needs to:
Generate / derive addresses
↓
Observe blockchain activity
↓
Detect transactions
↓
Verify payment
It does not need access to the private keys required to spend those funds.
That creates a useful separation:
Zorgax Payment Infrastructure
↓
XPUB / Watch-Only
↓
Observe BTC
NO PRIVATE SPENDING KEY
Compromising the checkout application should therefore not automatically mean compromising the keys controlling the Bitcoin itself.
For payment infrastructure, reducing the number of systems capable of spending funds is a feature.
3. Integer Satoshi Verification
Money and floating-point arithmetic are not friends.
Instead of comparing BTC values using floating-point numbers, payment verification operates using integer satoshis.
1 BTC = 100,000,000 satoshis
Internally, an expected payment can therefore look like:
expected_amount = 125000 sats
received_amount = 125000 sats
rather than relying on decimal comparisons such as:
0.00125 BTC
The general rule is simple:
Represent monetary values using their smallest practical integer unit whenever possible.
4. TXID Idempotency
Blockchain events don't necessarily arrive exactly once.
Infrastructure retries.
Workers restart.
Requests can be repeated.
Network calls fail after one side has already completed an operation.
Without protection, the same transaction could accidentally be processed multiple times.
The new flow therefore treats transaction processing as an idempotent operation.
Conceptually:
BTC Transaction
↓
TXID
↓
Already processed?
↙ ↘
YES NO
↓ ↓
Ignore Verify
↓
Record
A transaction identifier should not produce multiple payment effects simply because the surrounding infrastructure retried an operation.
5. Anti-Replay Protection
Idempotency solves part of the problem.
But payment systems also need to consider replay.
A valid transaction should not be reusable as proof for an unrelated checkout.
The relationship needs to remain explicit:
Payment Intent
↓
Derived Address
↓
Expected Amount
↓
Observed Transaction
↓
TXID
↓
Verification
The transaction isn't interpreted in isolation.
It is evaluated against the payment intent it is supposed to satisfy.
This becomes increasingly important when payments eventually interact with automated services.
6. Controlled MongoDB Migration
Adding a new payment rail also changes the data model.
That means deployment isn't just a matter of pushing new application code.
Existing database state has to be considered.
The implementation includes a controlled MongoDB migration path rather than silently assuming production documents already match the new schema.
The deployment model becomes:
Code Ready
↓
Tests
↓
Migration Review
↓
Database Migration
↓
Infrastructure Verification
↓
Enable Payment Rail
Database migrations deserve their own operational boundary.
Especially when money is involved.
7. BTC Remains Disabled by Default
This is probably the least exciting feature technically.
It may also be one of the most important.
The Bitcoin rail remains disabled until the required infrastructure is actually ready.
Having working code doesn't mean a payment method should immediately become available in production.
The system still requires infrastructure such as:
Watch-only wallet XPUB
+
Reachable Electrum boundary
+
HTTPS / private networking
+
Production configuration
+
Database migration
+
Deployment authorization
Only after those pieces are verified should the payment rail be enabled.
In other words:
Implemented ≠ Production Ready
That's a distinction worth preserving.
8. Testing the Payment Boundary
The current local implementation passed:
60 test suites and 208 tests.
The generated patch was also validated with:
git apply --check
That gives us confidence in the implementation artifact and test state.
But tests are not the same thing as production verification.
The next stage has different risks:
LOCAL
Implementation
↓
208 tests
↓
Patch verification
PRODUCTION
Review
↓
Commit
↓
Push
↓
Infrastructure
↓
Migration
↓
Deployment
↓
Real-world verification
At the current milestone, the first side is complete.
The second side has intentionally not been executed yet.
Why This Matters for Zorgax
The interesting part isn't simply adding Bitcoin checkout.
Zorgax is being explored as an AI and knowledge layer capable of interacting with other services and, eventually, increasingly autonomous infrastructure.
Once agents can purchase resources or services, payments become part of the agent architecture.
Imagine:
AI Agent
↓
Needs Resource
↓
Creates Payment Intent
↓
BTC Address
↓
Payment
↓
Blockchain Verification
↓
Service Authorized
Now payment infrastructure isn't just an ecommerce feature.
It's a machine-readable economic primitive.
And that changes the security requirements.
From Human Checkout to Agent Payments
Traditional checkout assumes a human is somewhere in the loop.
They see a price.
They click a button.
They authorize a payment.
Future agent systems could operate differently.
Agent A
↓
requests service
↓
Agent B
↓
returns payment intent
↓
Payment Rail
↓
verification
↓
service execution
At that point, concepts such as idempotency, replay protection, deterministic monetary representation and payment-intent isolation become fundamental.
Machines retry aggressively.
Distributed systems duplicate events.
Networks fail.
Services restart.
Money cannot be allowed to behave differently simply because the surrounding software experienced a retry.
The Security Boundary Matters More Than the Payment Button
One lesson from this implementation is that adding Bitcoin isn't primarily about displaying a QR code.
The interesting engineering happens behind it.
ZORGAX
↓
Payment Intent
↓
Per-Intent Address
↓
Bitcoin Network
↓
Electrum
↓
Transaction Detection
↓
┌──── Verification ────┐
│ │
Amount TXID
in sats Idempotency
│ │
└──────────┬───────────┘
↓
Anti-Replay
↓
Payment State
↓
Service / Access
Every arrow represents a boundary where assumptions can fail.
That's where most of the engineering belongs.
Current Status
The important distinction is that this work is currently a verified local implementation, not a production launch.
Completed:
- Electrum watch-only per-intent addresses
- TXID idempotency
- anti-replay protection
- integer satoshi verification
- controlled MongoDB migration
- BTC rail disabled until infrastructure is ready
- 60 test suites passing
- 208 tests passing
- patch validated with
git apply --check
Not yet executed:
- production commit/push
- production deployment
- real database migration
- real Bitcoin transactions
- activation of the BTC rail
The remaining infrastructure includes the watch-only wallet XPUB, a reachable Electrum boundary over an appropriately protected network connection, production configuration and separate authorization for deployment and migration.
That's intentional.
Payment code should be easy to enable only after the infrastructure around it is ready.
What's Next?
The next milestone isn't adding another payment button.
It's safely crossing the boundary from tested implementation to production infrastructure.
And beyond that is the more interesting experiment:
Can the same payment-intent architecture eventually allow AI agents to safely purchase services from humans, APIs, other agents and autonomous machines?
That's where Bitcoin checkout stops being just checkout.
It becomes part of an autonomous economic protocol.
If you're building payment infrastructure for AI agents or distributed systems, how are you handling idempotency, replay protection and machine-to-machine authorization?
