Appendix E: The Janitor Construction Hook
This appendix documents the Janitor (Manifest-Driven Aggregation) model. This architecture is intended to fully replace the previously considered Leaderless UTXO approach. While the Leaderless design provided a decentralized path for concurrent donations, it introduced significant “state bloat” and user-experience friction that the Janitor model successfully resolves through protocol-level automation.
It is intended that a future draft of the design document will flesh out the Janitor model more fully.
1. Architectural Shift: From Manual to Autonomous
In a standard UTXO system, transactions are “inert”—they do not move unless a user manually crafts a transaction. The Janitor model introduces a Maintenance Layer into the block-composition process. Instead of leaving donation fragments scattered across the ledger, we utilize an automated “sweeping” mechanism to keep the treasury consolidated. This would be performed within neptune-core nodes operating in a composer role.
Why it Replaces Leaderless
| Flaw of Leaderless | Janitor Solution |
|---|---|
| UTXO Fragmentation: Hundreds of donations create hundreds of tiny UTXOs, bloating the mutator set. | Constant Consolidation: Fragments are merged into a single “Summary UTXO” as quickly as they appear. |
| Input Limits: A developer might be unable to claim 1,000 donations in one TX due to protocol size limits. | Single Output: The developer only ever spends one “Gold Bar” summary UTXO, regardless of campaign size. |
| Zombie Funds: If a project fails, funds sit locked until the donor manually reclaims them. | Automated Refunds: The Janitor “pushes” expired funds back to donors to collect a cleanup bounty. |
2. The Janitor Hook (Core Logic)
The “Janitor” is implemented as a generic Aggregator Hook within the neptune-core block-composition code. It remains entirely agnostic of the CCS specifically; it simply follows the “Search and Merge” instructions provided in the on-chain IBD Manifest.
Step 1: Identification via Unlock Scripts
Rather than checking for specific hardcoded IDs, the Janitor scans the mempool and the confirmed UTXO set for any outputs whose Lock Scripts can be satisfied by the Unlock Script template provided in the Manifest. This ensures the core can support any contract that provides a valid Manifest.
Step 2: Native State Synthesis (The “Fast Path”)
The aggregation of data does not happen inside the Triton VM (which would be computationally expensive). Instead, the Janitor logic performs the arithmetic in native Rust:
- It identifies up to 25 pending donation UTXOs.
- It calculates the new treasury total (Old Summary + New Donations).
- It generates the RemovalRecords (inputs) and AdditionRecords (outputs) for the merge.
Step 3: Composer Integration
The Janitor hands these records to the Block Composer. The composer incorporates them into the next block proposal. Because the composer is already generating a ZK-STARK proof for the entire block, the “Summary Update” is proven as part of the standard mining workflow.
3. Economic Incentives: The Janitor Fee
To ensure this work is performed by miners, the Manifest defines a Protocol-Level Bounty:
- The Aggregation Fee: A small, mandatory portion of each donation is claimable only by the miner who successfully merges that donation into the Summary UTXO.
- The Cleanup Bounty: For maintenance tasks (like refunds), a specific reward is offered to the miner who “cleans” the expired state from the ledger.
This transforms the miner from a passive observer into an active State Janitor, financially motivated to keep the CCS optimized and user funds moving.
4. Handling Surge and Backlog
If a viral campaign receives more donations than can fit in a single block (e.g., more than 25 per block), the Janitor model performs Iterative Consolidation.
- It merges the first 25 donations into the Summary.
- In the next block, it identifies the remaining fragments and merges them as well.
The system is self-healing; it will always “catch up” until the treasury is represented by a single, optimized UTXO.
5. Technical Visual: State Consolidation
- Input Phase: Composer identifies inputs () matching the Manifest script.
- Processing Phase: Native Rust calculates the sum and subtracts the Janitor Fee.
- Output Phase: A single (the new Summary UTXO) and a Fee Output are generated.
- Verification Phase: Triton VM validates the final block proof, ensuring the sum matches the Manifest’s logic.