A collection of smart contracts used by Art Blocks for our flagship product, as well as Artblocks Engine products.
This repository is actively used and maintained by the Art Blocks team. We welcome contributions from the community. Please see our Contributing section more information.
yarn
Create a .env file by duplicating .env.example and populating all variables.
yarn compile
yarn generate:typechain
yarn test
yarn coverage
yarn docgen
(docs for main are served at https://artblocks.github.io/artblocks-contracts/#/)
yarn format
We welcome contributions from the community!
Please read through our Style Guidelines, Solidity Gotchas, and Testing Philosophy sections before contributing.
In addition to meeting our style guidelines, all code must pass all tests and be formatted with prettier before being merged into the main branch. To run the tests, run yarn test. To format the code, run yarn format.
Documentation for contracts is deployed via GitHub pages at: https://artblocks.github.io/artblocks-contracts/
Documentation for contracts may also be generated via yarn docgen. Most Art Blocks contracts use NatSpec comments to automatically enrich generated documentation. Some contracts use dynamic expressions to improve user experience.
For a high-level overview of the Art Blocks V3 contract architecture, refer to the simplified entity relationship diagram below.
erDiagram
ADMIN_ACL ||--o{ CORE_V3_V3_FLEX : manages
ADMIN_ACL ||--o{ MINTERFILTER : manages
CORE_V3_V3_FLEX ||--|| MINTERFILTER : uses
CORE_V3_V3_FLEX }o--|| BYTECODESTORAGEREADER : uses
MINTERFILTER ||--o{ MINTER_1 : uses
MINTERFILTER ||--o{ MINTER_2 : uses
MINTERFILTER ||--o{ MINTER_N : uses
MINTER_1 ||--|| I_FILTERED_MINTER : implements
MINTER_2 ||--|| I_FILTERED_MINTER : implements
MINTER_N ||--|| I_FILTERED_MINTER : implements
RANDOMIZER ||--|| CORE_V3_V3_FLEX : provides_random
ENGINE_REGISTRY ||--o{ CORE_V3_V3_FLEX : notifies
For a more detailed overview of this architecture, please see the V3 Contract Architecture page.
IMPORTANT - many scripts rely on typechain-generated factories, so ensure you have run
yarn generate:typechainbefore running any deployment scripts.
We have two types of deployment scripts: Generic and Specific.
Generic deployment scripts are located in the ./scripts directory. These scripts are used to deploy contracts that are not specific to a particular deployment. Generic deployment scripts are used to deploy contracts that are used by multiple partners or core contracts, such as the Art Blocks Engine contracts, or minters. Generic scripts take an input json file, located in the /deployents/ directory, and execute the deployment as defined in the input file. In general, there are scripts prepared to run generic deployments for all networks and environments. For example, the following can be used to deploy the Art Blocks Engine contracts to the goerli test network (note that an input configuration is also required for all generic deployments.):
yarn deploy:dev:v3-engineSpecific deployments are used less frequently, and are located in the /scripts directory as well. These scripts are used to deploy contracts that are specific to a particular deployment. They are not easily reusable, and are generally only used once. An example to run a specific deployment is:
yarn hardhat run --network <your-network> scripts/deploy.tswhere <your network> is any network configured in hardhat.config.js.
For additional deployment details, see hardhat docs: https://hardhat.org/guides/deploying.html
This is the Smart contract that controls the artwork created by the artist. No financial transactions occur on this Smart contract.
Core contracts use the versioning schema below:
| Description | Version | Project Range | Mainnet Address |
|---|---|---|---|
| AB Core V0 | V0 | 0-2 | 0x059EDD72Cd353dF5106D2B9cC5ab83a52287aC3a |
| AB Core V1 | V1 | 3-373 | 0xa7d8d9ef8D8Ce8992Df33D8b8CF4Aebabd5bD270 |
| Engine Cores (V2) | V2_PBAB | All PBAB | Various - see deployments/engine/ directory DEPLOYMENTS.md files |
| Engine Partner Cores (V2) | V2_PRTNR | All PRTNR | Various - see deployments/engine/ directory DEPLOYMENTS.md files |
| AB Core V3 (current) | V3 | 374+ | 0x99a9B7c1116f9ceEB1652de04d5969CcE509B069 |
AB Core V3 changelog here, and performance metrics here.
The following represents the current set of flagship core contracts deployed on the Goerli testnet, and their active Minter Filters:
-
Art Blocks Artist Staging (Goerli):
-
Art Blocks Dev (Goerli):
For deployed core contracts, see the deployment details in the /deployments/engine/[V2|V3]/<engine-partner>/ directories. For V2 core contracts, archived source code is available in the /posterity/engine/ directory.
BytecodeStorageReader (currently on V1 version) is public library for reading from storage contracts. This library is intended to be deployed as a standalone contract, and provides all read functionality by being used as an externally linked library within the Art Blocks ecosystem contracts that use contract storage for writes.
Given that it is an externally linked library with a shared public deployment, the deployment addresses for these shared deployments are referenced in our shared deployments constants.ts util (in the BYTECODE_STORAGE_READER_LIBRARY_ADDRESSES constant) so that they may be linked at time of deployment and are also linked here below for shared reference:
- V1
BytecodeStorageReader(goerli): https://goerli.etherscan.io/address/0xB8B806A10d16cc80dB788552B54B3ECb4A2A3C3D#code - V1
BytecodeStorageReader(mainnet): https://etherscan.io/address/0xf0585dF582A0ad119F1616FB82f3b449a98EeCd5#code
For details on the Flagship and Engine Minter Suite, see the minter suite documenation.
- Goerli: https://goerli.etherscan.io/address/0xec5dae4b11213290b2dbe5295093f75920bd2982#code
- Ropsten: https://ropsten.etherscan.io/address/0x7ba972189ED3C527847170453fC108707F62755a#code
- Rinkeby: https://rinkeby.etherscan.io/address/0x3b30d421a6dA95694EaaE09971424F15Eb375269#code
- Kovan: https://kovan.etherscan.io/address/0x3b30d421a6dA95694EaaE09971424F15Eb375269#code
- Mainnet: https://etherscan.io/address/0x088098f7438773182b703625c4128aff85fcffc4#code
In an effort to ensure source code verification is easily completed by anyone, After 10, January 2023, all mainnet deployments should also have a corresponding tag+release in this GitHub repository. For deployments prior to this date, PR history may be used to determine the commit hash used for a given deployment. Currently, all mainnet deployments of contracts developed in this repositiory are verified on Etherscan.
Art Blocks supports on-chain royalty lookups for all Flagship and Engine tokens on Manifold's Royalty Registry. This enables royalty revenue streams for artists and other creators.
For information about on-chain royalties, please see the royalties documentation.
An NPM package is published that includes all contracts in the /contracts/ directory. The /contracts/archive/ directory contains contracts that were previously published, but are no longer actively developed, but should still be included in our published npm package. For example, the original Art Blocks core contracts are included in the /contracts/archive/ directory so they may be actively integrated with subgraphs and frontends, even though they are no longer actively developed.
Your .env file should contain a COINMARKETCAP_API_KEY param in order to calculate ethereum gas costs. The key value can be found in the Engineering team's shared 1Password account. Additionally, you'll need to add the following object within the module.exports key in hardhat.config.ts:
gasReporter: {
currency: "USD",
gasPrice: 100,
enabled: true,
coinmarketcap: process.env.COINMARKETCAP_API_KEY
}
After this config is finished, you'll notice a usd (avg) column in the auto-generated table that's printed when you run unit tests with yarn test.
(note: gasPrice is a variable param that reflects the gwei/gas cost of a tx)
- Primary Sales and Minting Contract (no longer in use) 0x059edd72cd353df5106d2b9cc5ab83a52287ac3a
- This is the original Art Blocks smart contract which had a built in minter. This contract represents only projects 0 (Chromie Squiggle), 1 (Genesis), 2 (Construction Token) and handled both control of the NFTs and the purchase transactions. This smart contract received funds and automatically split them between the artist and the platform.
- Secondary Sales Receiving and Sending Address (no longer in use) 0x8e9398907d036e904fff116132ff2be459592277
- This address received secondary market royalties from https://opensea.io until July 29th 2021. These royalties were subsequently distributed to artists directly from this address. After July 29th the secondary royalty address was changed to the current one on the first page of this doc.
- Primary Sales Minting Contracts (no longer in use) –
- 0x091dcd914fCEB1d47423e532955d1E62d1b2dAEf
- 0x1Db80B860081AF41Bc0ceb3c877F8AcA8379F869
- 0xAA6EBab3Bf3Ce561305bd53E4BD3B3945920B176
- 0x0E8BD86663e3c2418900178e96E14c51B2859957
- These are the Smart contract that received funds from primary sales and split them between the artist(s) and the platform. Artists received funds directly from this contract. These minter contracts are no longer in use.
evm.codes - An interactive guide to EVM op-code costs.
The Art Blocks artblocks-contracts repo is open source software licensed under the GNU Lesser General Public License v3.0. For full license text, please see our LICENSE declaration file.