On-Chain Adoption Guide

Authored by:

Dickson Wu

SEAL

This guide explains how protocols can register their Safe Harbor adoption on-chain. Registering ensures your adoption is public, verifiable, and enforceable.

Why On-Chain Adoption Matters

On-chain registration:

• Makes your Safe Harbor adoption public and transparent.
• Signals to whitehats that your protocol is officially covered under the agreement.
• Publishes your terms (scope, bounty, contacts) on-chain in a way that's traceable and verifiable, even if updated later.

How On-Chain Adoption Works

The process involves two steps:

1. Create your Agreement contract via the AgreementFactory (containing your scope details)
2. Register the agreement with the Safe Harbor Registry

Three Ways to Deploy and Register

• The address that registers represents your protocol on-chain.
• Most protocols use multisigs or DAOs for the registration step - Be sure to set the owner of the agreement to your multisig or DAO address if you are registering with them.
• The simplest workflow is to use the SEAL Self-Adoption Tool to deploy your agreement and register it with your multisig/DAO.

1. SEAL Self-Adoption Website + Script/Multisig Registration

1. Navigate to the SEAL Self-Adoption Tool.
2. Fill in your scope details (Asset Recovery Address, Assets Under Scope, Bounty Terms, etc.).
   • WARNING: Be sure to set the owner of the agreement to your multisig or DAO address if you're registering with them.
3. Choose one of the following:
   • Generate an Agreement to deploy your Agreement contract via the SEAL tool
   • Export JSON for use in Foundry scripts
4. Deploy your agreement using the generated parameters
5. Register separately using either:
   • Foundry script (see method 3 below)
   • Multisig registration (see method 2 below)

2. Multisig Registration (Gnosis Safe)

If your protocol uses a multisig, you can register on-chain securely after deploying your agreement.

1. First, create your Agreement contract:

   • Use the SEAL Self-Adoption Tool to generate the deployment parameters
   • Deploy via the AgreementFactory using your preferred method
   • WARNING: Be sure to set the owner of the agreement to your multisig address

2. Register with your multisig:

   • Open your Gnosis Safe and go to the Transaction Builder app
   • Enter the Safe Harbor Registry address: 0x326733493E143b8904716E7A64A9f4fb6A185a2c
   • Select the method: adoptSafeHarbor(address agreementAddress) and input your deployed Agreement contract address
   • Add the transaction and simulate it:
     • You should see a SafeHarborAdoption event with your multisig as the adopter
   • Collect signatures and execute

3. Foundry Script / Custom Code

If you prefer deploying and registering via code or need custom integrations, you can use SEAL's Foundry script or write your own.

• Repository: security-alliance/safe-harbor
• Script: registry-contracts/script/AdoptSafeHarbor.s.sol

1. Generate your scope JSON via the SEAL tool or manually prepare it using registry-contracts/examples/agreementDetails.json as a template

2. Paste the JSON into: registry-contracts/agreementDetails.json

3. Run the script:

   • By default, the script will set the deployer as the owner of the agreement
   • You can change this by setting AGREEMENT_OWNER in your .env file to your desired owner address
   • By default, the script will not register the agreement - you can change this by setting ADOPT_TO_REGISTRY to true in your .env file
   • The script can handle both deployment and registration

1. Create your agreement: Call AgreementFactory.create(AgreementDetails memory details, address chainValidator, address owner, bytes32 salt)
2. Register it: Call SafeHarborRegistry.adoptSafeHarbor(address agreementAddress)

V3 Contract Addresses

V3 contracts are deployed via CreateX with deterministic addresses across all supported EVM chains.

Note: These addresses are the same on all supported EVM chains due to CREATE3 deployment.

Note: The V3 contracts have been audited by Cyfrin. The smart contracts are bytecode equivilant to the hash of the audit. The audit can be found here

If you ever need help or have any questions, don't hesitate to reach out! 📬 Contact us at: safe-harbor@securityalliance.org