DE-UPLC

December 1, 2025 · View on GitHub

DE-UPLC is a Visual Studio Code extension that provides a powerful debugging environment for UPLC (Untyped Plutus Core) — the low-level smart contract language used in the Cardano blockchain.

Features

🔍 Step-by-step debugging — Execute UPLC scripts one step at a time
🎯 Breakpoints — Set breakpoints on specific terms to pause execution
📊 Machine State Inspection — View the CEK machine state including stack, environments, and values
💰 Budget Tracking — Monitor execution units and memory consumption in real-time
📝 Script Context Viewer — Inspect the full transaction context (ScriptContext)
🌐 Data Providers — Fetch UTXOs and protocol parameters from Koios API or local files

📚 New to UPLC? Read UPLC and the CEK Machine for a detailed explanation of the language and execution model.

Installation

From VSIX File (Recommended)

Download the latest .vsix file from the Releases page
Open VS Code
Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) to open the Command Palette
Type "Install from VSIX" and select Extensions: Install from VSIX...
Navigate to the downloaded .vsix file and select it
Reload VS Code when prompted

Alternatively, install via terminal:

code --install-extension de-uplc-0.0.1.vsix

From Source

See Building from Source section below.

Quick Start

1. Prepare Your Transaction

The extension supports two input formats:

Format A: Plain CBOR Hex

Simply create a file containing the raw transaction CBOR hex string:

84a400d9010281825820abc123...

Supported extensions: .tx, .cbor, .txt, .bin

When using plain hex, the extension will automatically fetch required UTXOs and protocol parameters from configured data providers (Koios API or offline file).

Format B: JSON with Full Context

Create a JSON file with the transaction and all required context data:

{
  "transaction": "84a400d9010281825820abc123...",
  "network": "mainnet",
  "utxos": [
    {
      "txHash": "abc123...",
      "outputIndex": 0,
      "address": "addr1...",
      "value": {
        "lovelace": "1000000",
        "assets": {
          "policyId.assetName": "100"
        }
      },
      "datumHash": null,
      "inlineDatum": "d8799f...",
      "referenceScript": {
        "type": "PlutusV2",
        "script": "59052d01..."
      }
    }
  ],
  "protocolParams": {
    "costModels": { "PlutusV1": [...], "PlutusV2": [...], "PlutusV3": [...] },
    "maxTxExMem": "14000000",
    "maxTxExSteps": "10000000000",
    "protocolVersion": { "major": 10, "minor": 0 }
  }
}

This format is useful when you want to debug offline or with custom UTXOs/parameters.

📁 Examples & Type Definitions:

Full context example: test-tx.json
Type definitions: src/common.ts — see DebuggerContext, UtxoOutput, ProtocolParameters

2. Configure Data Providers (Optional)

If you're using Format A (plain hex), configure how the extension fetches missing UTXOs and protocol parameters:

Option 1: Koios API (Default)

The extension will automatically fetch data from Koios. Optionally configure:

Go to Settings → search for "DE-UPLC"
Set deuplc.providers.koios.apiKey if you have one

Option 2: Offline File

Go to Settings → search for "DE-UPLC"
Enable deuplc.providers.offline.enabled
Set deuplc.providers.offline.filePath to your JSON file with UTXOs and protocol params

📁 Example: test-file-provider.json — offline data provider file with UTXOs and protocol parameters

3. Start Debugging

Open the UPLC Debugger sidebar (click the debugger icon in the Activity Bar)
Click "Open Transaction" button in the Transaction panel to load your file
Select a redeemer from the dropdown (e.g., spend#0, mint#1)
Click the Start button (▶️)

User Interface

The extension adds a dedicated sidebar with the following panels:

Panel	Description
Main Controls	Debugger controls (Start, Pause, Step, Stop, Refresh) and script information
Transaction	Open Transaction button to load a transaction file
Machine Context	View the continuation stack — frames representing pending operations
Machine State	Inspect current term being evaluated or value being returned
Environments	Browse variable bindings and closures
Logs	View trace output from the script
Breakpoints	Manage your breakpoints

Debugger Controls

Button	Action	Description
▶️	Start/Continue	Start debugging or continue execution
⏸️	Pause	Pause execution (when running)
⏭️	Step	Execute single step
🔄	Refresh	Reset debugging session to beginning
⏹️	Stop	Stop debugging session

Budget Display

When debugging is active, you'll see real-time budget tracking:

Ex units: Execution units spent / available
Memory units: Memory units spent / available

Budget values turn red when limits are exceeded.

Working with Scripts

Viewing the Script

Select a redeemer from the dropdown
Click "Show script" to open the decompiled UPLC in a new tab
The script viewer shows the hierarchical term structure

Setting Breakpoints

Open the script viewer (click "Show script")
Click on the line number gutter, or:
- Right-click → Toggle Term Breakpoint
- Press F9 on a line with a term
Breakpoints appear in the Breakpoints panel

Viewing Script Context

Click "Show context" to view the full ScriptContext including:

Transaction inputs/outputs
Minting policies
Certificates
Withdrawals
Signatories
Validity range
And more...

Keyboard Shortcuts

Shortcut	Action
`F9`	Toggle breakpoint (in script viewer)
`Ctrl+Alt+H`	Toggle inlay hints

Configuration

Access settings via File → Preferences → Settings → search "DE-UPLC"

Setting	Default	Description
`deuplc.enableInlayHints`	`true`	Show inlay hints in the term viewer
`deuplc.providers.koios.apiKey`	`""`	Optional Koios API key
`deuplc.providers.timeout`	`30000`	HTTP timeout in milliseconds
`deuplc.providers.retryAttempts`	`3`	Number of retry attempts for network errors
`deuplc.providers.offline.enabled`	`true`	Enable offline/file-based data provider
`deuplc.providers.offline.filePath`	`""`	Path to JSON file with UTXOs and protocol params

Building from Source

Prerequisites

Node.js 18+
Rust + wasm32-unknown-unknown target
wasm-pack (cargo install wasm-pack)

Build Steps

# Clone the repository
git clone https://github.com/cardananium/de-uplc.git
cd de-uplc

# Install dependencies
npm ci

# Generate schemas and types
npm run generate-all

# Build WASM module
cd rust-src
./build-quick.sh
cd ..

# Build extension
npm run package

# Create .vsix package
npx vsce package

Or use the automated build script:

./build-extension.sh

Troubleshooting

WASM Build Errors

# Install wasm-pack
cargo install wasm-pack

# Add Rust WASM target
rustup target add wasm32-unknown-unknown

Extension Not Loading

Check the VS Code Developer Console (Help → Toggle Developer Tools)
Look for [DE-UPLC] messages in the console

Data Provider Issues

Verify your JSON file path is correct
Check that the JSON structure matches the expected format
For Koios, ensure network connectivity

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

See the LICENSE file for details.