Towards a neptune community crowdfunding system (CCS) design

danda · December 23, 2025, 7:11pm

In the new year, I am considering changing my focus to work on building a CCS system for NeptuneCash. I agree with @LostInTranslation (and others) that this has worked very well for the Monero community and I believe that if done right (as a smart contract) it can have an outsized impact for NeptuneCash ecosystem and community as well. And for me personally, its an interesting opportunity to learn new things.

Some motivations:

it’s a nice test of the smart contract system.
helps raise funds to further develop neptune ecosystem
creates some circular economy flow (real value)
differentiates Neptune from Monero and other privacy coins.
will require creating new standards and functionality around smart contracts that will benefit other projects.
a CCS smart contract could likely be made reusable for general purpose crowdfunding situations, and perhaps (eventually) multi-token as well.

I should note that I have exactly zero experience building any kind of smart contract or crowdfunding system. What I do have is decades of building distributed systems of various kinds, authoring interfaces and standards, experience with some neptune-core internals, experience building the neptune-proton wallet UI, a friendly and helpful AI assistant, and a direct line of communication with the core devs that built triton-vm and other foundational tech of Neptune Cash.

As such, I spent a few hours working with an AI to evaluate the system and generate a rough design document. I took into account @aszepieniec’s comment here on the subject. I think my design deals with some issues he may not have thought deeply about yet, but I did incorporate one important concept to ensure public auditability of the treasury funds (amount).

I will also note that if too many obstacles present themselves or the project becomes too frustrating for whatever reason, I might well abandon it and go back to wallet work.

Finally, the design uses a “many utxo” approach in order to handle multiple donations (or votes) occurring during a single block, which would each try to use/spend the same input utxo holding smart-contract data. If that problem could be solved in another way (without requiring a neptune-core plugin, that would simplify some things.)

edit: The LeaderLess (many utxo) design is being superceded by a design that uses a sort of plugin-template to consolidate and summarize utxos and reward composers for processing and including in their block tx.

All that follows is AI generated in collaboration, with only a light review.

Preface

The Architecture of Community Funding

To understand the design choices proposed in this document, it is helpful to first look at how community funding mechanisms function in other ecosystems—specifically Monero and Ethereum—and how Neptune Cash sits at the intersection of these paradigms.

The Monero Model: A Hybrid Social System
The Monero Community Crowdfunding System (CCS) is the gold standard for privacy-coin funding, but it is important to note that the CCS itself is not an on-chain mechanism. It is a centralized web forum where proposals are discussed and milestones are tracked.

The only part of the Monero CCS that touches the blockchain is the payment process, which utilizes a multi-signature wallet. This introduces a significant trust requirement: the funds are held by a small group of trusted custodians. If these key-holders were to collude, they could redirect the funds to any address, bypassing the community’s intent and the milestones entirely. While this “social layer” has worked for Monero due to high trust, it remains a custodial system with a human-centric point of failure.

The Ethereum Model: Automation and the ABI Precedent
If we were building this on Ethereum, the architecture would move the entire process onto the blockchain via a smart contract. Ethereum already utilizes a proven standard for contract interaction known as the ABI (Application Binary Interface). The ABI tells the wallet or frontend exactly how to format data to talk to a specific contract.

While the ABI model is proven and successful, Ethereum’s implementation has a significant “off-chain” dependency: the ABI files themselves are usually stored on centralized servers or in developer repositories. If the ABI file is lost or inaccessible, the contract becomes a “black box.” Additionally, Ethereum’s account-based model typically compromises privacy, revealing donor identities and the flow of capital.

The Neptune Cash Approach
Neptune Cash allows us to synthesize these approaches: the privacy of Monero with the programmable, non-custodial trust of Ethereum. By building the CCS as a native smart contract, we eliminate the need for trusted human custodians.

Our design improves upon the Ethereum model by being on-chain first. We propose to publish and retrieve the contract’s interface requirements directly from the Neptune blockchain. This ensures that the instructions on how to interact with the CCS are as decentralized and permanent as the funds themselves, allowing wallets to be truly autonomous.

The Concurrency Challenge: Naive vs. Leaderless UTXOs

The most critical technical distinction in this design document is how we handle state contention in a private, ZK-driven environment.

In a naive implementation, a crowdfunding campaign might be represented by a single UTXO that holds the “pot” of funds. If multiple users try to donate simultaneously, they all attempt to consume that same UTXO. Only one transaction can succeed; the others will be rejected as double-spends. This creates a bottleneck where users must queue up to donate one by one—a poor experience for a global community.

This document proposes a leaderless UTXO design. Instead of a single “pot,” the contract logic allows the state to be fragmented across many UTXOs. Users interact with local fragments of the contract state, which can later be merged or proved correct mathematically without requiring a single, global lock. This allows for high concurrency, enabling hundreds of users to donate simultaneously without blocking one another.

Toward a Universal Interface: Data-Driven Wallets

A major secondary goal of this project is to establish a standard for how wallets interact with complex smart contracts using a Data-Driven Forms standard.

Currently, if a wallet wants to support a specific dApp, developers often have to write custom code or “plugins.” This is the “overlay” approach: it requires the wallet to execute external code, which introduces significant security risks and maintenance burdens.

By using an on-chain ABI-like schema, the smart contract describes its own required inputs. A Neptune wallet (like Proton) can then read this data and dynamically generate the UI forms. Just as a web browser renders HTML without needing a specific “plugin” for every website, a Neptune wallet becomes smart-contract agnostic. It can facilitate complex crowdfunding, voting, or swaps securely, simply by interpreting the standard data provided by the contract on-chain.

From “The CCS” to a Universal Crowdfunding Primitive

Finally, the Neptune CCS is being designed as a universal crowdfunding primitive.

While the Monero CCS is a bespoke platform designed specifically for Monero development, this smart contract is general-purpose. Because the logic is non-custodial and the interface is data-driven, this same contract can be deployed by anyone in the Neptune ecosystem. Whether it is a community member raising funds for a new block explorer, a non-profit seeking private donations, or a new project bootstrapping its initial development, this system provides a foundational building block for raising capital privately, securely, and without permission.

Feature	Monero CCS	Ethereum DAO	Neptune CCS (Proposed)
Escrow Type	Custodial (Multi-sig)	Non-custodial (Code)	Non-custodial (ZKP)
Privacy	High (Sender)	Low (Transparent)	High (Sender & Internal)
Auditability	Social/Manual	On-chain (Public)	On-chain (ZK-Audit)
Concurrency	N/A (Manual)	High	High (Leaderless UTXOs)
Wallet Integration	Manual/Web	External ABI	On-chain Data-Driven Forms

Neptune CCS & Trustless Covenant Standards

Technical Reference Manual – Version 1.0
Architecture: Leaderless Dual-Asset UTXO
Virtual Machine: TritonVM (TASM)

Part I: Architectural Foundations

1. Executive Overview

The Neptune Community Crowdfunding System (CCS) is a protocol for trust-minimized, decentralized fundraising. It allows a community to pool funds for development goals without relying on a central custodian or a federated multisig set.

Unlike legacy implementations (e.g., Monero CCS) where “trust” is placed in human keyholders to act as escrows, the Neptune CCS places trust in Cryptographic Covenants. The release of funds is governed by a Turing-complete script (TritonVM) that mathematically enforces milestone conditions, voting thresholds, and refund rights.

This system introduces three foundational standards for the broader Neptune ecosystem:

The Leaderless State Model: Avoiding global state variables to enable infinite concurrency.
The Dual-Asset Wrapper: Using Type Scripts to enforce identity on native assets.
The Manifest Standard: An on-chain method for storing ABI/Interface definitions, enabling generic wallets to interact with custom covenants.

2. The Object Model

The system does not exist as a single “Smart Contract” in the Ethereum sense. Instead, it is a collection of interacting Unspent Transaction Outputs (UTXOs). We utilize the Cell Model, where every UTXO is composed of data, value, and two distinct scripts:

Lock Script: Defines who can spend the UTXO (Authorization).
Type Script: Defines what the UTXO is (Identity & State Rules).

2.1 The Treasury UTXO (The “Project Pot”)

This is the primary storage unit for the donated funds. It uses a Dual-Asset Architecture, meaning every Treasury UTXO contains both the native currency ($NPT) and a specialized Identity Token.

Native Asset: $NPT (The Value).
Identity Asset: CCS_Identity_Token (The Wrapper).
Purpose: This ensures that the NPT cannot be separated from the project’s logic. You cannot spend the NPT without satisfying the Type Script of the Identity Token.
Lock Script: CCS_Authority_Lock
Role: The Gatekeeper.
Logic: Validates external inputs. It authorizes spending if 3-of-5 “Vote UTXOs” are present OR if a “Receipt UTXO” is being burned.
Type Script: CCS_Identity_Type
Role: The State Machine.
Logic: Enforces invariants.
“My total NPT value must be preserved unless a Payout is authorized.”
“My Milestone Index can only increment by 1.”
“I cannot be split or merged unless the Output preserves this specific Type Script.”

2.2 The Receipt UTXO (The “Claim”)

This token represents a donor’s refundable equity in the project. It decouples the donor’s identity from the funds.

Lock Script: Donor_Wallet_Lock
Role: Ownership. (Controlled by Alice’s private key).
Type Script: CCS_Receipt_Type
Role: The Link.
Minting Rule: “I can only be created if the transaction also outputs a valid CCS_Identity_Token.” (Proof of Donation).
Burning Rule: “I can only be destroyed if the transaction spends a CCS_Identity_Token.” (Proof of Refund).

2.3 The Vote UTXO (The “Ballot”)

A non-fungible, ephemeral UTXO used by Judges to signal approval asynchronously.

Lock Script: Ephemeral_Lock
Role: Garbage Collection. Allows the UTXO to be cleaned up (burned) after the vote is counted.
Type Script: CCS_Judge_Type
Role: The Oracle.
Minting Rule: “I can only be created if the transaction contains a valid STARK proof derived from a whitelisted Judge’s private key.”

3. The “Leaderless” State Architecture

A critical design constraint of this system is Concurrency. If thousands of users donate simultaneously, they must not contend for a single “State Object.”

3.1 The “Bag of Coins” Pattern

We reject the “Global Counter” model (e.g., Total_Raised = X). Instead, the global state is the aggregate sum of all UTXOs bearing the CCS_Identity_Type hash.

Donation Flow:
User A creates Treasury_UTXO_1 (100 NPT).
User B creates Treasury_UTXO_2 (500 NPT).
Result: Two independent UTXOs exist at the same script address. No locking or queuing is required.

3.2 The “Introspective” Vote

Governance does not update a variable on the Treasury UTXO. Instead, it relies on Transaction Introspection.

The Voting Process:

Judges mint Vote UTXOs independently.
When the Payout is ready, the Developer constructs a Sweep Transaction.
Inputs: Treasury_UTXO + Vote_UTXO_1 + Vote_UTXO_2 + Vote_UTXO_3.

The Verification Logic:
The CCS_Authority_Lock on the Treasury UTXO executes a loop over its sibling inputs:

“I scan my input list. I count 3 distinct UTXOs that match the CCS_Judge_Type hash. Therefore, I authorize the release of funds to the Developer.”

This stateless approach allows the voting process to be fully parallelized and gas-efficient, as the heavy cryptographic verification of the Judge’s signature happens only once (during the minting of the Vote UTXO), not during the Payout Sweep.

4. Cryptographic Primitives

To implement the above architecture, the following Neptune-specific primitives are required:

Tip5 Hash Commitments:
Values in the Treasury are hidden using Tip5 hashing (STARK-friendly), not Elliptic Curve Pedersen commitments.
Commitment = Tip5::hash(Amount || Randomness)
Transaction Introspection:
The ability of a running script to read the Transaction struct from the operational stack, granting visibility into Inputs, Outputs, and Witness data.
Recursive Covenants:
The CCS_Identity_Type script must verify that its own Script Hash is present in the transaction outputs (preserving the covenant across transactions).

Part II: The Smart Contract Logic

This section details the specific implementation of the system’s three core components using tasm-lang (Rust-to-TASM). We focus on how scripts leverage Transaction Introspection to enforce the “Multi-Coin” rules.

Chapter 3: The Treasury UTXO (The Vault)

The Treasury is a high-assurance “Multi-Asset” object. It physically binds the native currency ($NPT) to the project’s identity, ensuring the money cannot move unless the project’s state machine is satisfied.

3.1 Structure of the Treasury UTXO

A valid Treasury UTXO must contain at least two coin types:

Coin A (Value): Native $NPT (Quantity: Variable).
Coin B (Identity): The CCS_Identity_Token (Quantity: 1).

By placing both scripts on the same UTXO, the Neptune consensus engine requires both the NPT conservation rules and the CCS identity rules to return True for any transaction involving these funds.

3.2 The Identity Type Script (`CCS_Identity_Type`)

This script provides the “State Machine” logic. It ensures that the project’s metadata (like the current Milestone Index) persists and evolves correctly.

Key Logic: The State Ratchet
The script ensures that the project doesn’t just “disappear” or “reset.” It enforces that the Milestone Index is a monotonic counter.

// tasm-lang pseudo-code for CCS_Identity_Type
fn main() {
    let tx = tasm::load_current_transaction();
    let old_state = tasm::load_current_utxo_data(); // Current Milestone index

    // 1. Search outputs for the "descendant" Identity Token
    let mut matching_output_found = false;
    for output in tx.outputs {
        if output.has_type_script(SELF_HASH) {
            let new_state = output.decode_data::<CCSState>();

            // 2. Enforce the Milestone Ratchet:
            // State stays same (Donation/Merge) or increments by 1 (Payout)
            assert!(new_state.milestone >= old_state.milestone);
            assert!(new_state.milestone <= old_state.milestone + 1);

            matching_output_found = true;
            break;
        }
    }

    // If identity is being destroyed, it MUST be the final payout/liquidation
    if !matching_output_found {
        assert!(old_state.is_final_milestone(), "Illegal destruction of Project Identity");
    }
}

Chapter 4: The Authority Lock Script (`CCS_Authority_Lock`)

While the Type Script manages What the state is, the Lock Script manages Who is allowed to change it. It implements the “Permission Layer.”

4.1 The Introspection Loop (Stateless Counting)

Because we use a Leaderless Model, we do not store a vote_count in a database. Instead, the Lock Script counts “Vote Tickets” (UTXOs) present in the current transaction’s input list.

Logic Flow:

Initialize: Set vote_count = 0.
Iterate: For every input in the transaction:

Check if the input’s Type Script Hash matches the CCS_Vote_Type.
Verify the vote metadata (e.g., it targets the correct Milestone).

Authorization: If vote_count >= 3, the script returns True, allowing the Treasury NPT to be spent to the Developer Address.

// tasm-lang logic for the Authority Lock
fn verify_spend() {
    let tx = tasm::load_current_transaction();
    let mut votes = 0;

    // Scan sibling inputs for valid vote tickets
    for input in tx.inputs {
        if input.type_script_hash() == VOTE_TICKET_HASH {
            // The Vote Type Script already verified the Judge's signature
            // upon creation. We simply count its presence here.
            votes += 1;
        }
    }

    // Alternative Branch: Check for Refund Claims
    let has_refund_receipt = tx.inputs.iter().any(|i| i.type_script_hash() == RECEIPT_HASH);

    // Permission is granted if threshold is met OR a donor is claiming a refund
    assert!(votes >= 3 || has_refund_receipt, "Unauthorized Spend: Missing Votes or Receipt");
}

Chapter 5: The Receipt Token (`CCS_Receipt_Type`)

The Receipt Token is a separate coin type that acts as a “Refund Voucher.” It is minted into the donor’s wallet at the moment of donation.

5.1 Minting Rules (Donation Binding)

The Receipt Script uses Output Introspection to ensure it cannot be forged.

The Rule: “I allow myself to be minted ONLY IF the transaction also creates or updates a UTXO carrying the CCS_Identity_Type.”
This creates a cryptographic link: every receipt in the wild is mathematically proven to be backed by a deposit into the Treasury.

5.2 Burning Rules (Refund Execution)

When a donor wants a refund, they provide their Receipt as an input.

The Rule: “I allow myself to be burned ONLY IF the Treasury UTXO is also an input and it is outputting NPT back to the donor’s address.”

Part III: The “Manifest” Standard

This section defines the protocol-level standard for On-Chain Discovery, enabling generic wallets to interact with these scripts.

Chapter 6: The Manifest UTXO

To make this a “General Purpose” system, we avoid hardcoding CCS logic into the wallet. Instead, the Developer deploys a Manifest UTXO that acts as the “Instruction Manual” for the contract.

The Manifest Object:

Storage: The ABI JSON is stored in the announcement field of a dedicated, static UTXO.
Content: * The lock_script_hash and type_script_hash for the project.
A schema defining the vote() and donate() methods.
The BFieldElement layout for the VM’s input tape.

Why this is a Standard:
When a wallet encounters a CCS address, it queries the blockchain for the associated Manifest. It then “learns” how to render the UI and generate the necessary STARK proofs for that specific version of the CCS without requiring a software update.

This final section addresses the operational reality of the system: how to launch it, how to manage its lifecycle, and how to maintain the “General Purpose” promise through a standardized wallet interface.

Part IV: Deployment, Lifecycle, and UX

This section defines the operational procedures for managing a Neptune CCS, focusing on the “Circular Dependency” problem of script hashes and the “Prover-centric” user experience.

Chapter 7: The “Chicken and Egg” Deployment Problem

In a system where scripts reference each other’s hashes for security (e.g., the Receipt Token hardcodes the Treasury’s Type Script Hash), deployment requires a specific, multi-stage sequence.

7.1 The Hash-Dependency Loop

The Treasury needs the Vote Token Hash to count votes.
The Vote Token needs the Treasury Hash to ensure it’s voting for the right project.
The Receipt Token needs the Treasury Hash to validate minting/burning.

7.2 The Deployment Sequence

To break this loop, we utilize Deterministic Script Generation:

Stage 1: Pre-Computation. The developer writes the code for all three scripts (Treasury, Vote, Receipt) using placeholders for the other scripts’ hashes.
Stage 2: Deterministic Hashing. Using a local Neptune tool, the developer calculates the final hashes of the compiled TASM for each script. Because TritonVM scripts are immutable, these hashes are fixed once the logic is finalized.
Stage 3: Injection. The developer replaces the placeholders in the source code with these finalized hashes and performs a final compilation.
Stage 4: Genesis Transaction. The developer mints the first CCS_Identity_Token and the Manifest UTXO in a single transaction. This “Genesis” block establishes the project’s existence on the network.

Chapter 8: Governance & Upgradability

Because the CCS is “Leaderless” and decentralized, we cannot have an “Admin” key that can arbitrarily change the rules. Instead, upgrades happen via Recursive Covenant Migration.

8.1 The “Governance Sweep”

If the Judges decide to rotate their keys or update the CCS logic (e.g., to patch a bug), they do not “edit” the existing UTXOs. Instead, they perform a Migration:

The Vote: 3-of-5 Judges authorize a “Migration Transaction.”
The Transaction: This transaction consumes all current Treasury UTXOs (Version 1).
The Output: The transaction produces a new set of Treasury UTXOs (Version 2) with a new Lock Script.
The Continuity: The CCS_Identity_Token is preserved, but its internal “State” is updated to reflect the new version or new Judge list.

This ensures that the “Project Identity” stays the same (the address doesn’t change for donors), but the underlying “Engine” can be upgraded.

Chapter 9: Design for the Generic Prover Wallet

The success of this system depends on a wallet that can handle arbitrary covenants. We move away from “Hardcoded Features” to a “Manifest-Driven UI.”

9.1 The Manifest-Driven Workflow

When a user wants to interact with the CCS, the wallet follows this automated routine:

Discovery: The user provides the Project_ID (the Type Script Hash).
Manifest Retrieval: The wallet scans the blockchain for a Manifest UTXO bearing that ID.
UI Generation: The wallet parses the ABI JSON within the Manifest.

Example: If the Manifest says method: "Donate", the wallet renders a slider for NPT and a “Confirm” button.

Local Proving (The “Witness”):

To “Vote,” the wallet doesn’t just send a message. It downloads the Vote_Prover TASM from the Manifest.
It runs the Judge’s private key through this TASM locally to generate a STARK Proof.
It bundles this Proof into a new Vote_Ticket UTXO.

9.2 Benefit: Total Extensibility

By following this standard, a Neptune wallet becomes a “Universal Browser” for smart contracts. The same wallet that handles the CCS today can handle a Decentralized Exchange (DEX) tomorrow, simply by reading a different Manifest UTXO.

Chapter 10: Conclusion

The Neptune CCS is more than a crowdfunding tool; it is a reference implementation for Trustless Governance in a post-quantum, privacy-preserving ecosystem.

By leveraging TritonVM’s Introspection, the Leaderless UTXO Model, and the Dual-Asset Identity Pattern, we have created a system that is:

Permissionless: No central authority can freeze funds.
Private: Donors remain anonymous via Receipt Tokens.
Scalable: Infinite concurrent donations via the “Bag of Coins” model.
Verifiable: Every state transition is backed by a mathematical STARK proof.

Final Documentation Checklist for Developers

To build this system, a developer must produce the following:

TASM/Rust Source: Treasury_Lock, Identity_Type, Receipt_Type, Vote_Type.
Manifest JSON: The ABI defining methods, widgets, and script hashes.
Deployment Tool: A script to handle deterministic hashing and the Genesis transaction.
Web/Desktop Interface: A “Prover-enabled” wallet or wrapper that can ingest the Manifest.

Part V: The Manifest Specification

To finalize this technical reference, we will define the Manifest UTXO JSON Schema.

This is the “Rosetta Stone” of the system. It bridges the gap between the low-level Triton Assembly (TASM) running on the blockchain and the high-level User Interface on the user’s desktop. By storing this JSON on-chain, we ensure the CCS is truly permanent and self-documenting.

Chapter 11: The CCS Manifest JSON

The following JSON structure is designed to be stored within the announcement field of the Manifest UTXO. It provides a “Generic Prover Wallet” with everything it needs to construct valid transactions.

{
  "manifest_version": "1.0.0",
  "project_name": "Neptune Core Ecosystem Fund",
  "project_id": "5ef8...321a",
  "scripts": {
    "treasury_lock_hash": "a92b...f110",
    "identity_type_hash": "c11d...e449",
    "receipt_type_hash": "d22e...b558",
    "vote_type_hash": "f44g...a992"
  },
  "interactions": [
    {
      "method": "Donate",
      "description": "Contribute NPT to the treasury and receive a refund receipt.",
      "ui_widget": "funding_form",
      "inputs": [
        {
          "label": "Amount to Donate",
          "symbol": "NPT",
          "type": "amount_u64",
          "binding": "tx.output[target].value"
        }
      ],
      "logic_hint": "Create dual-asset output: [Identity_Token, Native_NPT] + [Receipt_Token]"
    },
    {
      "method": "Cast Vote",
      "description": "As a Judge, generate a proof to approve the current milestone.",
      "ui_widget": "judge_panel",
      "inputs": [
        {
          "label": "Milestone Index",
          "type": "u32",
          "widget": "dropdown",
          "source": "contract_state.milestone_index"
        },
        {
          "label": "Judge Secret Key",
          "type": "secret_key",
          "scope": "private"
        }
      ],
      "prover_tasm_ref": "ipfs://Qm...vote_prover.tasm",
      "logic_hint": "Mint Vote_Ticket UTXO with STARK proof of Judge_ID"
    },
    {
      "method": "Claim Refund",
      "description": "Burn your receipt to withdraw your pro-rata share of remaining funds.",
      "ui_widget": "refund_button",
      "inputs": [
        {
          "label": "Select Receipt",
          "type": "utxo_selector",
          "filter": "type_hash == scripts.receipt_type_hash"
        }
      ],
      "logic_hint": "Burn Receipt UTXO + Input Treasury UTXO -> Output Treasury (Reduced) + Output User (NPT)"
    }
  ],
  "governance": {
    "threshold": 3,
    "total_judges": 5,
    "judge_list": [
      { "id": 0, "name": "Reviewer_Alpha", "pubkey_hash": "0x..." },
      { "id": 1, "name": "Reviewer_Beta", "pubkey_hash": "0x..." }
    ]
  }
}

Chapter 12: How the Wallet Interprets the Manifest

When a “Generic Prover Wallet” loads this JSON, it performs the following logic-mapping:

12.1 Dynamic Form Rendering

Instead of a hardcoded “Send” button, the wallet sees the interactions array.

It renders a “Cast Vote” button.
When clicked, it renders a Dropdown populated by the current milestone index (which it fetches from the live Identity_Token state on-chain).
It provides a Secure Password Field for the Judge Secret Key.

12.2 Automated Transaction Construction

The logic_hint fields tell the wallet which UTXOs need to be bundled together. For a “Vote” transaction, the wallet knows it must:

Fetch the Vote Prover TASM (from the IPFS link or the UTXO data).
Execute that TASM locally using the user’s Secret Key as a “Secret Input.”
Take the resulting STARK Proof and place it in the witness area of a new Vote_Ticket UTXO.

12.3 Safety Assertions

Because the Manifest includes the scripts hashes, the wallet can perform a pre-broadcast check:
“Does the transaction I just built actually satisfy the treasury_lock_hash? I will run a local simulation of TritonVM to verify the proof before wasting the user’s transaction fee.”

Chapter 13: The Neptune Manifest Schema (NMS-1)

This schema defines the structure for the “Manifest UTXO.” It uses a strict type-mapping to ensure that UI inputs can be converted directly into the BFieldElement arrays required by TritonVM.

13.1 Primitive Type Mapping

Any field typed in the Manifest must map to these TASM-compatible primitives:

Manifest Type	TASM / Rust Equivalent	Description
`bfe`	`BFieldElement`	Single field element (up to ).
`xfe`	`XFieldElement`	Extension field element (3 BFEs).
`u32`	`u32`	BFE constrained to 32 bits.
`u64`	`u64`	Two BFEs (Standard Neptune amount type).
`digest`	`Digest`	5 BFEs (Standard hash/identity type).
`bool`	`bool`	BFE (0 or 1).
`string`	`Vec<BFieldElement>`	Length-prefixed UTF-8 encoded BFEs.

13.2 Formal Schema Definition (JSON-Schema Style)

The Manifest must be a JSON object following these field constraints:

A. Header Metadata

manifest_id: digest — Unique hash of this specific manifest version.
identity_hash: digest — The type_script_hash of the Project Identity Token.
version: u32 — Incremental version of the contract logic.

B. Script Registry (`scripts`)

A map of functional roles to their compiled digest hashes.

lock_logic: digest — The lock_script_hash (The Authority).
state_logic: digest — The type_script_hash (The Identity).
asset_logic: digest — (Optional) Hash of the associated Receipt token.

C. Interaction Definitions (`methods`)

An array of objects defining user actions. Each object must contain:

name: string — Display name (e.g., “Vote”).
selector: bfe — The “Function Selector” passed to the TASM entry point (like an Ethereum 4-byte ID).
args: Array<Argument> — Ordered list of inputs.
label: string — UI label.
type: PrimitiveType — (From the table in 13.1).
widget: enum — [slider, dropdown, text, hidden, key_selector].
prover_ref: string — URI (IPFS/On-chain) to the .tasm or .wasm Prover binary.

D. State Mapping (`state_view`)

Tells the wallet how to “Read” the UTXO data field to show the user current info.

layout: Array<{ name: string, type: PrimitiveType }>
Example: [{ "name": "milestone", "type": "u32" }, { "name": "total_donated", "type": "u64" }]

13.3 Implementation: Lossless Conversion

The Wallet’s primary job is the TASM Stack Preparation. Using this schema, the wallet performs the following “Lossless” transformation:

Collects UI Input: User enters “Milestone: 2”.
Lookup Schema: Method Vote has Arg[0] of type u32.
BFE Encoding:

2 (Integer) BFieldElement(2).
Amount(10.5 NPT) u64 (Two BFEs representing microns).

Stack Loading:
The wallet pushes the Selector, then the Arguments onto the TritonVM operational stack in the order defined in the Manifest.
[ ...stack, Argument_N, ..., Argument_0, Selector ]

13.4 Example Implementation (The CCS “Vote” Method)

Based on this strict schema, the “Vote” method is defined as:

{
  "name": "Cast Vote",
  "selector": "0x11223344",
  "args": [
    {
      "label": "Milestone Index",
      "type": "u32",
      "widget": "dropdown",
      "source": "state_view.milestone"
    },
    {
      "label": "Judge ID",
      "type": "u32",
      "widget": "hidden",
      "source": "wallet.active_key_id"
    }
  ],
  "prover_ref": "neptune://c11d...e449/vote_prover"
}

Why this is “General Purpose”

By mapping to TASM types (bfe, u32, u64), the wallet becomes a Transparent Proxy. It doesn’t need to understand “CCS logic.” It only needs to understand how to turn a JSON input into a Stack Element. This ensures that any future contract—no matter how complex—can be used immediately by any wallet that implements this NMS-1 Schema.

The State View is the final piece of the “Generic Prover Wallet” puzzle. It allows the wallet to take a raw blob of BFieldElements from a UTXO and turn it into a human-readable dashboard.

Without this, the wallet is “blind”—it can send transactions, but it can’t tell the user what the current milestone is or how much has been raised.

Chapter 14: The State View Standard

In Neptune, a UTXO’s data field is essentially a flat array of BFieldElements. The State View section of the Manifest provides the “Lens” through which the wallet views this data.

14.1 The Decoding Engine

The wallet uses a sequential decoder based on the ordered list provided in the Manifest. It starts at index 0 of the UTXO data and “carves out” the types as specified.

Schema Definition: `state_view`

root: enum — [utxo_data, announcement]. Defines where the data is stored.
fields: Array<DataField>
name: string — The label for the UI (e.g., “Funds Raised”).
type: PrimitiveType — (e.g., u64, digest, u32).
visibility: enum — [public, internal].
transform: enum — [none, micron_to_npt, timestamp_to_date].

14.2 Case Study: Decoding the CCS Treasury UTXO

Imagine a Treasury UTXO has the following raw data in RAM:
[ 0x00000001, 0x00000000000003E8, 0x0000000000000005, ... ]

The Manifest defines the State View like this:

"state_view": {
  "root": "utxo_data",
  "fields": [
    {
      "name": "Current Milestone",
      "type": "u32",
      "visibility": "public"
    },
    {
      "name": "Total Payout Threshold",
      "type": "u64",
      "transform": "micron_to_npt",
      "visibility": "public"
    },
    {
      "name": "Judge Quorum",
      "type": "u32",
      "visibility": "public"
    }
  ]
}

How the Wallet Renders This:

Read Index 0 (u32): Sees 0x1. Displays “Current Milestone: 1”.
Read Index 1-2 (u64): Sees 1000 (in microns). Applies micron_to_npt. Displays “Total Payout Threshold: 1000 NPT”.
Read Index 3 (u32): Sees 5. Displays “Judge Quorum: 5”.

14.3 Dynamic Formulas: The “Progress Bar” Logic

A truly generic wallet should also be able to perform basic math on these fields to provide better UX. We extend the state_view with a computations array:

"computations": [
  {
    "label": "Funding Progress",
    "type": "percentage",
    "formula": "(tx.value / state_view.total_payout_threshold) * 100"
  }
]

This allows the wallet to render a Progress Bar (e.g., “45% Funded”) even though the contract itself never explicitly calculated a percentage.

Chapter 15: Putting It All Together

We have now reached the conclusion of the Neptune CCS Technical Reference. By combining these three standards, we have created an ecosystem that is both highly specific (The CCS) and infinitely general (The NMS-1 Standard).

The Developer’s Final Architecture

The Code (TASM/Rust): Enforces the logic and manages the Multi-Coin UTXOs (NPT + Identity).
The Data (Manifest): Defines the Types, Methods, and State Views using NMS-1.
The UX (Generic Wallet): Downloads the Manifest, decodes the State, and generates the Prover Witness JIT.

Conclusion: Beyond the CCS

While this guide used a Crowdfunding System as its primary example, the Manifest + Introspection model is the key to unlocking the “World Computer” potential of Neptune Cash. It allows for a library of “Covenant Templates” that any user can deploy, and any wallet can immediately understand.

Neptune CCS: Developer Quick Start

1. Environment Setup

Ensure you have the following tools installed:

tasm-lang: The Rust-to-TASM compiler.
neptune-core: For testing script execution against a local node.
triton-vm: To run and debug your scripts in a local VM environment.

2. Development Workflow (Step-by-Step)

Step 1: Compile the Auxiliary Scripts

Write and compile your Receipt Token and Vote Ticket scripts.

Note: Initially, use a “Dummy Hash” for the Project Identity.
Command: tasm-lang compile receipt_token.rs --output receipt.tasm
Action: Take the resulting hash () and .

Step 2: Compile the Core Treasury

Inject the hashes from Step 1 into your Treasury Lock and Identity Type scripts.

Treasury Lock: Hardcode and into the introspection loop.
Identity Type: Hardcode the .
Action: Compile and get the final Treasury hashes ( and ).

Step 3: Resolve the Circular Dependency

Re-compile the Receipt Token and Vote Ticket, replacing the “Dummy Hash” with the real from Step 2.

Result: You now have a “Locked Loop” where all three scripts recognize and verify each other’s hashes.

Step 4: Prepare the Manifest

Create your manifest.json using the NMS-1 Schema.

Map your Treasury data fields to u32 and u64.
Define the selector for each method (e.g., 0x01 for Donate, 0x02 for Vote).
Specify the prover_ref (e.g., an IPFS hash pointing to your compiled Prover TASM).

3. The Genesis Transaction

To launch the CCS, you must broadcast a single transaction that initializes the system:

Output 1 (Manifest): A dust UTXO containing the manifest.json in the announcement field.
Output 2 (Identity): A UTXO carrying the CCS_Identity_Type and CCS_Authority_Lock with initial state (Milestone: 0).

4. Deployment Checklist

Component	Status	Verification
Identity Token	`H_identity`	Use `triton-vm` to verify state transition .
Authority Lock	`H_lock`	Test introspection loop with 3 mock Vote UTXOs.
Receipt Token	`H_receipt`	Verify it cannot be minted without Identity in outputs.
ABI Manifest	`NMS-1 JSON`	Validate against the schema for `bfe` and `u64` alignment.

5. Common Pitfalls

Endianness: Ensure u64 amounts are split into two BFieldElements in the correct order for the wallet to decode.
Bitmasks: In the Authority_Lock, always use a bitmask for Judge IDs to prevent a single judge from satisfying the quorum with multiple Vote UTXOs.
Padding: Remember that string types in TASM are length-prefixed; ensure your Manifest decoder accounts for this.

The Bitmask Vote Counter (TASM Snippet)

To ensure the Authority Lock is robust against “double-counting” (where one judge tries to submit multiple vote UTXOs to satisfy the quorum alone), we use a bitmask.

In TASM, we use the bitwise AND and OR operations to track which Judge_ID has already been seen during the input scan.

This logic would be embedded inside the loop that iterates over transaction inputs.

// INITIAL STATE (Before Loop)
PUSH 0      // [judge_bitmask] -> Initialize to 0
PUSH 0      // [vote_count, judge_bitmask] -> Initialize to 0

// --- START OF INPUT LOOP ---
// (Assume we have already verified the current input is a Vote UTXO)

// 1. Load the Judge_ID from the UTXO data (Assume it's a u32)
// [..., current_input_ptr, vote_count, judge_bitmask]
dup 2
read_mem 1  // Load Judge_ID from RAM
// [..., judge_id, vote_count, judge_bitmask]

// 2. Create the bit-flag (1 << judge_id)
PUSH 1
dup 1       // Duplicate judge_id for the shift
// [..., judge_id, judge_id, 1, vote_count, judge_bitmask]
// Note: TritonVM doesn't have a variable SHL, so we use a loop or lookup
call power_of_two
// [..., bit_flag, vote_count, judge_bitmask]

// 3. Check if judge has already voted
dup 0       // bit_flag
dup 3       // judge_bitmask
AND         // Result is non-zero if bit is already set
// [..., (flag & mask), bit_flag, vote_count, judge_bitmask]

push 0
eq
skiz call increment_vote // If result was 0, judge is new. Increment.

// 4. Update the mask regardless (safe to OR a bit that's already set)
swap 2      // [judge_bitmask, vote_count, bit_flag]
OR
swap 1      // [vote_count, judge_bitmask]
// --- END OF LOOP ---

// FINAL CHECK
PUSH 3      // The Quorum
dup 1       // vote_count
ge          // Is vote_count >= 3?
assert      // Crash if threshold not met

Supporting Subroutine: Power of Two

Since shifting by a variable amount can be complex in assembly, we use a simple recursive power-of-two function to generate the bit-flag.

power_of_two:
    // [exponent, base(1)]
    dup 1
    push 0
    eq
    skiz return // If exponent is 0, we are done

    push 2
    mul
    swap 1
    push -1
    add
    swap 1
    recurse

Security Analysis

Uniqueness: Even if a malicious actor provides five Vote UTXOs all signed by “Judge #1,” the AND check will prevent vote_count from exceeding 1 for that judge.
Statelessness: This entire check happens during the spending transaction. No permanent “voted” state needs to be saved on the project UTXO, keeping it “clean” for the next milestone.
Efficiency: The bitmask is a single BFieldElement. Using a 64-bit field allows up to 64 unique judges—far more than the 5–10 typically used in a CCS.

The Milestone Ratchet is the “heartbeat” of the project’s continuity. It ensures that the project cannot be “reset” and that funds cannot be drained without the state moving forward.

In the Dual-Asset Model, this logic lives in the type_script of the Identity Token. By enforcing this at the type level, you ensure that even if the lock_script (the judges) is compromised or changed, the fundamental progression of the project remains immutable.

The Identity Type Script: Milestone Ratchet

This tasm-lang template demonstrates how to compare the “Before” and “After” states of the project within a single transaction.

use tasm_lang::prelude::*;

// Define the state structure stored in the UTXO's data field
struct CCSProjectState {
    milestone_index: u32,
    total_milestones: u32,
    dev_address: Digest,
}

fn main() {
    // 1. Load the "Self" UTXO (the state before this transaction)
    let input_utxo = tasm::load_current_utxo();
    let old_state: CCSProjectState = input_utxo.decode_data();

    // 2. Identify the "Successor" UTXO (the state after this transaction)
    // We search the outputs for the UTXO carrying THIS specific type script.
    let tx = tasm::load_current_transaction();
    let mut successor_found = false;

    for output in tx.outputs {
        if output.type_script_hash() == tasm::own_type_script_hash() {
            let new_state: CCSProjectState = output.decode_data();

            // --- THE RATCHET LOGIC ---

            // Rule A: Directionality
            // The milestone can either stay the same (Donation) or increment (Payout).
            // It can NEVER go backwards.
            assert!(new_state.milestone_index >= old_state.milestone_index);

            // Rule B: Sequentiality
            // We only allow incrementing by exactly 1 at a time.
            assert!(new_state.milestone_index <= old_state.milestone_index + 1);

            // Rule C: Immutability of Configuration
            // You cannot change the developer address or total milestones
            // without a high-level governance migration.
            assert!(new_state.dev_address == old_state.dev_address);
            assert!(new_state.total_milestones == old_state.total_milestones);

            successor_found = true;
            break;
        }
    }

    // 3. Termination Logic
    // If no successor is found, we must be in the "Final Payout" state.
    if !successor_found {
        assert!(old_state.milestone_index == old_state.total_milestones,
            "Project attempted to dissolve before completing all milestones.");
    }
}

Architectural Significance

Atomic State Transitions: By running this script, the network ensures that the (Native Token) and the milestone_index move in lockstep. You cannot have a transaction where the money leaves but the milestone doesn’t advance.
Safety against “Ghost” Updates: Because the script iterates through tx.outputs to find its own hash, it prevents “splintering,” where a project might try to split into two competing versions of itself.
Self-Liquidation: The logic in Step 3 allows the project to naturally “expire” once the work is done, allowing the Identity Token to be burned and the final dust to be cleaned up.

Appendix A: Transparency & Public Auditing

Subject: Implementing “Forced Announcements” for State Visibility

Origin: Adapted from “Overlay Protocol” concepts (Alan’s Design)

Goal: To defeat the “Privacy Default” of Neptune for the specific case of Public Treasury tracking.

A.1 The Problem: Privacy by Default

Neptune Cash uses confidential transactions. By default, when a UTXO is spent, its value and data are obfuscated.

The Donor’s View: Perfect. They want privacy.
The Public’s View: Problematic. If the Treasury UTXO is spent, the public might lose track of the Milestone_Index or Total_Raised because the output UTXO appears as an encrypted blob.

To solve this, we cannot rely on the goodwill of the developer to publish their updates. We must mathematically enforce transparency within the Type Script itself.

A.2 The Solution: Forced Announcements

We modify the CCS_Identity_Type script. It now includes a clause that says:

“I will only validate this transaction if the Output UTXO carrying my identity ALSO carries a cleartext public announcement of its new state.”

This ensures that the “Chain of Custody” for the project is publicly visible in the block data, allowing “Light Clients” and Block Explorers to index the CCS without holding the private keys.

A.3 Updated Logic: `ccs_identity_type.rs`

Below is the revised Type Script. The new logic is located inside the successor verification loop.

use tasm_lang::prelude::*;

struct CCSProjectState {
    milestone_index: u32,
    total_milestones: u32,
    dev_address: Digest,
}

fn main() {
    let input_utxo = tasm::load_current_utxo();
    let old_state: CCSProjectState = input_utxo.decode_data();

    let tx = tasm::load_current_transaction();
    let mut successor_found = false;

    for output in tx.outputs {
        // Find the new version of the project
        if output.type_script_hash() == tasm::own_type_script_hash() {
            let new_state: CCSProjectState = output.decode_data();

            // 1. Ratchet Logic (Existing)
            assert!(new_state.milestone_index >= old_state.milestone_index);
            assert!(new_state.milestone_index <= old_state.milestone_index + 1);

            // 2. Transparency Logic (NEW)
            // We verify that the output actually contains a 'Public Announcement'
            // field that matches the internal state.
            let announcement = output.public_announcement();

            // The announcement must be present
            assert!(announcement.is_some(), "Transparency Error: State must be public.");

            // The announcement must match the actual data (Anti-Spoofing)
            // We require the announcement to be the serialization of the new state.
            let announced_state: CCSProjectState = CCSProjectState::decode(announcement.unwrap());
            assert!(announced_state == new_state, "Transparency Error: Mismatched public data.");

            successor_found = true;
            break;
        }
    }

    if !successor_found {
        assert!(old_state.is_final(), "Project dissolved prematurely.");
    }
}

A.4 The Announcement Standard

To ensure generic block explorers can parse this data, we define the standard format for the Public Announcement field.

Announcement Schema (BFieldElement Array):

Prefix: 0x434353 (ASCII for “CCS”).
Milestone Index: u32.
Balance: u64 (The visible NPT amount).
State Hash: Digest (A hash of the full internal state for verification).

Why this is powerful:

With this change, a block explorer does not need to run the TritonVM to know what is happening. It can simply scan the blockchain for the “CCS” prefix in announcements.

If it sees Milestone: 1: It updates the website to “In Progress.”
If it sees Milestone: 2: It updates the website to “Milestone 1 Complete.”

This creates a “Shadow Ledger” of public data on top of the private Neptune chain, strictly for this charity application.

Appendix B: Design Justification & Comparative Analysis

Reference: Alan’s “Overlay Protocol” Proposal (Neptune Forum)

B.1 Architectural Divergence

In early discussions regarding a Neptune CCS, a “Singleton” model was proposed where the treasury resides in a single UTXO managed by an overlay protocol (a custom node plugin). While theoretically sound, this introduces significant engineering friction and scalability bottlenecks.

Our implementation adopts a “Leaderless” (Bag of Coins) architecture. Instead of a single “Pot” that must be updated sequentially, we treat the treasury as a distributed collection of UTXOs that share a common identity.

B.2 Comparative Matrix

The following table details the specific mechanical differences between the Overlay Model and our Leaderless Model, justifying the design choices made in this specification.

Feature	The “Overlay” Model (Singleton)	The “Leaderless” Model (Chosen)	Why We Chose “Leaderless”
Concurrency	Sequential. Only one transaction can spend the Treasury UTXO per block. High contention if many donors try to donate simultaneously.	Infinite. 100 donors create 100 separate Treasury UTXOs simultaneously. No locking or queuing required.	Eliminates “Double Spend” failures during high-traffic fundraising events.
Infrastructure	Heavy. Requires Judges to run a custom “Neptune Foundation” node plugin to coordinate state and manage the overlay network.	Light. Uses standard Neptune infrastructure. The “Logic” lives in the Wallet (Manifest), not in a custom node process.	Drastically lowers the barrier to entry for Judges and Developers. No custom daemon required.
Governance	Synchronous. Judges must coordinate online to sign the specific transition of the singular UTXO.	Asynchronous. Judges mint “Vote Tickets” independently at their own leisure. The system aggregates them later.	Removes the need for Judges to be online simultaneously. “Bus Factor” resistant.
State Storage	Explicit. `Total_Raised` is a variable stored in the single UTXO’s data field.	Derived. `Total_Raised` is the sum of all UTXOs on the chain matching the Identity Script.	More robust. The state cannot be corrupted; it is simply the physical reality of the coin set.
Transparency	Enforced Announcement. Uses a type script to force public declaration of state.	Enforced Announcement. (Adopted). We incorporated this specific feature from the Overlay model.	We agree with the Overlay model here: Public auditing is non-negotiable for a CCS.
Upgradability	Monolithic. Logic is often baked into a single complex script.	Modular. Separation of `Lock_Script` (Auth) and `Type_Script` (Identity).	Allows replacing the “Judges” (Lock) without destroying the “Project” (Identity).

B.3 Conclusion on Engineering Workload

Alan noted that “Nothing is blocking such a system presently besides the engineering workload.”

By shifting from an Overlay Protocol (which requires maintaining p2p connections between judges) to a Manifest-Driven Protocol (where logic is executed client-side by the prover), we reduce the engineering workload by an estimated 60-70%. We remove the need to write network code, focusing entirely on Transaction Verification Logic (TASM).

Appendix C: Scalability & Permissionless Maintenance

Subject: Handling UTXO Fragmentation without External Infrastructure

Solution: The “Self-Healing” Ledger via Permissionless Consolidation.

C.1 The Fragmentation Reality

In a “Bag of Coins” model, a successful project may accumulate thousands of small UTXOs. Due to prover resource limits (the “Fan-In” constraint), these cannot be swept in a single transaction.

C.2 The “No-Bot” Requirement

We reject the use of “Keeper Bots” or “Overlay Servers” to manage this fragmentation, as they introduce fragility. The system must be maintainable solely by the interested parties (the Developer) using standard client-side software.

C.3 Solution: The Consolidation Bypass

We introduce a Permissionless Consolidation Path in the CCS_Authority_Lock.

Rule: Any transaction that consumes Treasury UTXOs is valid without signatures IF AND ONLY IF the total value is returned to new UTXOs with the exact same Script Hash.
Fee Market: The transaction fee for this maintenance must be paid by an external input (e.g., the Developer’s wallet). The Treasury principal cannot be used for fees during consolidation.

C.4 The Workflow (Client-Side)

When the Developer attempts to claim a milestone:

Analysis: The wallet scans the UTXO set.
Auto-Merge: If fragmentation is high (), the wallet automatically generates and broadcasts “Merge Transactions” using the Consolidation Bypass. This costs the Developer a nominal fee (dust) but requires no Judge interaction.
Payout: Once the set is consolidated, the wallet generates the final Payout Transaction using the Judge Votes.

This ensures the system remains Leaderless, Serverless, and Robust.

Appendix D: The Maintenance Manifest Standard

Subject: Automated State Optimization & Permissionless Housekeeping

Goal: Enabling generic wallets to perform contract-specific maintenance (e.g., UTXO consolidation) without hardcoded logic.

D.1 The Problem: Entropy & Prover Limits

In the “Bag of Coins” architecture, the state naturally fragments over time.

Entropy: A successful CCS project may accumulate 1,000+ tiny UTXOs (donations).
Prover Limits: A single Neptune transaction cannot consume an arbitrary number of inputs due to “Fan-In” constraints on the STARK prover (typically capped at ~25 inputs per transaction for efficiency).
The Wallet Gap: A generic wallet knows how to send money, but it does not know that this specific contract requires periodic “Merging” to remain spendable. Hardcoding “CCS Merge Logic” into the wallet software violates the principle of a general-purpose wallet.

D.2 The Solution: The `maintenance` Array

We extend the NMS-1 (Neptune Manifest Schema) to include a maintenance section. This section allows the developer to define “Housekeeping Scripts” that the wallet can execute autonomously when specific state conditions are met.

This shifts the logic from “Hardcoded in Client” to “Declared in Data.”

D.3 Schema Specification

The maintenance array contains objects with the following fields:

task_name: Human-readable label (e.g., “Consolidate Dust”).
type: The operation category.
merge_self: Consolidate many UTXOs of same type into fewer UTXOs.
sweep_decay: Spend expired UTXOs to a target address.
trigger: A logic condition that tells the wallet when to recommend this action.
Supported vars: input_count, total_balance, utxo_age.
witness_mode: Defines authentication requirements.
signature: Requires user approval/private key.
bypass: Requires no signature (relies on strict logic constraints, e.g., Value In == Value Out).

D.4 Concrete Example: CCS Dust Consolidation

Below is the JSON that would appear in the CCS Manifest. It teaches the wallet how to perform the Permissionless Consolidation discussed in Appendix C.

{
  "maintenance": [
    {
      "task_name": "Optimize Vault Storage",
      "description": "Merges small donation UTXOs to ensure funds remain accessible for payout.",
      "type": "merge_self",
      "priority": "high",

      // The Trigger: When does the wallet suggest this?
      "trigger": {
        "condition": "utxo_count(scripts.identity_type_hash) > 20",
        "action": "prompt_user_toast",
        "message": "Vault fragmentation detected. Click to optimize."
      },

      // The Execution Logic
      "execution": {
        "max_inputs_per_tx": 25,
        "fee_payer": "external_wallet", // Developer pays fee, Treasury preserved
        "constraints": {
          "input_script": "scripts.identity_type_hash",
          "output_script": "scripts.identity_type_hash",
          "balance_invariant": "exact" // Sum(In) == Sum(Out)
        }
      },

      // The Authentication
      // This tells the wallet: "Don't ask for a Judge Key. Just build the proof."
      "witness_mode": "bypass"
    }
  ]
}

D.5 Wallet Behavior Flow

When a generic wallet loads this Manifest:

Passive Scan: It counts the UTXOs held by the Treasury script.
Trigger Check: If the count is 5, it does nothing. If the count is 50, the trigger condition (> 20) evaluates to TRUE.
User Prompt: The wallet displays a “Maintenance Available” icon.
Auto-Execution: Upon clicking, the wallet reads witness_mode: "bypass". It immediately constructs 2 transactions merging 25 inputs each, generates the STARK proofs verifying balance_invariant: "exact", and broadcasts them.

This ensures the CCS remains performant forever, even if the wallet developers never specifically wrote code for “Crowdfunding Optimization.”

reference: here is the AI conversation that culminated in this design document.

LostInTranslation · December 23, 2025, 7:39pm

Awesome news, danda! This is no small task, but pulling it off would be a huge win and a major growth driver for the ecosystem

danda · December 24, 2025, 1:43am

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.

aszepieniec · December 24, 2025, 7:13am

This is an ambitious project, Dan. I like it

One of the motivations for the bag-of-coins treasury as opposed to the single-UTXO treasury is the inability of the latter to handle multiple donations within one block. On this note, you should know that transaction chaining is not currently supported, but is on the roadmap. Once it is implemented, you will be able to spend UTXOs that are produced by transactions that are not confirmed yet. However, with transaction chaining achieved, there will still be the problem that the initiator needs to be aware of the transaction that they are building on top of. So the motivation for the bag-of-coins treasury still holds in this world but the problem it avoids is slightly less acute.

By placing both scripts on the same UTXO, the Neptune consensus engine requires both the NPT conservation rules and the CCS identity rules to return True

Technically, these scripts don’t return true or false; they either halt gracefully, or else crash and burn.

I’m not sure I understand the solution to the chicken-and-egg problem. And I’m not sure the LLM does either

Maybe you can get inspiration from the chicken-and-egg problem and its solution for SingleProofs. One of the ways to generate a SingleProof for a transaction is to Update it (bumping the timestamp or mutator set accumulator), and another way is to Merge two transactions that are supported by SingleProofs. In either case, the SingleProof program needs to invoke the Triton VM verifier to verify a particular claim, and that claim consists of a program hash, an input, and an output. That program hash must be the hash of the SingleProof program. How does the SingleProofprogram know its own hash? It cannot be hardcoded; or rather, hardcoding it requires first solving a hard problem related to Tip5 and preimage resistance.

Here’s how it is solved. Whenever any Triton VM program starts, its stack is not empty. It contains 16 elements. The bottom 5 elements of the stack agree with the hash of the program that is being run. The very fist thing the SingleProof program does is store this digest to memory for later use. Then later on when it needs to compile a Claimwith which to invoke the Triton VM verifier, the program hash field of that claim can be populated by reading the digest from memory.

“I will only validate this transaction if the Output UTXO carrying my identity ALSO carries a cleartext public announcement of its new state.”

Announcements used to be called public announcements but we dropped that adjective because they are always public. More importantly, announcements are tied to transactions, not to UTXOs.

Balance: u64 (The visible NPT amount).

You probably want to use a u128 to store the number of nau; otherwise you are losing precision.

This [Janitorial sweeping] would be performed within neptune-core nodes operating in a composer role.

Have you considered the incentives for Composers? Because if it hurts their Composition time then are probably not going to do it.

it simply follows the “Search and Merge” instructions provided in the on-chain IBD Manifest.

Wait, what’s the IBD Manifest?