omahs/sound-protocol

Sound Protocol

Sound Protocol is a generalized platform for flexible and efficient creation of NFT drops.

Table of Contents

• Sound Protocol
  • Table of Contents
  • Deployments
  • Specification
  • Architecture
  • Diagram
  • Contracts
  • Documentation
  • Usage
    • Prerequisites
    • Setup
    • Testing
    • Deploying
  • Bug Bounty
  • License

Deployments

Permissionless zero-fee deployments on Goerli testnet and Mainnet:

Contract	Address
GoldenEggMetadata	0x3ca50e8da8c3d359fc934aea0161f5346ccb62a1
FixedPriceSignatureMinter	0xc8ae7e42e834bc11c906d01726e55571a0620158
MerkleDropMinter	0xda4b6fbb85918700e5ee91f6ce3cc2148af02912
RangeEditionMinter	0x4552f8b70a72a8ea1084bf7b7ba50f10f2f9daa7
EditionMaxMinter	0x5e5d50ea70c9a1b6ed64506f121b094156b8fd20
SoundCreatorV1	0xaef3e8c8723d9c31863be8de54df2668ef7c4b89
SoundEditionV1	0x8cfbfae570d673864cd61e1e4543eb7874ca35c2
SoundEditionV1_1	0xE5fEB62FB34aDbA661B7c8256887a8B9a21C2278

Specification

See spec for current protocol specification. For details on how to build and run a custom minter instance, see section "Adding a custom minter module" section in spec. Documentation coming soon.

Architecture

The Sound Protocol comprises of several components:

• SoundEdition

  The NFT contract.

  An ERC721A contract deployed via the minimal proxy clone pattern.

  The mint function allows authorized minter contracts or administrators to batch mint NFTs
  (authorization is granted via the MINTER_ROLE or ADMIN_ROLE).

• SoundCreator

  A factory that allows for a single transaction setup that:

  1. Deploys and initializes SoundEdition.
  2. Authorize one or more MinterContracts on SoundEdition.
  3. Configure one or more MinterContracts to mint on SoundEdition.

• MinterContract

  A contract to call the mint function on SoundEdition.
  This contract can implement any kind of customized sales logic.
  One or more MinterContracts can be used on the SoundEdition simultaneously.

• fundingRecipient

  Can be a contract such as a 0xSplits wallet, or an Externally Owned Account (EOA).

• MetadataContract

  A contract which is called by the SoundEdition in the tokenURI function for customizable metadata logic.
  Optional.

Diagram

flowchart LR
    SoundCreatorV1 --> initialize

    subgraph SoundEditionV1
    initialize
    mint
    withdrawETH
    withdrawERC20
    tokenURI
    end

    tokenURI -.-> MetadataContract
    A[Minter A] --> mint
    B[Minter B] --> mint
    C[Minter C] --> mint
    withdrawETH --> fundingRecipient
    withdrawERC20 --> fundingRecipient

Contracts

The smart contracts are stored under the contracts directory.

Files marked with an asterik (*) are specific to sound.xyz,
but you can refer to them if you are building contracts to interact with them on-chain,
or building your own customized versions.

contracts/
├── core
│   ├── SoundCreatorV1.sol ─ "Factory"
│   ├── SoundEditionV1.sol ─ "NFT implementation"
│   ├── SoundFeeRegistry.sol * ─ "Platform fee registry"
│   ├── interfaces
│   │   ├── IMetadataModule.sol ─ "Metadata module interface"
│   │   ├── IMinterModule.sol ─ "Generalized minter interface"
│   │   ├── ISoundCreatorV1.sol ─ "Factory interface"
│   │   ├── ISoundEditionV1.sol ─ "NFT implementation interface"
│   │   └── ISoundFeeRegistry.sol * ─ "Platform fee registry interface"
│   └── utils
│       └── ArweaveURILib.sol * ─ "For efficient storage of Arweave URIs"
└── modules
    ├── BaseMinter.sol * ─ "Shared minting logic"
    ├── EditionMaxMinter.sol * ─ "Minimalistic minter"
    ├── FixedPriceSignatureMinter.sol * ─ "For permissioned mints via ECDSA signatures"
    ├── MerkleDropMinter.sol * ─ "For permissioned mints via Merkle proofs"
    ├── RangeEditionMinter.sol * ─ "Cuts off mints after a set time if a quota is hit"
    ├── GoldenEggMetadata.sol * ─ "For the on-chain golden egg metadata"
    └── interfaces
        ├── IEditionMaxMinter.sol *
        ├── IFixedPriceSignatureMinter.sol *
        ├── IMerkleDropMinter.sol *
        ├── IRangeEditionMinter.sol *
        └── IGoldenEggMetadata.sol *

Documentation

A comprehensive documentation is currently in the works.

Please refer to the Natspec comments and spec for now for further details.

Usage

Prerequisites

• git
• nodeJS
• node version manager
• pnpm - You need to have pnpm installed globally, you can run npm i -g pnpm to install it.
• brew
• foundry - You can run sh ./setup.sh to install Foundry and its dependencies.

Setup

• Clone the repository

  git clone [email protected]:soundxyz/sound-protocol.git
  cd sound-protocol

• Setup node version Either install the version specified in nvmrc or use nvm to set it up:

  nvm use
  

• Install packages

  pnpm install
  

• Build contracts

  pnpm build
  

• Run tests

  pnpm test
  

• Print gas reports from tests

  pnpm test:gas
  

Testing

(v == logs verbosity)

forge test -vvv

Code coverage:

We use codecov for analysing the code coverage reports generated by forge coverage. To view code coverage locally, you'll need to install lcov (mac: brew install lcov) and run:

pnpm test:coverage

This will produce the coverage report in /coverage folder. Note that forge coverage is still in active development so it often claims if/else branches are uncovered even when there are tests executed on them.

Deploying

Create a .env in the root with:

GOERLI_RPC_URL=
MAINNET_RPC_URL=
PRIVATE_KEY=
ETHERSCAN_KEY=
OWNER=<address that will own the ownable contracts>

Then run:

pnpm deploy:goerli

Bug Bounty

Up to 10 ETH for any critical bugs that could result in loss of funds. Rewards will be given for smaller bugs or ideas.

License

MIT Copyright 2022 Sound.xyz