UTXO Compiler

English

中文

English

中文

Appearance

Installation ​

This page explains how to check whether your utxo_compiler binary works. utxo_compiler is a command-line program: you run it in a terminal, pass it a .ct contract file, and it outputs compiled contract data.

Download ​

Download the current release from the Downloads page.

Supported Platforms ​

  • Linux
  • Windows 64-bit
  • Windows 32-bit
  • macOS: planned

Release Package Structure ​

Linux Package Structure ​

After extracting the Linux package, the directory usually looks like this:

utxo_compiler-v1.0.0-linux/
├── bin/
│   └── utxo_compiler    # Executable
├── doc/                 # Documentation directory
├── install.sh           # Installation script
├── share/apc/stdlib/    # Standard library contracts
└── VERSION              # Version information

Windows Package Structure ​

The Windows package includes DLL files required at runtime. A DLL is a dependency file that the executable loads when it starts.

utxo_compiler-v1.0.0-windows-64/32/
├── utxo_compiler.exe    # Windows executable
├── libstdc++-6.dll      # C++ standard library
├── libgcc_s_seh-1.dll   # GCC runtime library for the 64-bit package
├── libgcc_s_dw2-1.dll   # GCC runtime library for the 32-bit package
├── libwinpthread-1.dll  # Multi-threading support library
├── stdlib/              # Standard library contracts
├── doc/                 # Documentation directory
├── install.bat          # Windows installation script
├── DEPENDENCIES.txt     # Dependency library description
└── VERSION              # Version information

Testing and Verification ​

Step 1: Check That the Program Starts ​

Open a terminal in the extracted directory and run the version command.

Linux release package:

bash
./bin/utxo_compiler --version

Debian or Ubuntu package:

bash
utxo_compiler --version

Windows release package:

powershell
.\utxo_compiler.exe --version

If you built the compiler from the source tree, the executable is usually under build/bin:

bash
./build/bin/utxo_compiler --version

You can also do a basic check for an extracted Windows release package on Linux with Wine:

bash
# Install Wine first if needed
sudo apt install wine

wine ./utxo_compiler-v1.0.0-windows-64/utxo_compiler.exe --version
wine ./utxo_compiler-v1.0.0-windows-32/utxo_compiler.exe --version

Step 2: Compile a Minimal Contract ​

Create a file named p2pkh.ct:

python
Contract P2PKH:
    def verify(sig: hex, pubKey: hex):
        pubKeyHash = Hash160(pubKey.Clone())
        EqualVerify(pubKeyHash, self.pubKeyHash)
        result = CheckSig(sig, pubKey)

This contract checks whether a signature matches the private key behind an expected public-key hash. Key parts:

  • sig: the transaction signature supplied when spending the UTXO.
  • pubKey: the public key; the contract computes its Hash160.
  • self.pubKeyHash: the expected public-key hash embedded in the locking script.
  • Clone(): copies pubKey, because Hash160 consumes its input and CheckSig needs the public key again.

Compile it:

bash
./bin/utxo_compiler p2pkh.ct

If compilation succeeds, the compiler, parser, and bytecode generation path are working. Next, follow Tutorial 1: P2PKH to debug and use the contract.

Verify Windows Package Dependencies ​

If a Windows user cannot start the program, check whether the package includes the required DLL files:

bash
# Check DLL dependencies of the Windows executable
x86_64-w64-mingw32-objdump -p utxo_compiler.exe | grep "DLL Name"

# Verify DLLs included in the package
python -m zipfile -l dist/utxo_compiler-v1.0.0-windows-64.zip | grep "\.dll"

Beginner Pitfalls ​

  • Using the wrong path: in the portable Linux release package, the compiler is usually ./bin/utxo_compiler. In the Debian package, it is usually available as utxo_compiler.
  • Copying only the Windows .exe: keep the DLL files next to utxo_compiler.exe.
  • Pointing to a missing .ct file: the last command argument must be an existing contract file.
  • Testing on-chain first: compile and debug locally before building a real transaction.

Quick Review ​

  • utxo_compiler compiles .ct contracts into locking-script bytecode.
  • After installation, run --version, then compile a minimal contract.
  • Windows packages need the .exe and DLL files together.
  • If the same value is used twice in contract code, you usually need .Clone().

Next Steps ​

🇨🇳 中文版