Protocol Design

Overview

Guide users through designing and building a smart contract protocol from scratch using Ape Framework. This skill covers the full protocol lifecycle:

• Understanding design requirements
• How to setup a new protocol project
• Developing smart contracts for the protocol
• Testing guidance and strategy
• Scripting deployment and management actions
• Setting up protocol automation and monitoring, with Silverback
• Distribution via Python SDK, for others to work with your protocol

Prerequisites

Before using this skill, verify the user has:

• uv installed (https://docs.astral.sh/uv)
• Basic understanding of smart contract concepts
• A clear idea of what the protocol should do
  • Use the development/spec-interview skill if the protocol design is not fully specified

Workflow

Step 1: Fetch Ape Documentation

CRITICAL: Always fetch current Ape documentation before proceeding:

• Quickstart: https://docs.apeworx.io/ape/stable/userguides/quickstart.html
• Project structure: https://docs.apeworx.io/ape/stable/userguides/projects.html
• Testing: https://docs.apeworx.io/ape/stable/userguides/testing.html
• Scripts: https://docs.apeworx.io/ape/stable/userguides/scripts.html
• Plugins: https://docs.apeworx.io/ape/stable/userguides/plugins.html

DO NOT rely on general knowledge about Ape - always fetch the current documentation first to ensure accuracy.

Step 2: Understand the Protocol

Ask focused questions to understand what the user wants to build:

• What does the protocol do at a high level? What problem does it solve?
• Who are the actors involved in this process, and how should they be constrained?
• Are there important digital assets or state that the protocol should manage?
• What should the core smart contracts be and how do they interact with each other?
• Are there other protocols that can be leveraged to reduce the design of new code?
• What events should contracts emit so that off-chain systems can monitor and react to on-chain actions? (important for monitoring and automation use cases)
• Which blockchain network(s) should the protocol be deployed on?
• Are there privileged roles or access controls needed to manage the protocol?
• Which smart contract language do you prefer to use? (Suggest Vyper if none preferred by the user, however Solidity is easily supported as well)

CRITICAL: Have a thorough understanding of the protocol design before writing any code. Use SPECIFICATION.md (generated by the spec-interview skill) to manage the high-level design requirements.

Step 3: Set Up the Project

Initialize the project using Ape's standard structure:

[protocol-name]/
├── pyproject.toml          # Project config with Ape and compiler plugin dependencies
├── README.md               # Protocol overview, setup instructions, usage guide
├── SPECIFICATION.md        # High-level Design Requirement specification
├── contracts/              # Smart contract source files
│   ├── Contract1.vy        # Use .vy for Vyper, .sol for Solidity
│   ├── ...                 # Other contracts
│   └── interfaces/         # Interface definitions (if needed)
│       └── IContract1.vyi
├── tests/
│   ├── conftest.py         # Shared fixtures (deployed contracts, funded accounts, etc.)
│   ├── functional/         # Unit tests for each contract in isolation
│   │   ├── test_contract1.py
│   │   └── test_contract2.py
│   └── integration/        # System-level tests of contracts working together
│       └── test_system.py
└── scripts/
    ├── deploy.py           # Deployment script (run via `ape run deploy`)
    └── ...                 # Any additional scripts needed for custom protocol actions

Key Files

pyproject.toml

[project]
name = "[protocol-name]"
version = "0.1.0"
dependencies = []

[tool.ape.dependencies]
# NOTE: Add any package dependencies here, e.g.:
# openzeppelin = {github = "OpenZeppelin/openzeppelin-contracts", version = "5.0.0"}

[dependency-groups]
test = [
    "eth-ape>=0.8,<0.9",
    "ape-vyper",  # Or ape-solidity, depending on language choice
    "pytest>=9.0,<10",
]
dev = [
    {include-group = "test"},
]

Important Notes:

• The compiler plugin (ape-vyper or ape-solidity) handles installing the compiler itself, so the user does not need to install Vyper or Solidity separately.
• Add other Ape plugins as needed (e.g. ape-foundry for a local fork provider).
• If the protocol depends on external contracts (e.g. OpenZeppelin), declare them in [tool.ape.dependencies] so Ape can fetch them.
• Install any required dependencies via ape pm install

Step 4: Develop the Smart Contracts

Guide the user through implementing their contracts:

• Start with the core contract that holds the protocol's primary state
• Build outward to supporting contracts that interact with it
• Define clear interfaces between contracts
• Emit events for significant state changes (these are important for monitoring and indexing)
• Keep contracts focused and modular

Step 5: Write Tests

Testing is organized into two categories:

Functional tests (tests/functional/) - Unit tests for each contract in isolation:

• Test each public function with expected inputs
• Test edge cases and failure modes (should revert with expected errors)
• Test event emissions
• Test access control (unauthorized callers should be rejected)

Integration tests (tests/integration/) - System-level tests of the protocol:

• Test multi-contract interactions (e.g. deploying the full system and running user scenarios)
• Test with an SDK or CLI scripts if they are part of the project
• Consider fork testing against mainnet state for protocols that interact with existing DeFi

Run tests with:

$ ape test

Run a specific test category:

$ ape test tests/functional/
$ ape test tests/integration/

Step 6: Write Deployment Scripts

Create a deployment script in scripts/deploy.py that can be run with ape run deploy.

A basic deployment script structure:

import click
from ape import project
from ape.cli import ConnectedProviderCommand, account_option


@click.command(cls=ConnectedProviderCommand)
@account_option("--deployer")
# NOTE: Deployer account is configured via: --deployer <alias>
def cli(deployer):
    """Deploys all the contracts in the system"""

    # Deploy contracts in dependency order
    contract1 = deployer.deploy(project.Contract1)
    contract2 = deployer.deploy(project.Contract2, contract1)

    # Perform any post-deployment configuration
    contract1.initialize(contract2, sender=deployer)

For complex, multi-contract systems, consider upgrading this script into a deployment group so that each contract can be deployed separately if needed:

import click
from ape import project
from ape.cli import ConnectedProviderCommand, account_option


@click.group()
def cli():
    """Deploy contracts in the system"""


@cli.command(cls=ConnectedProviderCommand)
@account_option("--deployer")
def contract1(deployer):
    """Deploys Contract1"""

    deployer.deploy(project.Contract1)


@cli.command(cls=ConnectedProviderCommand)
@account_option("--deployer")
def contract2(deployer):
    """Deploys Contract2"""

    if not project.Contract1.deployments:
        raise click.UsageError("Deploy contract1 first!")

    # Since Contract2 depends on Contract1, this allows us to define a stricter deployment process
    deployer.deploy(project.Contract2, project.Contract1.deployments[-1])

If there are further post-deployment actions or configurations that your protocol needs to do, consider adding separate scripts to manage those separately from deployment, as they may need to be performed outside of deploying the original system. Use click's documentation together with Ape's built-in ape.cli module to create deployment and management scripts that help the user deploy and manage all the aspects of their system.

For multi-chain deployments, consider upgrading this script to use createx-py for deterministic deployments that give contracts the same address across all chains. This can be introduced as a refinement after the basic deployment is working.

Step 7: Automation with Silverback (Optional)

If the protocol has specialized roles that need to be performed to function correctly, or otherwise would benefit from continuous monitoring or automated reactions to on-chain activity, reference the silverback/writing-bots skill to set up a Silverback bot.

Common scenarios where monitoring is valuable:

• Anomaly detection - Monitor protocol events and balances for unexpected behavior and alert the user (e.g. unusually large withdrawals, rapid parameter changes)
• Protocol maintenance roles - Some protocols require active participants to perform specific roles (e.g. liquidations, oracle updates, rebalancing). A Silverback bot can fill these roles during early adoption before generalized MEV bots or other actors pick them up organically.
• Operational alerts - Send notifications (Telegram, Discord, etc.) when important protocol events occur, such as governance actions or threshold breaches
• Automated responses - React to on-chain events by submitting transactions (e.g. auto-compounding, keeper operations)

Load the silverback/writing-bots skill when the user is ready to set up any automated actions with Silverback.

Step 8: SDK Development (Optional)

If the user mentions wanting to ship a Python SDK for this protocol (e.g. in the same monorepo), reference the protocols/writing-sdks skill.

An SDK is useful when:

• You want to make the protocol more accessible to Python developers
• You are building bots or applications that interact with the protocol
• You want to provide a higher-level API over raw contract calls, in order to simplify integration with more complex, protocol-level concerns that may not be useful to expose to developers

Key Principles

• Design before code - Understand the full protocol before writing contracts
• Fetch documentation - Always get current Ape docs before proceeding
• Test thoroughly - Both unit and integration tests before deployment
• Deploy incrementally - Start with testnet, verify behavior, then move to mainnet
• Monitor after deployment - Consider Silverback for ongoing protocol health

Common Pitfalls

• Don't skip the design phase - rushing to code leads to costly rewrites
• Don't assume compiler versions - let the Ape compiler plugin manage installation
• Don't deploy without thorough testing on a local network or testnet first
• Don't forget to emit events - they are critical for monitoring, indexing, and debugging complex protocols on-chain
• Don't hardcode addresses - use configuration or deployment scripts to manage addresses
• Don't write a complex deployment script upfront - start simple and refine