When software moves real money, partial truth is more dangerous than visible failure
A Node.js controller translated a binary serial protocol into safe, stateful bill acceptance and dispensing operations for Bitcoin ATMs.
2020
Production release
The controller went live in worldwide Bitcoin ATM deployments supporting blockchain-to-cash and cash-to-blockchain flows.
4
Complete cash procedures
Acceptance, dispensing, floating, and emptying were implemented as stateful workflows.
39
REST endpoints
The controller exposed integration and generic device-control surfaces for operations and testing.
95 pages
Technical manual
The handoff documentation covered architecture, protocol behavior, APIs, procedures, testing, and operations.
The real situation
This controller did not merely send commands to a peripheral. It coordinated a physical bill recycler, controller state, cash inventory, persistence, and a remote transaction platform while real money moved through timing-sensitive workflows.
A timeout did not prove that nothing happened. A blind retry could move additional cash. Acceptance required authorization while a bill remained in escrow, and dispensing had to account for multiple cash boxes, depletion, partial fulfillment, and uncertain outcomes.
What the business was carrying
The visible problem
- The JCM iPro recycler used a binary, sequence-sensitive ID003 protocol over RS232.
- Physical actions could outlive a software timeout or produce only partial completion.
- Device state, transaction state, persistence, callbacks, and cash inventory needed one trustworthy model.
Why the obvious fix was not enough
The harder system underneath
- Serial packets could arrive fragmented, and mechanical actions required careful timing.
- There was no working Node.js example for the required configuration.
- Consequential actions could not be made safe by reducing every result to success or failure.
The shared-reality problem
Five systems had to agree about what physically happened
The controller’s job was not just command delivery. It had to preserve a recoverable shared truth across the device, workflow, inventory, persistence, and remote platform.
Before
- Binary protocol and fragmented packets
- Mechanical timing
- External transaction authorization
- Cash movement that could not be blindly retried
After
- Production cash-handling controller
- Four complete stateful procedures
- Visible partial and uncertain outcomes
- Operationally documented handoff
- 01
Protocol
Build and validate device messages
Buffer fragments, check length and CRC, and parse responses.
- 02
State
Govern valid transaction transitions
Represent escrow, authorization, stack, return, dispense, timeout, and recovery explicitly.
- 03
Workflow
Plan complete and partial outcomes
Coordinate acceptance, payout, floating, emptying, and inventory reconciliation.
- 04
Operations
Expose control, evidence, and recovery
Provide APIs, logs, heartbeat monitoring, persistence, callbacks, and documentation.
What changed
Decisions that moved the work forward
- 1 Observe
Verify the smallest physical actions first
I connected and polled the device, accepted and returned one bill, dispensed one bill, and only then assembled complete transaction procedures.
- 2 Translate
Turn raw protocol responses into application events
Business workflows consumed meaningful events instead of needing to understand serial bytes and vendor-specific responses.
- 3 Control
Make every consequential state explicit
Finite state machines governed startup, escrow, authorization, stacking, returning, payout, collection, timeouts, and recovery.
- 4 Document
Externalize complexity for operations and handoff
I created diagrams, inventories, checklists, procedure maps, and an approximately 95-page manual as the design evolved.
What the business gained
Results beyond the implementation
01
The production controller supported both bill acceptance and dispensing workflows.
02
Partial payout, uncertain completion, device disagreement, and recovery were represented explicitly.
03
The system left a substantial operational and technical evidence trail for future engineers.
What this proves for a client
The scale may change. The systems judgment still transfers.
The same thinking applies beyond payment hardware. Whenever software coordinates physical actions, third-party services, inventory, or irreversible consequences, the system needs explicit state, observable failure, cautious retries, and documentation that makes recovery possible.
Technical footprint
Evidence and boundaries
- ✓ Production release in 2020
- ✓ Four core cash workflows
- ✓ 39 REST endpoints
- ✓ Approximately 95-page technical manual
- ✓ Archived implementation evidence
The client, private APIs, payloads, credentials, internal identifiers, security details, and deployment specifics remain excluded.
Visual recap
From protocol documentation to production cash-handling logic.
Related practical guide
How to Tell If a Task Is Ready for Automation
Read the guide →Related experience
A practical next step
Make the dangerous states visible before they become incidents
For hardware, payments, kiosks, or other consequential integrations, a system review can map state, timing, retries, partial outcomes, and recovery paths.