Quick Start
Go from zero to your first compiled policy in 5 minutes.
Welcome to Matador! This guide will walk you through setting up your environment, writing a simple "Hello World" policy, and compiling it to bytecode.
Prerequisites
- Node.js v20 or higher
- A terminal (Terminal, iTerm, PowerShell, WSL)
Install the CLI
The Matador CLI is your primary tool for compiling and validating policies. Install it globally or as a dev dependency in your project.
npm install -D matador-policy-cliyarn add -D matador-policy-clipnpm add -D matador-policy-cliCreate Your First Policy
Create a new file named hello.matador. This simple policy will only allow transactions that send ETH to a specific "treasury" address.
// Define the policy name and version
permission HelloMatador -> 1.0.0 {
// Define runtime parameters
parameters: {
treasury: address
}
// Define the conditions
when: {
all {
// Rule 1: The destination must be the treasury
context.target == parameters.treasury,
// Rule 2: Must be sending some value
context.value > 0
}
}
}Compile
Run the compiler to transform your readable policy into machine-executable bytecode.
npx matador-policy-cli compile hello.matadorYou should see output similar to:
✔ Compiled hello.matador to hello.jsonVerify Output
Open the generated hello.json file. You will see the compiled artifact ready for on-chain deployment.
{
"hexData": "0x1205...",
"metadata": {
"permission": "HelloMatador",
"specVersion": "1.0.0",
"instructionCount": 4
}
}What Just Happened?
- Parsing: The CLI parsed your
.matadorfile and validated the syntax. - Compilation: It converted your logic (
all,==,>) into optimized opcodes (TARGET_CHECK,VALUE_CHECK). - Encoding: It packed these opcodes into a compact hex string (
hexData).
Next Steps
Now that you have compiled a policy, you are ready to explore more advanced patterns.
Authoring Workflow
Learn the full lifecycle of policy development.
Integration Guide
Learn how to deploy this bytecode to a smart account.
Troubleshooting
Common Issues
"Command not found": Ensure you installed the package or use npx prefix.
"Syntax Error": Check for missing commas between conditions in the all {} block.