COTS is a CLI tool for simulating Cardano transactions offline, calculating fees, managing UTXOs, and exporting transactions in Cardano CLI or Koios API formats.
stack buildcotscli simulate -c examples/config.json -f alice -t <destination_address> -a 100000000 -vcotscli simulate -c examples/config.json -f alice -t <destination_address> -a 100000000 --export-cardano-cli
cotscli simulate -c examples/config.json -f alice -t <destination_address> -a 100000000 --export-koioscotscli validate -c examples/config.jsoncotscli simulate -c examples/config.json -f alice -t <destination_address> -a 100000000 --script plutus.plutus --datum datum.json --redeemer redeemer.jsonSee examples/config.json and examples/config.yaml for the expected structure.
simulate: Simulate a Cardano transactionvalidate: Validate a configuration or transactionexport: Export a transaction (Cardano CLI, Koios)update-protocol: Update protocol parametersversion: Show version
-c, --config FILE: Configuration file (JSON or YAML)-f, --from WALLET: Source wallet name-t, --to ADDRESS: Destination address-a, --amount: Amount in lovelace-s, --script: Plutus script file--datum: Datum JSON file--redeemer: Redeemer JSON file--export-cardano-cli: Export in Cardano CLI format--export-koios: Export in Koios API format-o, --output: Output file-v, --verbose: Verbose output
To run unit and integration tests:
stack testMIT
COTS implements the same commands as cardano-cli for a familiar experience:
# Build transaction (offline simulation)
cotscli transaction build --tx-in <input> --tx-out <output> --out-file tx.raw
# Simulate transaction
cotscli transaction simulate --tx-file tx.raw
# Sign transaction
cotscli transaction sign --tx-body-file tx.raw --signing-key-file key.skey --out-file tx.signed
# Validate transaction
cotscli transaction validate --tx-file tx.signed
# Export transaction
cotscli transaction export --tx-file tx.signed --out-file tx.json
# Decode transaction
cotscli transaction decode --tx-file tx.signed# Generate payment key pair
cotscli address key-gen --verification-key-file payment.vkey --signing-key-file payment.skey
# Build address
cotscli address build --payment-verification-key-file payment.vkey --out-file address.addr
# Get address info
cotscli address info --address addr_test1...# Generate stake key pair
cotscli stake-address key-gen --verification-key-file stake.vkey --signing-key-file stake.skey
# Build stake address
cotscli stake-address build --stake-verification-key-file stake.vkey --out-file stake.addr
# Get stake address info
cotscli stake-address info --address stake_test1...# Build minting transaction
cotscli mint build --tx-in <input> --tx-out <output> --mint <mint-spec> --out-file mint.raw
# Calculate minting fees
cotscli mint calculate --policy-id <policy> --asset-name <name> --quantity <amount># List UTXOs
cotscli utxo list --address addr_test1...
# Reserve UTXOs
cotscli utxo reserve --address addr_test1... --amount 1000000 --out-file reserved.json# Update protocol parameters
cotscli protocol update --protocol-params-file params.json --out-file updated.jsonCOTS uses SQLite to manage the UTxO state persistently and robustly. This allows:
- Persistence between sessions: Track UTxOs, balances, protocol parameters
- Accurate simulation: Mimic the state evolution of a real Cardano node
- Developer control: Snapshots, imports/exports, reset
- Portability: Single database file, easy to version and debug
# Initialize a new database
cotscli database init --db-file cots.db
# Reset the database (deletes all tables)
cotscli database reset --db-file cots.db
# Create a snapshot of the current state
cotscli database snapshot --db-file cots.db --out-file snapshot.db
# Load a snapshot
cotscli database load-snapshot --snapshot-file snapshot.db --db-file cots.db
# Import UTxOs from a JSON file
cotscli database import-utxo --db-file cots.db --utxo-file utxos.json
# Export UTxOs to a JSON file
cotscli database export-utxo --db-file cots.db --out-file exported_utxos.json
# Inspect database statistics
cotscli database inspect --db-file cots.dbThe SQLite database contains the following tables:
utxos: Current UTxO state by addresstx_history: Simulated transaction historywallets: Wallet addresses and metadataprotocol_params: Protocol parameters in usescript_logs: Plutus script execution resultsassets: Token/asset metadata
- Initialize:
cotscli database init - Import UTxOs:
cotscli database import-utxo --utxo-file initial_utxos.json - Simulate transactions: UTxOs are automatically updated
- Create snapshots:
cotscli database snapshotto save state - Export results:
cotscli database export-utxoto share
| Feature | SQLite | JSON |
|---|---|---|
| Data integrity | ✅ ACID-safe | ❌ Possible corruption |
| Performance | ✅ Fast read/write | ❌ Slower with large state |
| Advanced queries | ✅ Full SQL | ❌ Manual loading/filtering |
| Multi-table support | ✅ Easy | ❌ Manual nesting |
| Portability | ✅ Single file | ✅ Single file |
- Accurate fee calculation according to Cardano rules
- Automatic min-UTxO validation
- Multi-asset support
- Plutus script fee calculation
- Full simulation of native token minting
- Support for minting policies (native and Plutus)
- Asset metadata validation
- Minting fee calculation
- Address derivation according to CIP-1852
- Automatic change address rotation
- BIP-39 mnemonic phrase support
- Payment and staking key management
- Branching states for experiments
- Differentiation between snapshots
- State version management
- Full configuration export/import
- Fork or clone the repository
- Build with
stack build - Run tests with
stack test - Use the CLI as described above
For more details, see the documentation in the docs/ folder and example configs in examples/.