ColorChain — Verifiable Swap Receipts

Tamper-evident cryptographic receipts for mobile asset swaps.

Comment

Inspiration

ColorChain is a mobile-first digital asset ecosystem with its own Android wallet, custom blockchain, touch-based mining, peer-to-peer synchronization, messaging, games, an internal exchange called Entropy DEX, and an External Asset Gateway.

Before OpenAI Build Week, ColorChain already supported test swaps between two internal ecosystem assets:

  • LBUP, the primary ColorChain asset
  • CENORA, a separate internal asset

The exchange flow worked, but users did not have a portable and independently verifiable record of what happened during a completed swap.

For Build Week, we created Verifiable Swap Receipts V1: deterministic, tamper-evident cryptographic receipts generated from the authoritative result of an Entropy DEX swap.

Our goal was to make internal asset operations easier to inspect and verify without exposing private keys, duplicating exchange logic, or claiming that a pre-production prototype is already a public financial market.

What it does

After a successful Entropy DEX operation, ColorChain creates a structured swap receipt for either direction:

  • LBUP_TO_CENORA
  • CENORA_TO_LBUP

The receipt is not created merely because the UI reports success.

The application first records the balances before the operation, executes the existing canonical swap or redeem flow, and then waits until the same operation reference appears in the authoritative local token-ledger state.

Only after that confirmation does the application create and store the receipt.

Each receipt contains:

  • receipt format and version
  • deterministic receipt ID
  • UTC timestamp
  • network and environment mode
  • swap direction
  • input asset and amount
  • output asset and amount
  • exchange-rate model
  • input balance before and after
  • output balance before and after
  • LBUP balance before and after
  • CENORA balance before and after
  • canonical operation or redeem reference
  • referenced block hash and height when available
  • ledger tip metadata before and after
  • owner public address
  • deterministic canonical payload
  • SHA-256 receipt hash
  • optional wallet public-key signature
  • explicit test and pre-production markers
  • verification status

The receipt uses integer monetary values rather than floating-point calculations.

Users can:

  • open the latest receipt after a swap
  • browse local swap history
  • reopen receipts after restarting the Android application
  • view all safe receipt fields
  • recompute and verify the receipt hash
  • verify the optional wallet signature
  • copy deterministic JSON
  • share the JSON through the Android share sheet

Verification can return statuses including:

  • VALID_HASH_AND_SIGNATURE
  • VALID_HASH_ONLY
  • INVALID_HASH
  • INVALID_SIGNATURE
  • UNSUPPORTED_VERSION
  • MALFORMED_RECEIPT

If a protected value such as the amount, direction, timestamp, operation reference, balance, or ledger metadata is modified, the recomputed hash no longer matches and verification fails.

How we built it

We implemented the feature directly inside the existing ColorChain / TamaraShadow Android and JVM codebase.

We did not create a parallel demo ledger or duplicate the exchange calculation inside the UI.

The existing ColorChain components remain authoritative:

  • Entropy DEX
  • DexManager
  • TokenLedger
  • CENORA conversion logic
  • signed redeem-request flow
  • vault release flow
  • wallet and UTXO state
  • existing exchange-operation identifiers

The receipt layer observes the result of these existing systems without changing settlement rules.

The implementation includes:

  • an immutable SwapReceipt model
  • canonical serialization with a fixed field order
  • UTF-8 encoding
  • locale-independent values
  • UTC timestamps with millisecond precision
  • SHA-256 receipt hashing
  • deterministic receipt IDs
  • optional signing through the existing wallet API
  • secp256k1 signature verification
  • public-key-to-address validation
  • authoritative operation matching through TokenOperationEvidence
  • duplicate rejection
  • corruption detection
  • thread-safe local receipt history
  • Android AtomicFile persistence
  • a private application storage location
  • a bounded receipt history
  • deterministic JSON export
  • receipt history and detail activities
  • English and Russian Android resources
  • JVM tests for deterministic hashing, tampering, persistence, directions, duplicate handling, confirmation policy, and signatures

The existing wallet private key is never exported into the receipt model or JSON output. Signing is performed through the existing wallet API, while receipts store only public verification material and the resulting signature.

Deterministic verification

A cryptographic hash is only meaningful when every implementation agrees on the exact bytes being hashed.

For that reason, the canonical receipt format uses:

  • one fixed field order
  • explicit field names
  • UTF-8
  • locale-independent formatting
  • base-10 integer amounts
  • preserved UTC timestamps
  • normalized hexadecimal fields
  • explicit versioning
  • explicit testMode=true
  • explicit productionSettlement=false

The SHA-256 hash of that canonical payload becomes both the receipt hash and the deterministic receipt ID.

The displayed Android text, language, spacing, and localized labels are not used as authoritative hash input.

This means the same receipt data produces the same cryptographic result regardless of the user-interface language.

Existing foundation vs. Build Week contribution

ColorChain was an existing project before OpenAI Build Week.

The following capabilities already existed:

  • Android wallet
  • ColorChain blockchain
  • LBUP asset model
  • CENORA asset model
  • Entropy DEX interface
  • test LBUP to CENORA conversion
  • test CENORA to LBUP redeem flow
  • wallet persistence
  • P2P synchronization
  • mining
  • Messenger
  • games
  • External Asset Gateway
  • Android gen and std flavors

The new Build Week contribution was Verifiable Swap Receipts V1, including:

  • canonical receipt schema
  • deterministic receipt ID
  • SHA-256 integrity verification
  • tamper detection
  • optional wallet signature
  • operation-reference confirmation
  • block and ledger evidence metadata
  • balances before and after
  • local atomic persistence
  • duplicate protection
  • corruption handling
  • Android receipt history
  • Android receipt detail screen
  • JSON copy and sharing
  • English and Russian interface resources
  • JVM receipt tests
  • Build Week architecture and demonstration documentation

The Build Week implementation was created in two dedicated commits:

  • bfa9ec6568905f6ea7f9b37e926f599bf0142034 — Add verifiable Entropy DEX swap receipts

  • d3d9ae9a12e882ce597acf639710e355361c33a4 — Complete Android swap receipt UI integration

Development branch:

build-week/verifiable-swap-receipts

How we used Codex and GPT-5.6

We used Codex to inspect the existing repository, trace the real Entropy DEX execution paths, identify authoritative TokenLedger evidence, implement the receipt architecture, integrate the Android interface, create tests, run project checks, prepare documentation, and isolate the Build Week changes into dedicated commits.

We used GPT-5.6 for architecture review, canonicalization design, integrity and privacy boundaries, threat modeling, acceptance criteria, test planning, terminology review, and preparation of the Devpost submission.

AI is not used to calculate authoritative balances, approve swaps, determine ledger validity, or decide whether an operation succeeded.

Those decisions remain inside deterministic ColorChain application logic.

Challenges

The largest challenge was adding a cryptographic evidence layer to a large existing application without changing the exchange itself.

We had to ensure that:

  • a receipt was not created for an unsuccessful operation
  • a UI success response alone was not treated as authoritative
  • the real operation reference was later found in TokenLedger state
  • balances came from existing application state
  • both exchange directions used the same receipt architecture
  • Android and JVM produced identical canonical hashes
  • receipt history survived application restarts
  • duplicate operations did not create duplicate receipts
  • one damaged entry did not destroy the complete history
  • signatures could be verified without exposing private-key material
  • existing wallet, mining, consensus, P2P, Messenger, Gateway, and game modules remained separate from receipt logic

Accomplishments that we are proud of

We are especially proud that the receipt system is connected to the existing ColorChain operation model instead of being a standalone hackathon simulation.

The implementation:

  • supports both Entropy DEX directions
  • records balances before and after
  • binds receipts to real operation references
  • includes available block and ledger metadata
  • uses deterministic SHA-256 verification
  • supports optional wallet-signature verification
  • detects modified protected fields
  • survives Android application restarts
  • provides a practical history and detail interface
  • exports safe deterministic JSON
  • does not expose seed phrases or private keys
  • does not alter consensus or asset economics

What we learned

The most important lesson was that cryptographic verification depends as much on canonicalization as it does on the hash algorithm.

Field order, integer normalization, timestamps, encoding, versioning, and hexadecimal normalization must all be explicitly defined.

We also learned that useful local evidence does not require exaggerated claims.

A receipt can prove that its protected fields have not changed and that it corresponds to an operation observed in the application’s canonical local state.

That does not automatically make it a public-market settlement, a third-party audit, or an immutable on-chain financial statement.

What’s next

Future versions may add:

  • QR-based receipt exchange
  • optional receipt synchronization between devices
  • independent verification tools
  • a public receipt schema specification
  • richer explorer integration
  • optional anchoring of receipt hashes into ColorChain blocks
  • external auditor verification flows
  • more advanced corruption recovery
  • user-controlled export bundles

ColorChain remains a technical MVP and pre-production prototype.

Verifiable Swap Receipts V1 does not represent public liquidity, a guaranteed market value, production exchange settlement, legal finality, or confirmation by an external financial institution.

Built With

Share this project:

Updates