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 write-capable lifecycle entry
fn main() -> bool {
// Rule 1: The destination must be the treasury
if (context.target != parameters.treasury) {
return false;
}
// Rule 2: Must be sending some value
if (context.value == 0) {
return false;
}
return true;
}
}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
main()function into callable policy bytecode. - 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 semicolons after return, let, and assignment statements.