Cardano Invoicing

Status: partly runnable, last checked 2026-11-02. Needs access to the private cardano-invoicing repo, branch dev. Preview testnet only. We haven’t re-run these steps for this page, and they use a test token rather than a stablecoin.

This runs the invoice validator through its lifecycle. It isn’t connected to SPORE, SPAWN or Calvin yet.

Prerequisites

Aiken v1.1.24
Node.js 18 or later
A Blockfrost project key for preview
A funded preview wallet from the testnet faucet

Setup


aiken build


cd mesh-test && npm install && cp .env.example .env

Put the Blockfrost key and a test-only mnemonic in .env. Never use a wallet that holds real funds.

Run the lifecycle


npm run setup

This writes state.json with the applied parameters and script address. The address exists now, with nothing deployed.


npm run lock

This mints a test token and locks it at the script address.

Then pick one ending. To pay the recipient:


npm run complete

Or, once the expiry printed by setup has passed, refund the payer:


npm run cancel

Re-run setup only when you want a new invoice. New parameters mean a new address.

Check the result

Look up the script address and transaction on a preview explorer. The locked UTxO should be gone, and the funds should be at the recipient or payer address.

Common problems

Symptom	Cause
`cancel` fails	Expiry hasn’t passed. The validity lower bound must be after `expiry`
`complete` fails	An output goes somewhere other than the recipient. Change has to go there too
Fails on quantity	The UTxO doesn’t hold exactly `value`
Script hash differs	Different parameters or compiled code. Keep using the same `state.json`

Read the known limits before using this as a basis for anything else.

Explore invoicing: Programmable Invoicing and invoicing on Cardano