LogoLogo
These products have been deprecated and are no longer being maintained. For a better experience and support, please check out our new stack Aragon OSx.
Aragon Legacy Documentation
Aragon Legacy Documentation
  • 🔷Aragon
    • Aragon Legacy Documentation
    • Aragon Values, Finances, and Legal
      • Legal and technical infrastructure
      • Financial infrastructure
      • Meet your DAO support network
    • Learn about DAOs
      • What is a DAO?
      • Why do we need DAOs?
      • What is decentralized autonomous governance?
      • What is the AN DAO?
      • TAO Voting
      • Why use Aragon to build a DAO?
  • 🌐Products
    • Prerequisites
    • Quickstart
    • Setting up a Metamask Wallet
      • Getting started with Ethereum
      • Getting started with Goerli Testnet
      • Getting started with Polygon
      • Getting started with Mumbai Testnet
      • Getting started with Harmony
      • Getting started with Harmony testnet
      • Getting started with Metis Andromeda
      • Getting started with Stardust Testnet
      • Getting started with BSC Testnet
      • How to sign a transaction?
      • Import your seed wallet to Metamask
      • Gas Tracker
    • Setting up a Frame Wallet
    • Setting up a Gnosis Safe MultiSig Wallet
    • Aragon Client
      • What is Aragon Client
      • How to create a DAO
        • Templates
        • Using the Company Template
        • Using the Membership Template
        • Use the Reputation template
      • How to create a DAO on Polygon
      • How to create a DAO on Harmony
      • How to navigate your DAO
        • Home
        • The Apps
          • Tokens App
          • Voting App
          • Finance App
          • Agent App
            • How to install the Agent App in your DAO
            • Using Agent with Frame
        • System Setting
          • Permissions Setting
          • App Center
          • Organization Setting
      • After you've started a DAO
        • How to change the Quorum of your DAO
          • Change Quorum using Aragon Console
          • Change Quorum using EVMcrispr
        • How to create a Legal Wrapper for your DAO with Otoco
        • How to Operate your DAO from your Mobile Phone
      • How to Brick your DAO 🧱
    • Aragon Govern
      • What is Aragon Govern?
      • How to create a Govern DAO
      • Navigate into your Govern DAO
        • How to mint and assign DAO tokens to others
        • How to deposit funds
        • Challenging a transaction
      • Reasons for the delay period in the transaction
      • Collateral for scheduling or challenging a transaction. Why?
      • Acting as a guardian for an Aragon Govern dispute
      • Using the Client DAO with the Govern DAO
    • Aragon Voice
      • What is Aragon Voice?
      • Creating a voting proposal
      • Creating a voting proposal using your token
      • Voting on a proposal
    • Aragon Vocdoni
      • What is Aragon Vocdoni
      • Creating a Vodconi organization
      • Accessing your Vocdoni organization
      • Navigating your Vocdoni organization
        • Creating a voting proposal
        • Voting on a proposal (anonymous voting disabled)
        • Voting on a proposal (anonymous voting enabled)
    • Aragon Court
      • What is Aragon Court
      • Court Dashboard
      • Dispute lifecycle
      • Acting as guardian for a dispute
      • Glossary
  • 🛠️Developers
    • Legacy Developer Documentation
    • General Tools
      • The Basics
        • Before starting
        • Quick start
        • Tech Stack
        • App permissions
        • Forwarding
        • Upgradeability
        • Package management
        • Templates
        • Aragon client
        • Human readable transactions
      • Guides
        • How to create your first custom DAO using Aragon CLI!
        • How to use the Agent App
          • Installing Aragon Agent from aragonCLI
          • Setting and Checking permissions
          • Interacting with Aragon Agent
        • How to build your first Aragon App!
        • How to publish an Aragon App to aragonPM
        • How to migrate existing Aragon App to Buidler plugin
        • How to change the Quorum of your DAO
          • Change Quorum using Aragon Console
          • Change Quorum using EVMcrispr
        • Deploying Aragon Client in new Chains
          • Deployments information
            • Harmony testnet
            • BSC Tesnet
            • Harmony
            • Metis stardust
            • Metis Andromeda
        • How to Brick your DAO 🧱
        • How to sign with Web3 providers
          • Setting up a Metamask Wallet
            • Import your seed phrase into Metamask
            • Import your private key into Metamask
            • Sign a transaction with Metamask
          • Setting up a Frame Wallet
            • Sign a Transaction with Frame
        • Troubleshooting
      • aragonOS
        • Introduction
        • Motivations
        • Developing with aragonOS
        • Reference documentation
        • Migrating to aragonOS 4 from aragonOS 3
        • Reference (aragonOS 3)
        • Smart Contract References
          • ACL
            • ACL
            • ACLSyntaxSugar
            • ACLHelpers
            • IACL
            • IACLOracle
          • APM
            • APMNamehash
            • APMRegistry
            • APMInternalAppNames
            • Repo
          • APPS
            • AppProxyBase
            • AppProxyPinned
            • AppProxyUpgradeable
            • AppStorage
            • AragonApp
            • UnsafeAragonApp
          • COMMON
            • Autopetrified
            • ConversionHelpers
            • DelegateProxy
            • DepositableDelegateProxy
            • DepositableStorage
            • EtherTokenConstant
            • IForwarder
            • IForwarderFee
            • IVaultRecoverable
            • Initializable
            • IsContract
            • Petrifiable
            • ReentrancyGuard
            • SafeERC20
            • TimeHelpers
            • Uint256Helpers
            • UnstructuredStorage
            • VaultRecoverable
          • ENS
            • ENSConstants
            • ENSSubdomainRegistrar
          • EVMSCRIPT
            • EVMScriptRegistry
            • EVMScriptRunner
            • IEVMScriptExecutor
            • IEVMScriptRegistry
            • EVMScriptRegistryConstants
            • ScriptHelpers
          • EVMSCRIPT/EXECUTORS
            • BaseEVMScriptExecutor
            • CallsScript
          • FACTORY
            • APMRegistryFactory
            • AppProxyFactory
            • DAOFactory
            • ENSFactory
            • EVMScriptRegistryFactory
          • KERNEL
            • IKernel
            • IKernelEvents
            • Kernel
            • KernelAppIds
            • KernelNamespaceConstants
            • KernelProxy
            • KernelStorage
      • aragonCLI
        • Introduction
        • Main commands
        • DAO commands
        • APM commands
        • IPFS commands
        • Global configuration
      • aragonPM
        • Introduction
        • Architecture
        • Reference documentation
      • aragonAPI
        • Introduction
        • Javascript
          • Quick Start
          • App API
          • React API
          • Wrapper
          • Providers
          • Architecture of apps
          • Background Scripts
      • aragonUI
        • Getting started
        • How to upgrade
        • BASE
          • Spacing
          • Colors
          • Text styles
          • Icons
          • Main
        • ACTIONS
          • Button
          • ContextMenu
        • NAVIGATION
          • Tabs
          • Pagination
          • BackButton
          • Link
          • Header
        • STRUCTURE
          • Bar
          • Box
          • Card
          • Split
          • DataView
          • Table
          • EmptyStateCard
          • IdentityBadge
          • TransactionBadge
          • Tag
          • Accordion
          • Timer
          • TokenAmount
          • EthIdenticon
          • TransactionProgress
        • DATA ENTRY
          • AutoComplete
          • DateRangePicker
          • DropDown
          • Switch
          • Radio
          • CheckBox
          • Slider
          • TextInput
          • SearchInput
          • AddressField
          • RadioGroup
          • RadioList
          • TextCopy
          • Field
        • VISUALIZATION
          • CircleGraph
          • LineChart
          • Distribution
        • FEEDBACK
          • Info
          • ProgressBar
          • LoadingRing
          • Toast
          • SyncIndicator
          • FloatIndicator
        • OVERLAYS
          • Help
          • Popover
          • Modal
          • SidePanel
        • ADVANCES
          • ButtonBase
          • FocusVisible
          • PublicUrl
          • Redraw
          • RedrawFromDate
          • Root
          • RootPortal
          • Viewport
      • aragonDS
        • Guidelines
          • Layout
          • Color
          • Iconography
          • Typography
          • Illustrations
        • Components
          • Overview
      • Aragon Connect
        • Guides
          • Aragon Basics
          • Getting started
          • Usage with React
        • Advanced
          • Custom Subgraph queries
          • Writing an App Subgraph
          • Writing an App Connector
        • Connectors
          • Organizations
          • Tokens app
          • Voting app
          • Finance app
        • API reference
          • connect()
          • App
          • Connectors
          • Organization
          • Permission
          • Repo
          • Role
          • TransactionIntent
          • TransactionPath
          • TransactionRequest
          • Types
          • Errors
      • App Center
        • App Center
        • Preparing Assets
        • Submitting Your App to the App Center
    • Product Tools
      • Aragon Govern
        • README
        • Introduction
          • Concepts and background
            • Govern Core concepts
            • ERC3000
          • Developers
            • Getting started
            • Govern.js API
            • Historical deployments
            • GraphQL API
            • Smart contracts breakdown
        • Deployments
          • Mainnet
          • Rinkeby
        • Packages
          • ERC 3k
          • Govern Console
          • Govern contract utils
          • Types
          • govern-create
          • Govern Server
          • govern-subgraph
          • govern-token
          • govern.js
      • Aragon Vocdoni
    • Aragon Client Glossary
  • THE ANT TOKEN
    • Aragon Network Token
      • About ANT
      • Historical token sale
    • ANTv1
      • Non-standard behaviours and gotchas
      • About the MiniMe token
      • The initial token sale flow
    • ANTv2
      • Upgrade portal
        • Troubleshooting
      • Contract interaction
      • Migrating on-chain liquidity
    • Developers
      • Quick start
      • Integrating ANT
      • Historical deployments
      • Security policy
  • ‼️FAQ
    • Products
      • Aragon Client
        • Where is my DAO?
        • DAO creation taking a long time to confirm
        • DAO is taking a long time to load
        • Failed DAO creation transaction
        • Why do I see a Blue Screen?
        • An unexpected error has occurred
        • App does not appear in Firefox
        • Receiving funds directly to the Agent or Vault address
        • How to Recover Funds accidentally sent to an Aragon App address
        • Depositing EURS in the Finance app
        • Which templates are available on the Ethereum Network?
        • Which templates are available on the Polygon Network?
        • Which templates are available on the Harmony Network?
        • Which templates are available on the Metis Andromeda Network?
        • How to delete a DAO
      • Aragon Govern
        • Which was the wallet address used to create the Aragon Govern DAO?
        • Where are my DAO tokens?
        • How to delete a DAO
        • How can I transfer funds to the Aragon Govern DAO?
      • Aragon Vocdoni
        • Is Vocdoni easy to use?
        • Is Vocdoni anonymous?
        • Is Vocdoni free?
        • Is my data safe with Vocdoni?
        • As an Organization, what can I do with Vocdoni?
      • Aragon Court
        • What is the current duration of the different stages of a dispute?
        • Dispute - Which fees need to be paid to create a dispute?
        • Dispute - Do I need to put collateral to create a dispute?
        • Appeals - How much money is needed to appeal a dispute? And to confirm the appeal? What is it for?
        • Appeals - If I have tokens staked or activated, can I lose them if I appeal a dispute?
        • Appeals - What happens to the collateral put up
        • Voting - Is a majority needed to win a vote?
        • Voting - What happens if there is a tie?
        • Voting - What does "Refuse to vote" mean? What happens if it's the most voted option?
        • Voting - Another guardian tried to collude. Can I punish this guardian?
        • Voting - What's the penalty for leaked votes?
        • Governance - Which parameters of Court can be changed? How?
        • Governance - Do parameter changes affect ongoing disputes?
        • Technical - Where is the Court "hosted"?
        • Technical - Where can I find the source code and technical documentation for Aragon Court?
        • ANJ conversion - What date will the lock-up period end?
        • ANJ conversion - If I have not staked my $ANJ, do I still get the lockup period price?
        • ANJ conversion - Will I get the 0.044 conversion if I convert after September 5th 2021?
        • ANJ conversion - How much will it cost to be a Guardian in Aragon Court with $ANT?
        • I can't see my tokens in the Dashboard
        • I activated my tokens but I can't see my probability of being drafted
    • Miscellaneous
      • Metamask wallet transaction alert
      • Is Aragon open source?
      • Where can I browse through the DAOs created on Aragon?
      • How to migrate from "old" DAI to "new" DAI
      • Security notice for organizations created before Aragon 0.8
      • General troubleshooting tips
    • ANT Token
      • What can I do with ANT?
      • Who holds ANT?
      • Who are the biggest ANT holders?
      • Long-term holding ANT - What benefits?
      • Can I delegate my network votes to somebody else?
      • Can I do flash loans with ANT?
      • Is there an ANT options market?
      • Are you planning to launch new network tokens?
      • My wallet isn't available on the Upgrade Portal
      • How can connect my Ledger to the Upgrade Portal?
      • I accidentally sent my "old" ANT to an exchange
      • ANJ conversion - What is the minimum number of $ANJ I need to participate in the 0.044 conversion?
      • ANJ conversion - What is the conversion rate ANJ to ANT v2?
Powered by GitBook
On this page
  • Breaking interface changes
  • Shiny new things
  • Technical changes worth knowing about

Was this helpful?

  1. Developers
  2. General Tools
  3. aragonOS

Migrating to aragonOS 4 from aragonOS 3

PreviousReference documentationNextReference (aragonOS 3)

Last updated 2 years ago

Was this helpful?

aragonOS 4 was designed to be as familiar as possible to users of aragonOS 3. In some cases, an Aragon app might not even have to be changed when upgrading.

For a more in-depth technical explanation of the changes in aragonOS 4, please see the and . An annotated list of commits between aragonOS 3 and aragonOS 4 is also .

Breaking interface changes

Solidity pragma

All contracts inheriting from AragonApp must now use at least pragma solidity 0.4.24.

Initialization

All AragonApps must now be initialized before they can be used to prevent uninitialized contracts that may be maliciously initialized by someone else. Trying to access auth() or authP() protected functionality in uninitialized apps will now revert.

If your app didn't already require initialization then you'll need to include the following function in your app:

contract App is AragonApp {
    /**
    * @dev Initialize can only be called once. It saves the block number in which it was initialized.
    */
    function initialize() public onlyInit {
        initialized();
    }
}

And use it in a template when installing the app:

contract AppInstallTemplate {
    /**
    * @dev Create a new DAO with App installed
    */
    function newDAO() external {
        // ...

        App app = App(dao.newAppInstance(/* ... */));
        app.initialize();

        // Now app can be used
        // ...
    }
}

Pruned public constants

To optimize the gas costs of deploying base and proxy contracts as well as simplify public interfaces on tools like etherscan, we've pruned most public constants that would be unnecessary on-chain. This is most likely to only affect any existing tests that expect some constants to be exposed publicly in your contract and can be fixed by either creating mocks or duplicating the constants in the tests.

Kernel's newAppInstance overload replaced

An argument was added to the longer overloads of newAppInstance() and newPinnedAppInstance() to include an initialization payload so the new proxy instance could be created and initialized in one atomic call. The new arguments list for the longer overloads is (byte32 appId, address appBase, bytes initializePayload, bool setDefault).

AragonApp.getExecutor(bytes) renamed

AragonApp.getExecutor(bytes) has been renamed getEVMScriptExecutor(bytes) and has getEVMScriptRegistry() exposed alongside it.

Proxy-less AragonApps

By default, all AragonApps are petrified on deployment and can only be used behind a proxy.

Stand-alone usage of AragonApps

AragonApps that use any functionality requiring a Kernel (e.g. auth(), EVMScripts, or the recovery mechanism) now require the app instance to be connected to a Kernel. Frankly, if you're not using any of this functionality, you probably shouldn't be inheriting from AragonApp.

The old behaviour used to be that functionality protected by the auth() or authP() modifiers could still be invoked if the app instance wasn't connected to a Kernel. This was unexpected and confusing behaviour, possibly leading to dangerous situations, and was removed.

EVMScripts require callers to be initialized

Using AragonApp.runScript(bytes, bytes, address[]) requires an application to be initialized, and each EVMScript executor contract now also checks if its caller has been initialized to prevent malicious misuse from unintended users.

DelegateScript and DeployDelegateScript executors removed

Both DelegateScript and DeployDelegateScript were found to be insecure and have been removed. Although they were still protected by the ACL, the potential for damage was too high due to the fact that they delegatecalled into a user-submitted address.

Token contracts removed

aragon-apps

Shiny new things

ETH and token recoverability

All AragonApps now have built-in ETH and token recoverability in case they accidentally receive value. A transferToVault(address) interface is exposed externally to allow someone to send the tokens held by an app instance to the default vault set in the Kernel.

An allowRecoverability(address) hook is exposed to allow overloading in AragonApp subclasses to control the recoverability behaviour. For example, if an application is meant to hold tokens or ETH, it should turn off the recoverability behaviour for any accepted tokens so they can't be maliciously transferred to another app, even if it is the default vault.

Depositable proxies

By default, it is impossible to send ETH to an app proxy instance (assuming it is one of AppProxyUpgradeable or AppProxyPinned) through a gas-limited .send() or .transfer(). This only applies to proxy instances because you can always declare your own payable fallback in AragonApp subclasses.

If your application would like its proxies to be able to directly receive ETH through .send() or .transfer(), however, you can use AragonApp.setDepositable(true) at some point to enable this functionality.

Good example use cases of this are in applications that need to hold value like a vault or fundraising contract. A vault would always want to accept direct transfers so it calls setDepositable(true) upon initialization. A fundraising application, however, would likely only want to enable it for the duration of the fundraising period, so it only calls setDepositable(true) as the period starts and calls setDepositable(false) when the period ends.

auth provides isInitialized check

The auth() and authP() modifiers now also check for isInitialized() so you don't have to use both modifiers anymore.

New utilities

Technical changes worth knowing about

Unstructured storage

Kernel storage of apps

The Kernel's storage of apps and their namespacing was revamped to use a mapping of a mapping approach rather than a single mapping whose key was derived from a hash of the namespace and app name.

This is not only cheaper but also makes inspection and debugging much easier as the storage location for a particular app requires less steps to derive.

Preferring mappings to arrays for storing structs

KernelConstants has also been split into and , although it is unlikely your app was directly inheriting from KernelConstants.

This was chosen as a sane default as it is unlikely you'd want to directly deploy, install, and use a base contract instance of an app rather than a proxy instance, but it is also possible to turn this off by inheriting from instead.

The and implementations were removed. You should import these contracts into your own project if you would like to continue to use them.

If you'd like to see what this looks like in practice, you can visit .

All the apps in were upgraded to aragonOS 4. Most have not changed much with very few external interface differences. If you were using old versions of them such as in an organization template, however, then you may have to adjust to small differences in their APIs.

The most notable change is with the which was massively simplified and made much easier to secure than the previous implementation. If you had trouble integrating with the previous Vault, this one should be much simpler to use and understand.

For more information see the .

It is recommended to use the new and utilities to safely get values for time variables (e.g. now) and convert between uint units. These also provide a standard interface that allow you to easily create mocks for changing the time returned during testing.

is also recommended to use as the "address" for ETH when an application can handle both tokens and ETH.

App proxies ( and ) are now implemented through .

This means contracts inheriting from AragonApp now start their storage directly from rather than an arbitrary value (in aragonOS 3 it was slot 100), making it much easier to inspect, debug, and swap out proxy implementations. This also makes it much easier for aragonOS to add more functionality in the future without requiring data migrations.

As pointed out at , mappings of structs are much easier to upgrade at later dates than arrays of structs because the data isn't packed tightly. All aragonOS internal and official aragon apps now use this pattern of emulating arrays through mappings.

🛠️
annoucement blog post
reference documentation
available
KernelAppIds
KernelNamespaceConstants
UnsafeAragonApp
Minime token
Standard token
aragon-apps/shared/minime
aragon-apps
Vault
raw list of changes
TimeHelpers
Uint256Helpers
EtherTokenConstant
AppProxyUpgradeable
AppProxyPinned
unstructured storage
storage slot 0
Devcon 3