PyVax — Smart Contracts for Agents

Write pure Python. Deploy verified smart contracts on Avalanche C-Chain. No Solidity required.

pipx install pyvax-cli
pyvax new my-agent-vault --template AgentVault
pyvax compile
pyvax deploy AgentVault --chain fuji

Try it in the browser — no installation needed: pyvax.xyz/playground

What is PyVax?

PyVax is a Python-to-EVM compiler toolchain that transpiles standard Python classes into optimized EVM bytecode deployable on Avalanche C-Chain. It is built for the next generation of onchain applications: AI agents, autonomous game economies, and multi-agent DeFi — where developers think in Python, not Solidity.

from pyvax import Contract, action, agent_action, human_action

class AgentVault(Contract):
    balances: dict = {}
    total_deposits: int = 0

    @action
    def deposit(self, amount: int):
        """Any wallet can deposit"""
        self.require(amount > 0, "Amount must be positive")
        sender = self.msg_sender()
        self.balances[sender] = self.balances.get(sender, 0) + amount
        self.total_deposits = self.total_deposits + amount
        self.emit("Deposit", sender, amount)

    @agent_action
    def autonomous_rebalance(self):
        """Only verified AI agent wallets can call this"""
        pass

    @human_action
    def withdraw(self, amount: int):
        """Only human wallets — agents cannot drain funds"""
        sender = self.msg_sender()
        self.require(self.balances.get(sender, 0) >= amount, "Insufficient balance")
        self.balances[sender] = self.balances[sender] - amount
        self.emit("Withdraw", sender, amount)

pyvax compile
# ✔ Parsed syntax mapping
# ✔ AST generation successful
# => build/AgentVault.json (ABI + Bytecode)

pyvax deploy AgentVault --chain fuji
# ✓ Live at 0x4a2f3e2b1c8f... · Gas: 312,048

Architecture

graph LR
    A[Python Source .py] --> B[PyVax AST Parser]
    B --> C[EVMBytecodeGenerator]
    C --> D[ABI + Bytecode JSON]
    D --> E[Avalanche C-Chain]
    F[AgentWallet SDK] -->|autonomous execution| E

The transpiler parses your Python via the built-in ast module and emits raw EVM opcodes directly — no Python interpreter is ever deployed on-chain.

Installation

We recommend using pipx to install PyVax to avoid conflicts with system Python environments:

# 1. Install pipx (if you don't have it)
# On macOS/Linux: brew install pipx || (sudo apt install pipx && pipx ensurepath)
# On Windows: python -m pip install --user pipx && python -m pipx ensurepath

# 2. Install PyVax CLI
pipx install pyvax-cli

Note: Restart your terminal after running ensurepath for the first time. Requirements: Python 3.9+

Verify your environment:

$ pyvax doctor

PyVax Environment Diagnostic

🟢 Node Runtime      [v20.11.1]
🟢 Python SDK        [v3.12.0]
🟢 pyvax-cli         [v1.0.0]
🟢 Avalanche Fuji    [Connected - ping: 32ms]

Everything looks beautiful. Ready for transpile.

Quick Start

# 1. Scaffold a new project
pyvax new my-vault --template AgentVault --chain fuji
cd my-vault

# 2. Create an agent wallet
pyvax wallet new deployer

# 3. Compile your Python contracts
pyvax compile --optimizer=3

# 4. Deploy to Avalanche Fuji Testnet
pyvax deploy AgentVault --chain fuji

# 5. Call your contract
pyvax call <deployed-address> deposit --args 1000

# 6. Check what was deployed
pyvax info AgentVault

Core Features

🐍 Python-Native Smart Contracts

Write standard, valid Python with type hints. The transpiler maps Python directly to EVM storage and opcodes:

from pyvax import Contract, action

class ERC20(Contract):
    # Type-annotated class vars → EVM storage slots
    total_supply: int = 0
    balances: dict = {}      # dict → mapping(address => uint256)
    allowances: dict = {}
    decimals_: int = 18

    @action
    def transfer(self, to: str, amount: int):
        sender = self.msg_sender()
        self.require(self.balances.get(sender, 0) >= amount, "Insufficient balance")
        self.balances[sender] = self.balances[sender] - amount
        self.balances[to] = self.balances.get(to, 0) + amount
        self.emit("Transfer", sender, to, amount)

🤖 Agent Access Control Decorators

PyVax introduces a three-tier permission system enforced at the EVM level:

This lets you build hybrid contracts where AI agents and humans share the same contract but have strictly segregated permissions — preventing agents from draining human funds and preventing humans from disrupting autonomous logic.

🔑 AgentWallet SDK

from pyvax import AgentWallet

wallet = AgentWallet("trading-bot-v1")
wallet.fund(avax=0.5)

# Pre-flight simulates before signing — drops tx silently if it would revert
# Prevents gas loss from hallucinated or impossible agent actions
receipt = wallet.execute(
    target="0xVault123...",
    method="deposit",
    args=[1000]
)
print(receipt.gas_used)

Multi-agent swarms in Python:

from multiprocessing import Pool

wallets = [AgentWallet(f"worker-{i}") for i in range(10)]

with Pool(10) as p:
    p.map(agent_worker_loop, wallets)

🧪 Testing — No Hardhat, No Docker

Test contracts with standard pytest. MockChain simulates the full EVM in-memory:

from pyvax import MockChain
from contracts.AgentVault import AgentVault

def test_agent_guardrail():
    chain = MockChain()
    human, agent = chain.generate_wallets(2, balance=10.0)
    contract = chain.deploy(AgentVault)

    # Verify @agent_action blocks human wallets at EVM level
    with pytest.raises(chain.TransactionRevertedError):
        human.execute(contract, "autonomous_rebalance", [])

Or use the built-in CLI test runner:

pyvax test
# AgentVault  PASS  2.1kb  5 funcs  0.09s
# ERC20       PASS  1.8kb  4 funcs  0.07s
# Voting      PASS  1.4kb  3 funcs  0.06s
# All 5 test(s) passed!

⛓️ Chainlink VRF — One-Line Verifiable Randomness

class LootBox(Contract):
    @action
    def open_loot(self, player: str):
        # Chainlink VRF Coordinator auto-bound on deploy
        rng_value = self.chainlink_vrf(max_value=100)
        rarity = self._determine_rarity(rng_value)
        self._mint(player, rarity, 1)

VRF Subscription ID binding is prompted automatically:

pyvax deploy LootBox --chain fuji
# Dependency detected: VRF Coordinator
# Please enter your Chainlink Subscription ID: 8492
# Binding VRF dependencies... Deploying.

🎮 ERC-1155 Game Assets

class GameAssets(Contract):
    equipped: dict = {}

    @action
    def mint_material(self, player: str, material_id: int, qty: int):
        self._mint(player, material_id, qty)  # Fungible (gold, wood)

    @action
    def mint_weapon(self, player: str, weapon_id: int):
        self._mint(player, weapon_id, 1)       # Non-fungible (unique sword)

Gas Optimizations (v0.3.0)

PyVax applies three compiler passes automatically — ~15% overall gas reduction:

Plus manual optimization tools:

# Storage slot packing with typed hints
from pyvax import Uint8

class Optimized(Contract):
    # Packs into ONE 256-bit slot (vs three separate slots)
    health: Uint8 = 100
    is_alive: bool = True
    mana: Uint8 = 50

Optimizer levels: --optimizer=0 (none) through --optimizer=3 (aggressive)

Benchmark: PyVax v0.3.0 vs Solidity vs Huff

CLI Reference

Deployment flags

pyvax deploy AgentVault \
  --chain cchain \        # fuji (default) | cchain
  --rpc https://... \     # override RPC endpoint
  --gas-limit 3000000 \   # override auto gas estimation
  --dry-run \             # simulate gas without deploying
  --verify \              # verify on Snowtrace after deploy
  --verbose               # print full EVM trace on failure

Contract Templates

Scaffold any of these with pyvax new <n> --template <T>:

Writing Contracts — Rules

from pyvax import Contract, action

class MyContract(Contract):
    stored: int = 0          # int    → uint256 storage slot
    owner: str = ""          # str    → address storage slot
    flags: dict = {}         # dict   → mapping(address => uint256)
    alive: bool = True       # bool   → bool storage slot

    @action
    def set(self, value: int):
        self.stored = value                        # overflow-safe
        self.emit("Updated", value)                # LOG opcode

    @action
    def guarded(self, amount: int):
        self.require(amount > 0, "Must be > 0")   # REVERT on fail
        sender = self.msg_sender()                 # CALLER opcode
        ts     = self.block_timestamp()            # TIMESTAMP opcode
        block  = self.block_number()               # NUMBER opcode

Rules:

1. Classes inheriting Contract compile to EVM smart contracts
2. @action → public/external. No decorator → internal
3. Type-annotated class variables → EVM storage slots
4. msg_sender(), msg_value(), block_timestamp(), block_number() are implicit globals
5. self.require(cond, "msg") → inline REVERT with ABI-encoded error
6. self.emit("Event", arg1, arg2) → LOG1–LOG4 opcodes

Debugging

PyVax maps EVM revert traces back to Python source:

$ pyvax call 0xVault... withdraw_funds 900

# Trace Output
# Execute Failed: [TransactionRevertedError]
#
# File "vault.py", line 14, in withdraw_funds
#     self.balance[msg.sender] -= amount
#
# Error: Arithmetic Underflow. Attempted to subtract 900
# from current balance (100).

Run pyvax doctor at any time to verify environment health and RPC connectivity.

Run the Demo

git clone https://github.com/ShahiTechnovation/pyvax-rebrand
cd pyvax-rebrand
pipx install -e .
bash demo.sh

The demo scaffolds a project, compiles with optimizer level 3, runs pyvax doctor, and validates build artifacts — no wallet or live deployment required.

Project Structure

pyvax-rebrand/
├── avax_cli/
│   ├── transpiler.py      # Python AST → EVM bytecode (core compiler)
│   ├── cli.py             # Typer CLI — all commands
│   ├── compiler.py        # Multi-contract compilation pipeline
│   ├── deployer.py        # web3.py + EIP-1559 gas estimation
│   ├── wallet.py          # Encrypted HD keystore management
│   ├── interactor.py      # Contract read/write interaction
│   └── py_contracts.py    # Contract base class + decorators
├── app/                   # Next.js 14 web platform
├── playground/            # Browser compilation API (Railway)
├── content/docs/          # MDX documentation (20 articles)
├── tests/
│   ├── test_v3_optimizations.py   # Optimizer + gas validation
│   ├── test_pipeline.py           # End-to-end compile pipeline
│   ├── test_quick.py              # Smoke tests
│   └── test_sload_diag.py         # SLOAD cache diagnostics
├── test_AgentVault/       # AgentVault contract + deploy scripts
├── test_ERC20/            # ERC-20 contract + deploy scripts
├── test_Voting/           # Voting contract + deploy scripts
├── test_Counter/          # Counter contract + deploy scripts
├── test_SimpleStorage/    # SimpleStorage contract + deploy scripts
├── DemoToken/             # Demo ERC-20 deployment
├── demo.sh                # End-to-end demo script
├── setup.py               # pip install pyvax
└── pyproject.toml

Playground

No installation needed. Write, compile, and deploy Python contracts in the browser:

pyvax.xyz/playground →

• Live Python editor with full decorator support
• Real-time ABI + EVM bytecode inspector
• In-browser pyvax compile terminal
• One-click Fuji testnet deployment via MetaMask

Documentation

Full docs at pyvax.xyz/docs

Built With

• Avalanche C-Chain — primary deployment target
• Chainlink VRF — verifiable randomness
• web3.py — EVM interaction layer
• eth-account — HD wallet + transaction signing
• Typer + Rich — CLI framework
• PyCryptodome — keccak256 hashing
• Next.js 14 — web platform

Built with ❤️ for the Avalanche & Python ecosystems.

Submitted to Avalanche Build Games 2026