MultiAccount Deployment Guide

This guide has been updated to reflect the Etherscan V1 -> V2 upgrade.

This document outlines the required steps and responsibilities for deploying the MultiAccount contract.

1. Responsibility and Security The full responsibility for the deployment and ongoing management of the MultiAccount contract lies with the deploying entity. To ensure the integrity and security of the contract, please take the following actions:

   • Conduct thorough audits of the contract code.

   • Implement robust security checks.

   • Ensure regular maintenance and monitoring of the deployed contract.

2. Deployment of Latest Version It is essential to deploy the latest version of the MultiAccount contract. The most current version can be found at the following link: MultiAccount Contract

Please note that the MultiAccount contract available in this repository is a sample code. You are free to modify or customize the code to meet your specific requirements. However, be aware that any modifications or changes to the contract may extend the time required for the registration process, as the Symmio team will need to thoroughly review and approve the changes.

1. Transfer of Admin Roles and ProxyAdmin Ownership Upon successful deployment, the following steps must be completed to ensure secure management of the contract:

   • Transfer the admin roles to the appropriate entity.

   • Transfer ownership of the ProxyAdmin to a 3-day timelock contract for added security.

These measures are necessary to safeguard the contract against unauthorized access or modifications.

1. Proposal to Symmio Team After deploying the contract and completing the necessary security measures, a formal proposal must be submitted to the Symmio team. The proposal should request that the deployed MultiAccount contract address be registered in the Symmio Core Contracts. If any modifications have been made to the original sample contract, please note that the registration process may take longer due to the required review of the changes by the Symmio team.

Prerequisites

• Install Node.js and npm.

• Install Hardhat in your project directory: npm install --save-dev hardhat

• Install Typescript and ts-node: npm install --save-dev typescript ts-node

Step 1: Clone the Repo

git clone https://github.com/SYMM-IO/protocol-core
cd protocol-core

Step 2: Prerequisites

Ensure you're working with Node 20 LTS (Hardhat doesn’t support Node 21)

node -v            # should show v20.x
# if not:
nvm install 20
nvm use 20
node -v

Step 3: Create a .env

At the repo root, create a .env. Within the repo you'll find a .env.example. Copy the example over into the .env and populate the fields appropriately.

MANTLE_API_KEY=""
MANTLE2_API_KEY=""
BNB_API_KEY=""
BLAST_API_KEY=""
BASE_API_KEY=""
POLYGON_API_KEY=""
ARBITRUM_API_KEY=""
IOTA_API_KEY=""
MODE_API_KEY=""
BERA_API_KEY=""

PRIVATE_KEY=""
PRIVATE_KEYS_STR=""
ADMIN_PUBLIC_KEY=""
HARDHAT_DOCKER_URL="http://eth-node:8545"

TEST_USER_BALANCE=5000
TEST_USER_MAX_QUOTE=100
HEDGER_WEB_SERVICE="http://127.0.0.1:8090"
TEST_USER_TIMEOUT=120000
LOG_LEVEL=debug
DEPLOY_MULTICALL=false
VALIDATION_PROBABILITY=0.2
DEPLOY_MULTICALL=true

TEST_MODE={static,pre-upgrade,fuzz}

The required variables for deployment are here:

ETHERSCAN_API_KEY=YOUR_ETHERSCAN_V2_KEY
PRIVATE_KEY=0xYOUR_DEPLOYER_PRIVATE_KEY
ADMIN_PUBLIC_KEY=0xYOUR_ADMIN_PUBLIC_KEY

Use ETHERSCAN_API_KEY (single key). V1 per-network keys are now deprecated. Read more about the changes here.

Step 4: Update hardhat.config.ts (Etherscan V2)

Replace your etherscan section in hardhat.config.ts with one key and clean URLs (no ?apikey= anywhere): Example:

etherscan: {
  apiKey: process.env.ETHERSCAN_API_KEY || "", //Just using the V2 API
  customChains: [
    // Keep only chains you actually verify on.
    // IMPORTANT: no "?apikey=..." in apiURL anymore.
    {
      network: "zkEvm",
      chainId: 1101,
      urls: {
        apiURL: "https://api-zkevm.polygonscan.com/api",
        browserURL: "https://zkevm.polygonscan.com",
      },
    },
    {
      network: "opbnb",
      chainId: 204,
      urls: {
        apiURL: "https://api-opbnb.bscscan.com/api",
        browserURL: "https://opbnb.bscscan.com",
      },
    },
    {
      network: "iota",
      chainId: 8822,
      urls: {
        apiURL: "https://explorer.evm.iota.org/api",
        browserURL: "https://explorer.evm.iota.org",
      },
    },
    {
      network: "mode",
      chainId: 34443,
      urls: {
        apiURL: "https://api.routescan.io/v2/network/mainnet/evm/34443/etherscan",
        browserURL: "https://modescan.io",
      },
    },
    {
      network: "blast",
      chainId: 81457,
      urls: {
        apiURL: "https://api.blastscan.io/api",
        browserURL: "https://blastscan.io",
      },
    },
    {
      network: "mantle",
      chainId: 5000,
      urls: {
        apiURL: "https://api.mantlescan.xyz/api",
        browserURL: "https://mantlescan.xyz",
      },
    },
    {
      network: "sonic",
      chainId: 146,
      urls: {
        apiURL: "https://api.sonicscan.org/api",
        browserURL: "https://sonicscan.org",
      },
    },
    {
      network: "bera",
      chainId: 80094,
      urls: {
        apiURL: "https://api.routescan.io/v2/network/mainnet/evm/80094/etherscan",
        browserURL: "https://beratrail.io",
      },
    },
  ],
},

Step 5: Installing Dependencies

Install hardhat via the terminal (if not done already):

npm install --save-dev hardhat

Step 6: Compile the Contracts

npx hardhat compile

Step 7: Deploying a MultiAccount Contract (Polygon)

In this example, we're deploying a MultiAccount contract on Polygon, using the address of the diamond deployed there (--symmio-address). A comprehensive list of all the deployed Diamond addresses can be found here.

npx hardhat deploy:multiAccount --symmio-address 0x976c87Cd3eB2DE462Db249cCA711E4C89154537b --admin 0x3B5aC601c7bB74999AB3135fa43cbDBc6aB74570 --network polygon

This will print to the terminal:

Running deploy:multiAccount
Deploying contracts with the account: 0x3B5aC601c7bB74999AB3135fa43cbDBc6aB74570
0x3B5aC601c7bB74999AB3135fa43cbDBc6aB74570 0x976c87Cd3eB2DE462Db249cCA711E4C89154537b
MultiAccount deployed to {
  proxy: '0x69192790420cd7e97f231BB73B9c9C5d914A2fc8',
  admin: '0xC0788bB9293e53703a4e3921409849FAE006306C',
  implementation: '0x0F0711432E871bc0C581DA0cF71fC82565f3e77b'
}
Could not read existing JSON file: Error: ENOENT: no such file or directory, open 'D:\docsmulti\protocol-core\tasks\data\deployed.json'
Deployed addresses written to JSON file

You can find the deployed addresses in /tasks/data/deployed.json. This file is used for verification in the following step.

[
  {
    "name": "MultiAccountProxy",
    "address": "0x78174a787914Ae4eB8c1EaC87fEa19c547fD474D",
    "constructorArguments": [
      "0x3B5aC601c7bB74999AB3135fa43cbDBc6aB74570",
      "0x976c87Cd3eB2DE462Db249cCA711E4C89154537b",
      "0x60803461016157601f610e2d38819003918201601f191683019291906001600160401b038411838510176101665781606092849260409687528339810103126101615761004b8161017c565b9060206100648461005d83850161017c565b930161017c565b9160009182805282815285832060018060a01b0380961690818552825260ff87852054161561012a575b507febee9ae4283d502e7ed608f7bff6281dc40560c705aa66f8f31324862ed03f5a9081845283815285878520931692838552815260ff8785205416156100f2575b505050501660018060a01b0319600154161760015551610c7c90816101918239f35b8184528381528684209083855252858320600160ff19825416179055600080516020610e0d833981519152339380a4388080806100d0565b8380528382528684208185528252868420805460ff19166001179055339084600080516020610e0d8339815191528180a43861008e565b600080fd5b634e487b7160e01b600052604160045260246000fd5b51906001600160a01b03821682036101615756fe60406080815260048036101561001457600080fd5b600091823560e01c806301569e3a1461062857806301ffc9a7146105d2578063248a9ca3146105a85780632f2ff15d146104ff57806336568abe1461046d57806359f6d3921461043257806362dfbb2e146101665780637278b28f1461013d57806391d14854146100f7578063a217fddf146100d85763d547741f1461009957600080fd5b346100d457806003193601126100d4576100d191356100cc60016100bb610843565b938387528660205286200154610916565b610ab7565b80f35b8280fd5b8382346100f357816003193601126100f35751908152602090f35b5080fd5b5090346100d457816003193601126100d4578160209360ff92610118610843565b903582528186528282206001600160a01b039091168252855220549151911615158152f35b8382346100f357816003193601126100f35760015490516001600160a01b039091168152602090f35b50823461042f57602092836003193601126100f35780359067ffffffffffffffff82116100d457366023830112156100d45781810135906101a6826108b2565b926101b386519485610890565b828452868401926024913683838301011161042b57818792848b93018737860101527febee9ae4283d502e7ed608f7bff6281dc40560c705aa66f8f31324862ed03f5a808652858852868620338752885260ff878720541615610279575050600154925161026c949384938493509083906001600160a01b03165af1923d15610270573d610240816108b2565b9061024d83519283610890565b81528092863d92013e5b808051958695151586528501528301906108f1565b0390f35b60609150610257565b87935086908661028833610b52565b918351906102958261085e565b6042825287820192606036853782511561041957603084538251906001918210156104075790607860218501536041915b81831161039e5750505061037057604861036c9593859361035493610345975197889376020b1b1b2b9b9a1b7b73a3937b61d1030b1b1b7bab73a1604d1b8d86015261031c8d82519283916037890191016108ce565b8401917001034b99036b4b9b9b4b733903937b6329607d1b6037840152518093868401906108ce565b01036028810186520184610890565b5194859462461bcd60e51b86528501528301906108f1565b0390fd5b60648688878188519362461bcd60e51b8552840152820152600080516020610c508339815191526044820152fd5b909192600f811660108110156103f5576f181899199a1a9b1b9c1cb0b131b232b360811b901a6103ce8587610b2b565b53891c9280156103e3576000190191906102c6565b634e487b7160e01b825260118a528882fd5b634e487b7160e01b835260328b528983fd5b634e487b7160e01b8152603289528790fd5b634e487b7160e01b8152603288528690fd5b8680fd5b80fd5b8382346100f357816003193601126100f357602090517febee9ae4283d502e7ed608f7bff6281dc40560c705aa66f8f31324862ed03f5a8152f35b509190346100f357826003193601126100f357610488610843565b90336001600160a01b038316036104a457906100d19135610ab7565b608490602085519162461bcd60e51b8352820152602f60248201527f416363657373436f6e74726f6c3a2063616e206f6e6c792072656e6f756e636560448201526e103937b632b9903337b91039b2b63360891b6064820152fd5b5090346100d457816003193601126100d457359061051b610843565b908284528360205261053260018286200154610916565b82845260208481528185206001600160a01b039093168086529290528084205460ff161561055e578380f35b828452836020528084208285526020528320600160ff1982541617905533917f2f8788117e7eff1d82e926ec794901d17c78024a50270940304540a733656f0d8480a43880808380f35b5090346100d45760203660031901126100d457816020936001923581528085522001549051908152f35b5090346100d45760203660031901126100d457359063ffffffff60e01b82168092036100d45760209250637965db0b60e01b8214918215610617575b50519015158152f35b6301ffc9a760e01b1491503861060e565b50346100d4576020908160031936011261083f576001600160a01b038335818116949085900361083b57858052858452828620338752845260ff8387205416156106b15750907ff78ccdf5924090b2ab6627ac5da4ec5affed73d47c6bc6c8a4620a0d5ed57bc891846001549483519286168352820152a16001600160a01b0319161760015580f35b919050846106be33610b52565b90808351906106cc8261085e565b6042825286820192606036853782511561082857603084538251906001918210156108155790607860218501536041915b8183116107aa5750505061077b5760486107529385936107619361036c975196879376020b1b1b2b9b9a1b7b73a3937b61d1030b1b1b7bab73a1604d1b8c86015261031c8c82519283916037890191016108ce565b01036028810185520183610890565b5193849362461bcd60e51b855284015260248301906108f1565b606485878087519262461bcd60e51b84528301526024820152600080516020610c508339815191526044820152fd5b909192600f81166010811015610802576f181899199a1a9b1b9c1cb0b131b232b360811b901a6107da8587610b2b565b53881c9280156107ef576000190191906106fd565b634e487b7160e01b825260118952602482fd5b634e487b7160e01b835260328a52602483fd5b634e487b7160e01b815260328852602490fd5b634e487b7160e01b815260328752602490fd5b8580fd5b8380fd5b602435906001600160a01b038216820361085957565b600080fd5b6080810190811067ffffffffffffffff82111761087a57604052565b634e487b7160e01b600052604160045260246000fd5b90601f8019910116810190811067ffffffffffffffff82111761087a57604052565b67ffffffffffffffff811161087a57601f01601f191660200190565b60005b8381106108e15750506000910152565b81810151838201526020016108d1565b9060209161090a815180928185528580860191016108ce565b601f01601f1916010190565b600090808252602090828252604092838120338252835260ff84822054161561093f5750505050565b61094833610b52565b918451906109558261085e565b60428252848201926060368537825115610aa35760308453825190600191821015610aa35790607860218501536041915b818311610a3557505050610a0557604861036c9386936109e9936109da985198899376020b1b1b2b9b9a1b7b73a3937b61d1030b1b1b7bab73a1604d1b8a86015261031c815180928c6037890191016108ce565b01036028810187520185610890565b5192839262461bcd60e51b8452600484015260248301906108f1565b60648486519062461bcd60e51b82528060048301526024820152600080516020610c508339815191526044820152fd5b909192600f81166010811015610a8f576f181899199a1a9b1b9c1cb0b131b232b360811b901a610a658587610b2b565b5360041c928015610a7b57600019019190610986565b634e487b7160e01b82526011600452602482fd5b634e487b7160e01b83526032600452602483fd5b634e487b7160e01b81526032600452602490fd5b9060009180835282602052604083209160018060a01b03169182845260205260ff604084205416610ae757505050565b80835282602052604083208284526020526040832060ff1981541690557ff6391f5c32d9c69d2a47ea670b442974b53935d1edc7fd64eb21e047a839171b339380a4565b908151811015610b3c570160200190565b634e487b7160e01b600052603260045260246000fd5b604051906060820182811067ffffffffffffffff82111761087a57604052602a8252602082016040368237825115610b3c57603090538151600190811015610b3c57607860218401536029905b808211610be1575050610baf5790565b606460405162461bcd60e51b81526020600482015260206024820152600080516020610c508339815191526044820152fd5b9091600f81166010811015610c3a576f181899199a1a9b1b9c1cb0b131b232b360811b901a610c108486610b2b565b5360041c918015610c25576000190190610b9f565b60246000634e487b7160e01b81526011600452fd5b60246000634e487b7160e01b81526032600452fdfe537472696e67733a20686578206c656e67746820696e73756666696369656e74a164736f6c6343000812000a2f8788117e7eff1d82e926ec794901d17c78024a50270940304540a733656f0d"
    ]
  },
  {
    "name": "MultiAccountAdmin",
    "address": "0xB3A34B46a9103fB157b5b1Af4655ec703b1578D2",
    "constructorArguments": []
  },
  {
    "name": "MultiAccountImplementation",
    "address": "0x950BaeF761A17Cd0f77d6dB8008ebeBd011FCA4b",
    "constructorArguments": []
  }
]

Step 8: Verifying the MultiAccount contract

Simply run the verification script with the appropriate network flag to verify the contracts.

npx hardhat verify:deployment --network polygon

Troubleshooting

• “Using deprecated V1 endpoint / API key invalid” → ensure you have ETHERSCAN_API_KEY (single key, not a string) and your apiURLs don’t contain ?apikey=..

• Node warning → node -v must be v20.x.

• Compiler mismatch → run npx hardhat clean && npx hardhat compile. (Stick with the repo’s existing Solidity settings.)