otterspace-contracts

Otterspace’s EIP-4973-compliant non-transferable badge protocol helps DAOs create better incentive systems, automate permissions and enable non-financialized governance ✨ 🦦 🚀

Project setup

• Install Foundry
• Requires Node v16 and Solidity 0.8.16

git clone [email protected]:otterspace-xyz/otterspace-contracts.git
git submodule update --init
yarn
forge install
forge build
forge test
npx hardhat typechain
npx hardhat test

Supported networks and contract addresses

Checkout our documentation site at docs.otterspace.xyz

Use ABIs with JavaScript

We're publishing this repository at @otterspace-xyz/contracts

npm i @otterspace-xyz/contracts

With node >= 16, contract ABIs can be imported into JavaScript applications as npm dependencies as follows:

Badges ABI

import Badges from '@otterspace-xyz/contracts/out/Badges.sol/Badges.json' assert { type: 'json' }

Raft ABI

import Raft from '@otterspace-xyz/contracts/out/Raft.sol/Raft.json' assert { type: 'json' }

SpecDataHolder ABI

import SpecDataHolder from '@otterspace-xyz/contracts/out/SpecDataHolder.sol/SpecDataHolder.json' assert { type: 'json' }

We're exporting specific .sol files using the "files" property in package.json. Please familiarize yourself with the .sol files we're exporting by looking into package.json.

Tech Stack

We use Foundry and Hardhat together. With this setup we get:

• Unit tests written in Solidity (Forge)
• Integration tests written in JavaScript (Mocha)

Foundry

Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.

Foundry consists of:

• Forge: Ethereum testing framework (like Truffle, Hardhat and DappTools).
• Cast: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
• Anvil: local Ethereum node, akin to Ganache, Hardhat Network.

Need help getting started with Foundry? Read the 📖 Foundry Book!

Hardhat

Hardhat is an Ethereum development environment for professionals. It facilitates performing frequent tasks, such as running tests, automatically checking code for mistakes or interacting with a smart contract.

On Hardhat's website you will find:

• Guides to get started
• Hardhat Network
• Plugin list

Deploying contracts for the first time

• create a .env file matching the variables seen in .env.example
• run ./scripts/deployProxy.ts .env
• Hardhat will deploy the SpecDataHolder, Raft, and Badges contracts, then deploy a proxy for each one.
• Once deployed, follow the logged instructions in your terminal to verify the contracts.
• it will tell you: npx hardhat verify --network ${networkName} ${contractAddress}

Testing upgradability

• Our contracts use the OpenZeppelin UUPS proxy pattern for upgrades.
• To test your working changes against the latest release:
  1. make sure you're on the latest from the dev branch
  2. run forge build to make sure you've generated the latest ABIs
  3. copy the contents of:
  • artifacts/src/Badges.sol/Badges.json into src/test/abis/latest
  • artifacts/src/Raft.sol/Raft.json into src/test/abis/latest
  • artifacts/src/SpecDataHolder.sol/SpecDataHolder.json into src/test/abis/latest
• 4. make some changes to the contracts
• 5. run npx hardhat testUpgrade
• 6. As long as you don't see errors, your new contract is upgrade safe!

Running upgrades (overview)

• Once you've confirmed that the contracts are upgrade safe you'll
  • deploy an implementation (not proxy) of each changed contract
  • point the proxy at the new implementation

Running upgrades (steps)

• make sure your .env.implementation file has the correct values
• run ./scripts deploy_and_verify_implementation.sh .env.implementation ${contractName} ${networkName}
• to deploy Badges on Optimism it would be
  • ./scripts deploy_and_verify_implementation.sh .env.implementation Badges optimism
• watch the console for confirmation of deployment and verification, copy the implementation's address
• go into Defender and propose and execute the upgrade

How Otterspace runs upgrades

• Our process of running upgrades is managed by github actions, found in the .github/workflows directory.

Publishing attestations

npx hardhat run publishAttestations.js --network optimisticEthereum

more details about in ./scripts/update_scores.py

Foundry setup for VS Code Users

Add a .vscode file under the root

{
  "solidity.packageDefaultDependenciesContractsDirectory": "src",
  "solidity.packageDefaultDependenciesDirectory": "lib",
  "solidity.compileUsingRemoteVersion": "v0.8.16"
}

Versioning & publishing to NPM

• First update the version in package.json
• Add the version entry in changelog.md
• Commit all your changes
• Run git tag v5.x.x to the version you added in package.json
• Run git push origin v5.x.x
• Run npm publish

Note - you need to have admin rights to otterspace registry in npm

Changelog

See changelog.md file.

Supporting new chains

• Adding support for new chains

License

See LICENSE file.