Aragon Protocol

Appearance

Plugin Template (Foundry) ​

A GitHub template repository that scaffolds a new OSx plugin, the intended starting point when you set out to write your own plugin. Create a repo from it to start with a tested plugin project ready for publishing and deployment, without assembling the OSx boilerplate by hand.

Why start from it ​

Writing a plugin requires more than one contract. You need the right plugin base type for your upgradeability choice, a PluginSetup that grants exactly the right permissions on install and revokes them on uninstall, tests that exercise it against a real DAO, and scripts to publish and deploy it. Errors in any of these can cause plugin bugs. The template supplies working versions of each, so you can concentrate on your plugin's logic.

What it gives you ​

  • Contract starters for the plugin base types (the non-upgradeable, cloneable, and UUPS-upgradeable variants), so you can start from the base that matches your requirements.
  • PluginSetup scaffolding wired to those contracts, the prepare-install / prepare-uninstall logic that the PluginSetupProcessor drives.
  • Deploy scripts and factories, including the one-shot factory pattern for standing up a custom DAO with your plugin, and scripts for publishing to a PluginRepo.
  • A testing environment for unit tests, fork tests against a live network, and use-case scenarios.
  • Multi-explorer verification and a self-documenting just task runner (via just-foundry) covering the whole build/test/deploy workflow. Run just init to set up the project.

Which starter path to take ​

The template ships examples of every variant so each pattern is there to learn from; a real plugin keeps one of each and deletes the rest. Two choices define your path:

1. The plugin base type (see choosing a plugin base). The repo includes all three, MyUpgradeablePlugin (UUPS), MyCloneablePlugin (clone), and MyStaticPlugin (non-upgradeable). Keep the one you want, point MyPluginSetup's constructor() and prepareInstallation() at it, and drop the others. If it's upgradeable, inherit PluginUpgradeableSetup instead of PluginSetup so you can add prepareUpdate.

2. The deployment flow (set DEPLOY_SCRIPT in the justfile; it defaults to DeploySimple). The template's real output is a published plugin, but it ships three starter scripts:

  • Publish the plugin to a PluginRepo (DeploySimple), the main path, what makes your plugin installable by any DAO.
  • Deploy a DAO with your plugin(s) installed (DeployDaoWithPlugins, trusted) or via a one-shot factory (DeployViaFactory, trustless), included so you can stand up a DAO to exercise your plugin: a demo, an end-to-end test, or a simple one-off.

If your goal is launching a DAO rather than building a plugin, use the DAO Launchpad. It assembles a custom DAO from different components, including plugins published with this template. As a rule of thumb, build/publish a plugin → this template; launch a DAO → the Launchpad.

For tests, two builders stand up a DAO with your plugin installed: a SimpleBuilder (local) and a ForkBuilder (against a real deployed protocol, using the configured factory addresses).

Where it sits ​

The template is the plugin author's starting point. What you build here becomes a versioned entry in a PluginRepo; from there any DAO installs it through the PSP. The framework manages this plugin lifecycle.

Keep in mind ​

  • It's a scaffold, replace the sample contracts. The starters exist to be swapped for your plugin; keep the setup/test/deploy structure, change the logic.
  • Choose the base type deliberately. Your upgradeability and gas trade-offs are set by which plugin base type you start from; the template offers all of them for that reason.
  • Template vs DAO Launchpad. Building a (core or custom) plugin starts here; use the Launchpad for launching a DAO. Although the template includes DAO-deploy scripts, their purpose is to exercise your plugin.

See also ​