├── .github └── workflows │ └── retype-action.yml ├── .gitignore ├── CODEOWNERS ├── LICENSE ├── README.md ├── art-blocks-101 ├── generator.md ├── index.yml ├── introducing-the-onchain-generator.md ├── on-chain.md └── postparams.md ├── art-blocks-api ├── api-overview.md ├── artblocks-viewer.md ├── entities.md ├── index.yml └── queries.md ├── art-blocks-engine-onboarding ├── art-blocks-engine-101 │ ├── Embroidery-on-Art-Blocks-Engine.md │ ├── Engine-opensea-setup.md │ ├── Engine-partner-onboarding-steps.md │ ├── Engine-project-launch.md │ ├── Engine-royalty-registry-setup-(V2-only).md │ ├── Engine-technical-details.md │ ├── Filebase-IPFS.md │ ├── IPFS-Setup.md │ ├── Marketing-and-Launch-Prep │ ├── Mobile-Minter.md │ ├── README.md │ ├── custom-dashboard-mutations.md │ ├── faqs.md │ ├── minter-suite-migration-runbook.md │ └── what is Art Blocks Engine.md └── index.yml ├── core-contract-v3 ├── dashboard.md ├── erc2981-royalties.md ├── index.yml ├── manual-admin-operations.md └── overview.md ├── creator-onboarding ├── creators.md └── index.yml ├── favicon.ico ├── legacy.md ├── minter-suite ├── custom-minters.md ├── index.yml ├── minter-suite-supplemental.md ├── minting-philosophy.md ├── seadrop-integration.md └── shared-minter-suite.md ├── public-api-docs └── index.html ├── retype.yml └── static ├── Filebase_setup1.png ├── Filebase_setup2.png ├── Filebase_setup3.png ├── Filebase_setup4.png ├── Filebase_setup5.png ├── Filebase_setup6.png ├── Pinata_setup_1.png ├── Pinata_setup_2.png ├── Pinata_setup_3.png ├── Pinata_setup_4.png ├── Pinata_setup_5.png ├── getDependencyDetails.png ├── getDependencyScript.png ├── onChainHtml.png ├── onChainSquig.png ├── projectDetails.png ├── projectScriptByIndex.png ├── projectScriptInfo.png ├── screenshot1.png ├── screenshot2.png ├── screenshot3.png ├── screenshot4.png ├── squigLogo.png └── tokenHash.png /.github/workflows/retype-action.yml: -------------------------------------------------------------------------------- 1 | name: Publish Retype powered website to GitHub Pages 2 | on: 3 | workflow_dispatch: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | publish: 10 | name: Publish to retype branch 11 | 12 | runs-on: ubuntu-latest 13 | 14 | steps: 15 | - uses: actions/checkout@v2 16 | 17 | - uses: retypeapp/action-build@latest 18 | with: 19 | license: ${{ secrets.RETYPE_SECRET }} 20 | 21 | - uses: retypeapp/action-github-pages@latest 22 | with: 23 | update-branch: true -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .retype 2 | .DS_Store 3 | -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Request review from the best fit approvers group for this repo. 2 | * @ArtBlocks/Eng 3 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | --- 2 | label: Welcome 3 | icon: home 4 | --- 5 | 6 | # Welcome to the Art Blocks Docs! 7 | 8 | This documentation seeks to provide guidance for 3 primary audiences: 9 | 10 | 1) artists/creators preparing their projects to launch on Art Blocks or an Art Blocks Engine platform 11 | 2) current and prospective Engine partners 12 | 3) integrators/aggregators/marketplaces etc., looking to integrate with the Art Blocks APIs 13 | 14 | You will find the three main sections in our documentation mirrors these three primary audiences. Please explore the docs here, and let us know if you have any questions. 15 | 16 | For any issues with the docs, please file a bug [here](https://github.com/ArtBlocks/artblocks-docs/issues), or send us a PR with a suggested change! 17 | 18 | [![GitPOAPs](https://public-api.gitpoap.io/v1/repo/ArtBlocks/artblocks-docs/badge)](https://www.gitpoap.io/gh/ArtBlocks/artblocks-docs) 19 | -------------------------------------------------------------------------------- /art-blocks-101/generator.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 900 3 | description: Art Blocks Generator. 4 | --- 5 | 6 | # Art Blocks Generator 7 | 8 | The Art Blocks Generator combines artist scripts with token metadata to create unique generative art NFTs. This document outlines the basics of how the generator works, the structure of the token metadata, and related requirements for artist scripts. 9 | 10 | ## HTML Document 11 | 12 | The Art Blocks Generator builds an html document that includes: 13 | 14 | - A `tokenData` object that contains on-chain metadata for the NFT, including the token's hash and ID. 15 | - The artist's on-chain project script 16 | - (optional) A dependency used by the script. p5js, for example, is a common dependency. 17 | - (optional) For flex projects, external asset dependencies from the Art Blocks Dependency Registry. 18 | 19 | The HTML document created by the Generator may look something like the following: 20 | 21 | ```html 22 | 23 | 24 | 25 | 28 | 34 | 37 | 38 | 39 | 40 | ``` 41 | 42 | !!!info 43 | An on-chain version of he Art Blocks Generator is in development, which will allow for even more robust preservation of Art Blocks projects. 44 | !!! 45 | 46 | ## The `tokenData` Object 47 | 48 | The `tokenData` object is injected into the html document by the Art Blocks Generator. It contains the following fields: 49 | 50 | ```json 51 | tokenData = { 52 | // 32-byte hash of the token 53 | hash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", 54 | // tokenId = projectId * 1_000_000 + invocation 55 | tokenId: "1234567" 56 | } 57 | ``` 58 | 59 | For Art Blocks Flex projects, the `tokenData` object may also include: 60 | 61 | ```json 62 | tokenData = { 63 | ... 64 | // URL to preferred Arweave gateway 65 | preferredArweaveGateway: "https://arweave.net/", 66 | // URL to preferred IPFS gateway 67 | preferredIPFSGateway: "https://designator-string.mypinata.cloud/ipfs", 68 | // array of external asset Flex Dependencies 69 | externalAssetDependencies: [ 70 | { 71 | // type of dependency 72 | dependency_type: "IPFS", 73 | // content identifier for the asset 74 | cid: "QmbxU6subfSzzpxketBhVBVCGhFBPdTSB8nCtppGZtpZGf", 75 | // data related to the asset (if any) 76 | data: null 77 | } 78 | ] 79 | } 80 | ``` 81 | 82 | The `dependency_type` field will be one of the following values: 83 | 84 | - `"IPFS"` 85 | - `"ARWEAVE"` 86 | - `"ONCHAIN"` 87 | - `"ART_BLOCKS_DEPENDENCY_REGISTRY"` 88 | 89 | Note that project scripts are responsible for fetching any IPFS or Arweave assets. 90 | 91 | For "ART_BLOCKS_DEPENDENCY_REGISTRY" dependencies, the `cid` field will be the dependency's registry key, the data field will remain null, and additional script tag(s) will be injected into the html document to load the dependency. 92 | 93 | For example, the following script tag would be injected into the html document for a dependency with the key `p5js@1.9.0`: 94 | 95 | ```html 96 | 97 | ``` 98 | 99 | > If a dependency has been uploaded to the Art Blocks Dependency Registry, the on-chain generator will automatically inject the appropriate script tag(s) into the html document. 100 | 101 | ## Learning More 102 | 103 | For additional technical resources and documentation, please refer to the Technical Requirements described in the [help.artblocks.io documentation](https://help.artblocks.io/Technical-Requirements-7f9a9aaf39ea4f20b2d5b948cf08d5aa). 104 | -------------------------------------------------------------------------------- /art-blocks-101/index.yml: -------------------------------------------------------------------------------- 1 | icon: books 2 | label: Art Blocks 101 3 | expanded: true 4 | route: /creator-docs/art-blocks-101/ 5 | -------------------------------------------------------------------------------- /art-blocks-101/introducing-the-onchain-generator.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 1100 3 | description: A technical overview of the on-chain generator and introduction to the ecosystem of preservation projects at Art Blocks. 4 | --- 5 | 6 | # Introducing the On-Chain Generator 7 | 8 | *by Ben Yoshiwara* 9 | 10 | Art Blocks is excited to announce a new advancement in our commitment to preserving the unique digital artworks created on our platform: the deployment of our on-chain generator contract. This represents a step forward in ensuring the perpetual availability and accessibility of Art Blocks pieces. 11 | 12 | Want to see it in action? Check out our [demo repository](https://github.com/ArtBlocks/on-chain-generator-viewer) and [demo site](https://artblocks.io/onchain/generator) to see how easy it is to display Art Blocks works with the on-chain generator! 13 | 14 | ## Progressing Art Blocks Preservation 15 | 16 | In the past, viewing an Art Blocks piece relied on a centralized [generator](https://docs.artblocks.io/creator-docs/art-blocks-101/generator/) to assemble the HTML document that makes up an artwork, combining a project’s script and dependencies. The project's creative code and essential parameters are stored on-chain, and while the artwork can be manually reconstructed by anyone, for convenience Art Blocks has served artworks up with a backend. 17 | 18 | This new on-chain generator removes the need for that backend entirely, allowing anyone to retrieve any Art Blocks artwork entirely using just a single call to our smart contract. 19 | 20 | We’ve ensured that the complete process of generating viewable Art Blocks pieces is now preserved on-chain. This means that even in the distant future, these artworks can be reconstructed and displayed using only the information stored on the Ethereum blockchain, aligning with Art Blocks’ broader efforts in digital art preservation. While our conventional web server-based generator will remain the primary way to view Art Blocks pieces, this on-chain preservation secures their longevity and accessibility for generations to come. 21 | 22 | ## Why This Matters 23 | 24 | The most commonly used dependencies, **p5js** and **threejs**, are now [stored on-chain](https://docs.artblocks.io/creator-docs/art-blocks-101/on-chain/#summary). This means that approximately 90% of all Art Blocks flagship projects can now be fully constructed from on-chain components, while the remaining 10% identify a preferred CDN for already broadly-distributed npm packages that exist on hundreds of thousands of hard drives around the world. 25 | 26 | This advancement represents a significant step in ensuring the long-term preservation of Art Blocks pieces. If our conventional infrastructure were to ever become unavailable, the on-chain generator contract handles the complete assembly automatically, ensuring your artwork can always be reconstructed. As long as the Ethereum blockchain exists, these artworks can be constructed and viewed in a web browser without relying on any centralized infrastructure or implicit knowledge. 27 | 28 | ## Building the Complete System 29 | 30 | Our implementation combines several key components: 31 | 32 | - **The Core Contracts**: Store the project's creative code and token-specific data that define each unique artwork. 33 | - **[The Dependency Registry](https://etherscan.io/address/0x37861f95882ACDba2cCD84F5bFc4598e2ECDDdAF#readProxyContract)**: Manages JavaScript library dependencies for projects across supported Art Blocks contracts. Dependencies can be referenced via CDN or stored fully on-chain, allowing for progressive decentralization. We've started by uploading our most widely used dependencies on-chain: **p5.js** (v1.0.0) and **three.js** (v0.124.0), with plans to add more over time. 34 | - **[scripty.sol](https://github.com/intartnft/scripty.sol)**: "A gas-efficient on-chain HTML builder service that's tuned for stitching large JS based tags together." Created by [int.art](https://int.art/). Big shout out to the int.art team for building **scripty.sol**, which was instrumental in making this project possible! 35 | - **[The Generator Contract](https://etherscan.io/address/0x953D288708bB771F969FCfD9BA0819eF506Ac718#readProxyContract)**: Orchestrates the entire process by combining the project script and token data from the core contracts with the appropriate dependency from the registry, assembling everything into a complete, ready-to-view HTML document using **scripty.sol**. The generator supports both plain text HTML and base64-encoded data URIs for maximum flexibility in how the artworks can be displayed. 36 | 37 | ## Looking Forward 38 | 39 | Art Blocks is dedicated to developing cutting-edge technical solutions for the long-term preservation of artworks released on our platform. Through innovations like the **BytecodeStorage** library, **Dependency Registry**, and **On-Chain Generator**, we are expanding the boundaries of blockchain capabilities and remain committed to pushing these limits further in the future. 40 | -------------------------------------------------------------------------------- /art-blocks-101/on-chain.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 1000 3 | description: An overview of different NFT metadata storage mechanisms used by Art Blocks NFTs. 4 | --- 5 | 6 | # NFT Metadata Storage at Art Blocks 7 | 8 | An overview of NFT metadata storage philosophy and implementations at Art Blocks. 9 | 10 | ## Summary 11 | 12 | Art Blocks tokens store their metadata fully on-chain, ensuring collectors that their NFTs will always remain accessible and immutable. 13 | 14 | Token outputs are assembled on-chain by the Art Blocks On-Chain Generator, which retrieves the token's script and dependencies from the blockchain and assembles them into an HTML document that can be viewed in a web browser. 15 | 16 | For projects that require dependencies (e.g. p5js), Art Blocks provides the [Art Blocks Dependency Registry](https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/README.md#dependencyregistry), a fully on-chain software registry that can be used to optionally store dependency releases on-chain, as well as reference preferred software storage networks. 17 | 18 | Art Blocks Engine Flex NFTs also provide the option to store metadata on decentralized storage networks, such as IPFS or Arweave, to enable larger sized assets to be used when generating outputs. 19 | 20 | ```mermaid 21 | erDiagram 22 | ArtBlocks-Smart-Contract ||--|| Token-Ownership :on-chain 23 | ArtBlocks-Smart-Contract ||--o{ ArtBlocks-Project: contains 24 | ArtBlocks-Project ||--|| Artist-Script: on-chain 25 | ArtBlocks-Project ||--|| Other-Project-Metadata: on-chain 26 | ArtBlocks-Project }|--|| ArtBlocks-Dependency-Registry: references 27 | ArtBlocks-Dependency-Registry ||--o{ Dependency: list-of 28 | Dependency }|--o| On-Chain-Dependency-Code: optionally-on-chain 29 | Dependency }|--|| On-Chain-License: on-chain 30 | Dependency ||--|{ Preferred-Software-Registries: points-to 31 | ArtBlocks-Project }|..o{ Flex-Dependencies: engine-flex-only 32 | Flex-Dependencies }|--o{ IPFS-Arweave-Assets: may-include 33 | Flex-Dependencies ||--o{ On-Chain-Assets: may-include 34 | On-Chain-Generator ||--o{ ArtBlocks-Project: retrieves-on-chain-data 35 | On-Chain-Generator ||..o{ Flex-Dependencies: engine-flex-only 36 | On-Chain-Generator ||--o{ ArtBlocks-Dependency-Registry: retrieves-on-chain-data 37 | Web-Browser }|--|| On-Chain-Generator: assembles-html-and-displays-token 38 | Flex-Dependencies }|--|{ ArtBlocks-Dependency-Registry: may-include-assets-on 39 | ``` 40 | 41 | ## Overview of NFT Metadata Storage Options 42 | 43 | While all NFTs track token ownership on a blockchain, the metadata for the NFT (image or audio information, artist information, etc.) may be stored in a variety of ways. Common options include: 44 | 45 | | Storage Type | Immutable | Decentralized | Guaranteed to Persist Forever [^1] | Cost | 46 | | --------------------------------------------------------------- | --------- | ------------- | ---------------------------------- | ------ | 47 | | [Servers/Hosting](#servershosting) | No | No | No | Low | 48 | | [Hash On-Chain](#hash-on-chain) | Yes | No | No | Low | 49 | | [Decentralized Storage Network](#decentralized-storage-network) | Yes | Yes | No [^2] | Medium | 50 | | [Fully On-Chain](#fully-on-chain) | Yes | Yes | Yes | High | 51 | | [Software Registry](#software-registries) | ~Yes [^3] | ~Yes | No, Very Low Risk | Low | 52 | 53 | [^1]: As long as the blockchain network continues to exist. 54 | [^2]: Requires ≥1 interested party 55 | [^3]: Typically hash of release is published to prevent tampering/changes 56 | 57 | ### Servers/Hosting 58 | 59 | The metadata are stored on a server or cloud hosting service, such as AWS. This is a convenient and cheap option, but it has a few drawbacks: 60 | 61 | - The metadata can be changed by the server owner, so the NFT is not immutable. 62 | - The metadata can be lost if the server goes down or an admin decides not to discontinue paying for the service. 63 | - The metadata can be censored by the server owner. 64 | 65 | ### Hash On-Chain 66 | 67 | The hash of the metadata is stored on-chain, and the metadata is stored on a server. Storing the hash of the metadata makes the NFT immutable, while keeping it much cheaper than storing all of the metadata on-chain. However, it has a few drawbacks: 68 | 69 | - The metadata can be lost if the server goes down or an admin decides not to discontinue paying for the service. 70 | - The metadata can be censored by the server owner. 71 | 72 | Projects such as CryptoPunks originally stored the hash of the metadata on-chain, but the metadata was stored on a server. They have since upgraded to a fully on-chain solution. 73 | 74 | ### Decentralized Storage Network 75 | 76 | The metadata are stored on a decentralized storage network, such as IPFS or Arweave. This is a popular option, and enables the NFT to be immutable. Drawbacks include: 77 | 78 | - The metadata must remain pinned by at least one party in order to be accessible. 79 | 80 | ### Fully On-Chain 81 | 82 | The metadata are stored on the blockchain. This is the most expensive option, but it has many advantages. The metadata are always accessible and available, as long as the NFT exists. Collectors and artists never have to worry about a token's outputs disappearing. 83 | 84 | ### Software Registries 85 | 86 | Some NFTs (like some Art Blocks project tokens) may rely on published software libraries when generating outputs. In these cases, the NFT metadata may include information about dependencies and where to find them (e.g. "p5js, v1.0.0 on the cdnjs software registry"). Software registries are a special form of decentralized storage, because of the distributed nature of the software repositories and many downloads on developers' computers worldwide. 87 | 88 | ## Art Blocks Storage Solutions 89 | 90 | ### Art Blocks Fully On-Chain 91 | 92 | Art Blocks Flagship and Art Blocks Engine NFTs only rely on fully on-chain storage solutions, plus allowing a single dependency to be housed on a software registry. This provides an extremely high level of confidence that the NFTs will remain fully accessible and immutable for the foreseeable future. 93 | 94 | While Art Blocks originally relied on widely used software registries to house dependencies, the Art Blocks team has since created a **fully on-chain software registry called the [Art Blocks Dependency Registry](https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/README.md#dependencyregistry)**. The registry is fully decentralized and is used by all Art Blocks Flagship NFTs. The registry enables dependencies to be stored fully on-chain, when the gas costs are justified. Art Blocks uploaded their first dependency, p5js v1.0.0, to the registry in January 2024, retiring any doubt that projects relying on p5js@1.0.0 would ever be unable to generate their outputs in the future. 95 | 96 | ### Engine Flex 97 | 98 | Art Blocks Engine Flex NFTs provide an additional option for storing metadata. Flex NFTs can store metadata on-chain, or they can store the metadata immutably on the IPFS or Arweave decentralized storage networks. This allows Flex NFTs to utilize larger sized assets when generating outputs, while still providing the option for fully on-chain metadata where possible. 99 | 100 | ## Examples 101 | 102 | ## On-Chain Generator Example 103 | 104 | Let's review an example of how to retrieve the html that allows your browser to view the output of the first Art Blocks Token, token zero of project 0, [Chromie Squiggle by Snowfro](https://www.artblocks.io/marketplace/asset/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0). 105 | 106 | 1. Visit the Art Blocks On-Chain Generator on Etherscan: [0x953D288708bB771F969FCfD9BA0819eF506Ac718](https://etherscan.io/address/0x953D288708bB771F969FCfD9BA0819eF506Ac718#readProxyContract) 107 | 108 | 2. Get the html for token 0 by calling the `getTokenHtml` function with the core contract address `0x059edd72cd353df5106d2b9cc5ab83a52287ac3a` and token ID `0` as the input parameters: 109 | 110 | ![onChainHtml](/static/onChainHtml.png) 111 | 112 | 3. The returned text is the html that is used to generate the token's output. You can also copy and paste a base64-encoded version of this html in your browser to view the token's output! Use the function `getTokenHtmlBase64EncodedDataUri` to get the base64-encoded version of the html, and paste it into your browser's address bar to view the token's output. 113 | 114 | ![onChainHtmlBase64](/static/onChainSquig.png) 115 | 116 | This process of retrieving and viewing tokens is streamlined in our open source [on-chain generator viewer](https://github.com/ArtBlocks/on-chain-generator-viewer) 117 | 118 | ## On-Chain Script Example 119 | 120 | Let's review an example of how to retrieve the token and script metadata for the first Art Blocks Token, token zero of project 0, [Chromie Squiggle by Snowfro](https://www.artblocks.io/collections/curated/projects/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0). 121 | 122 | > Note: Newer versions of Art Blocks core contracts have different function names than the V0 Art Blocks core contract shown in this example. 123 | 124 | While we could query the Art Blocks Subgraph or API to retrieve the metadata, we will retrieve the metadata directly from the blockchain. 125 | 126 | 1. Visit the original Art Blocks Core Contract on Etherscan: [0x059EDD72Cd353dF5106D2B9cC5ab83a52287aC3a](https://etherscan.io/address/0x059EDD72Cd353dF5106D2B9cC5ab83a52287aC3a#readContract) 127 | 2. Get project 0's metadata by calling the `projectDetails` function with the project ID as the input parameter: 128 | 129 | ![projectDetails](/static/projectDetails.png) 130 | 131 | 3. Get project 0's script details by calling the `projectScriptInfo` function with the project ID as the input parameter: 132 | 133 | ![scriptDetails](/static/projectScriptInfo.png) 134 | 135 | 4. Get the script javascript by calling the `projectScriptByIndex` function with the project ID and index 0 as the input parameter. The returned text is the javascript code that is used to generate Chromie Squiggles! 136 | 137 | ![scriptByIndex](/static/projectScriptByIndex.png) 138 | 139 | 5. Get token 0's token hash by calling the `showTokenHashes` function with the token ID as the input parameter. This is the hash that is injected into the script to generate the token's unique output. 140 | 141 | ![tokenHash](/static/tokenHash.png) 142 | 143 | ## On-Chain Dependency Example 144 | 145 | Let's review an example of how to retrieve the dependency metadata for the first Art Blocks Token, token zero of project 0, [Chromie Squiggle by Snowfro](https://www.artblocks.io/collections/curated/projects/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0). 146 | 147 | In this case, the project uses the p5js v1.0.0 dependency, which is stored fully on-chain via the Art Blocks Dependency Registry. While we could query the Art Blocks Subgraph or API to retrieve the metadata, we will retrieve the metadata directly from the blockchain. 148 | 149 | 1. Visit the Art Blocks Dependency Registry on Etherscan: [0x37861f95882ACDba2cCD84F5bFc4598e2ECDDdAF](https://etherscan.io/address/0x37861f95882ACDba2cCD84F5bFc4598e2ECDDdAF#readProxyContract) 150 | 151 | 2. Get the dependency details by calling the `getDependencyDetails` function with the dependency name and version as the input parameters. At this time, we translate from the string `p5@1.0.0` to its bytes representation `0x703540312e302e30`: 152 | 153 | ![dependencyDetails](/static/getDependencyDetails.png) 154 | 155 | 3. Get the dependency code by calling the `getDependencyScript` function with the dependency name and version as the input parameters. We again translate to the bytes representation `0x703540312e302e30`, and can increment the index to get all 10 chunks of the dependency code: 156 | 157 | ![dependencyScript](/static/getDependencyScript.png) 158 | 159 | And that's it! We now have all of the information we need to generate the token's output, and we can be confident that the metadata will always be available and immutable! 160 | 161 | > Note: At this time, dependency scripts are stored compressed via gzip on-chain. Updates are planned to store code that can unzip the dependencies. 162 | -------------------------------------------------------------------------------- /art-blocks-101/postparams.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 800 3 | description: PostParams 4 | --- 5 | 6 | # PostParams 7 | 8 | PostParams are a technology that allow generative tokens to evolve over time while still preserving core artistic intent. 9 | 10 | Configurable parameters are stored on the blockchain, and can be updated over time. A project's artist decides what PostParams exist, how they can be changed, and who can make changes. 11 | 12 | ## Creative Possibilities 13 | 14 | PostParams opens up a wide range of creative avenues for generative artists and collectors alike: 15 | 16 | - **Collector Customization**: Allow collectors to toggle between color palettes, visual styles, or animation behaviors within artist-defined parameters. 17 | - **Artist-Collector Collaboration**: Create works where both artist and the collector have specific controls, establishing a collaborative relationship. 18 | - **Physical Art Connections**: Enable collectors to configure PostParams before the physical production of artworks, creating a bridge between digital and physical realms. 19 | - **Living Artworks**: Design pieces that evolve over time through interactions or changing parameters, telling an ongoing story. 20 | - **Network Effects**: Enable multiple token owners to influence different aspects of related artworks, creating community-driven, networked experiences. 21 | 22 | **Future Development**: 23 | 24 | - **Real-World Data**: Design art that reacts to on-chain data like ETH price, wallet address, or other external inputs. 25 | 26 | _Note: Please reach out to the Art Blocks team if you would like to explore reacting to live, on-chain data. We are happy to help you brainstorm your creative ideas._ 27 | 28 | # How-To Guide 29 | 30 | ## Video Tutorial 31 | 32 | TBD... 33 | 34 | ## Configuring project as artist 35 | 36 | As an artist, the creator dashboard (create.artblocks.io) is the easiest way to configure your project's PostParams. The creator dashboard allows you to configure the following: 37 | 38 | - Parameter names 39 | - Parameter values 40 | - Parameter types 41 | - Parameter constraints/limits 42 | - Parameter lock dates 43 | 44 | Note that if you would like your PostParams to show up as feature overrides, using the same parameter name as a feature name will properly override the feature. 45 | 46 | ## Configuring token as collector 47 | 48 | Token owners may log into the artblocks.io website and configure PostParams for their token on the token's page. The website will display a preview of the token with edited values, allowing collectors to preview the changes before forever registering the changes on the blockchain as part of the token's provenance. The connected wallet must have authority to change parameters for the token, or be a valid delegate for the token on delegate.xyz v2. 49 | 50 | # Technical Overview 51 | 52 | ## Compatibility 53 | 54 | Recent Art Blocks Engine Flex NFTs (core version v3.2.5+) support configurable PostParams. If you would like an updated core contract, please contact the Art Blocks team. 55 | 56 | ## Supported parameter types 57 | 58 | - Enum 59 | - Boolean 60 | - Integer Number Range 61 | - Decimal Number Range 62 | - Color 63 | - Timestamp (1970+) 64 | - String 65 | 66 | ## Supported Authorization Methods 67 | 68 | - Artist 69 | - Token Owner 70 | - Address/Smart Contract 71 | 72 | ## Supported Parameter Constraints 73 | 74 | - Min 75 | - Max 76 | - Lock date 77 | 78 | ## Accessing PostParams in project script 79 | 80 | PostParams are injected using the typical Art Blocks Generator's `tokenData` object in a Flex Dependency's data field. 81 | 82 | The following is a simple example of how to access an integer parameter in your project script: 83 | 84 | ```javascript 85 | // Typically, the first external asset dependency is the PostParam. 86 | // You can check your project configuration on Art Blocks Creator Dashboard 87 | // under Scripts => Flex Assets, and the PostParam asset will show up as the 88 | // external asset dependency with text "#web3call-contract#" 89 | const pp = tokenData.externalAssetDependencies[0]; 90 | 91 | // helper function to parse PostParam integer values, or fallback 92 | // to the token-hash-based value if the PostParam value is not set 93 | function getPpInt(ppVal, hashBasedVal) { 94 | const n = parseInt(ppVal); 95 | return isNaN(n) ? hashBasedVal : n; 96 | } 97 | 98 | // accessing a PostParam named "NumShapes" 99 | const amountMoving = getPpInt( 100 | pp?.data?.["NumShapes"], // prioritize the PostParam value if defined 101 | R.random_int(0, 100) // R is the hash-based pseudorandom number generator 102 | ); 103 | ``` 104 | 105 | The following is a more complete example of how to access multiple PostParams of different types in your project script. 106 | 107 | ```javascript 108 | // Palettes are defined in the script, as well as in the PostParam Configuration as an enum 109 | let palettes = [ 110 | { 111 | name: "Midnight Citrus", 112 | colors: ["#0f0f1c", "#ffcc00", "#ff7f11", "#ffa69e", "#4d194d"], 113 | }, 114 | { 115 | name: "Electric Bloom", 116 | colors: ["#8ecae6", "#219ebc", "#023047", "#ffb703", "#fb8500"], 117 | }, 118 | { 119 | name: "Forest Neon", 120 | colors: ["#073b3a", "#0b6e4f", "#08a045", "#d4d700", "#fdfcdc"], 121 | }, 122 | ]; 123 | 124 | // Typically, the first external asset dependency is the PostParam. 125 | const pp = tokenData.externalAssetDependencies[0]; 126 | 127 | // helper function to parse PostParam integer values, or fallback 128 | // to the token-hash-based value if the PostParam value is not set 129 | function getPpInt(ppVal, hashBasedVal) { 130 | const n = parseInt(ppVal); 131 | return isNaN(n) ? hashBasedVal : n; 132 | } 133 | 134 | // helper function to parse boolean values from PostParam strings, or fallback 135 | // to the token-hash-based value if the PostParam value is not set 136 | function parsePpBool(ppVal, hashBasedVal) { 137 | if (ppVal === "true") return true; 138 | if (ppVal === "false") return false; 139 | // if undefined, return hashBasedVal 140 | return hashBasedVal; 141 | } 142 | 143 | // --- ACCESSING VARIOUS PostParams --- 144 | 145 | // get enum PostParam "Palette", fallback to hash-based random choice 146 | const hashBasedPalette = R.random_choice(palettes); 147 | const palette = 148 | palettes.find((p) => p.name === pp.data["Palette"]) || hashBasedPalette; 149 | 150 | // get boolean PostParam "Animate", fallback to hash-based random boolean 151 | const animate = parsePpBool(pp?.data?.["Animate"], R.random_dec() < 0.5); 152 | 153 | // get integer PostParam "NumShapes", fallback to hash-based random integer 154 | const numShapes = getPpInt( 155 | pp?.data?.["NumShapes"], // prioritize the PostParam value if defined 156 | R.random_int(10, 100) // hash-based fallback 157 | ); 158 | 159 | // get color PostParam "BackgroundColor", fallback to white 160 | const backgroundColor = pp?.data?.["BackgroundColor"] ?? "#ffffff"; 161 | 162 | // get timestamp PostParam "Birthday", fallback to null 163 | const birthdayTimestamp = pp?.data?.["Birthday"] ?? null; 164 | 165 | // get string PostParam "Name", fallback to null 166 | const name = pp?.data?.["Name"] ?? null; 167 | 168 | // --- END ACCESSING PostParams --- 169 | ``` 170 | 171 | ## PostParams as token features 172 | 173 | Token features, for example `type: bold` on the Chromie Squiggle, are a way to enrich your tokens with artist-specified metadata. 174 | 175 | PostParams may be used as token features, and will override the feature if a PostParam with the same name exists. 176 | 177 | For example, if you have a feature named `Color` and a PostParam named `Color`, the PostParam will override the feature's value after it is configured. Upon each re-configuration, the token's features will be updated to match the configured PostParam value. 178 | 179 | Additionally, PostParams will be injected into a project's features script, allowing the features script to translate from a PostParam to whatever feature is desired. This enables more complex parsing and translation of PostParams to features that the more simple by-name override method cannot. The `tokenData` object in the features script contains external asset dependencies in the same format as the `tokenData` object in the project script. 180 | 181 | ## Updating PostParams 182 | 183 | PostParams may be updated at any time, provided the connected wallet has authority to change PostParams for the token, or is a valid delegate for the token on delegate.xyz v2. The parameter must also not be locked (see next section). 184 | 185 | ## Locking PostParams 186 | 187 | Artists may configure a parameter to be locked at a specific date and time, at the project level. Once the parameter is locked, it may never be unlocked, cementing the parameter value at the time of locking. 188 | 189 | ## Hooks and Live Data 190 | 191 | The PostParam system is designed to be extensible to allow for live data hooks. This enables injecting any live on-chain data into the project script. This is more advanced functionality and may require some solidity coding. Please reach out to the Art Blocks team if you would like to explore ideas in this area. 192 | 193 | The Art Blocks team has published a few examples of live data hooks in the [Art Blocks Contracts GitHub repository](https://github.com/ArtBlocks/artblocks-contracts/tree/main/packages/contracts/contracts/web3call/augment-hooks). Examples include: 194 | 195 | - injecting token owner's address and ETH balance 196 | - injecting the price of Ethereum 197 | - injecting Chromie Squiggle's floor price 198 | - injecting block parameters such as gas price 199 | - injecting the result of a chainlink oracle 200 | 201 | Configuring hooks is not currently available in the creator dashboard, but can be easily configured with tools like etherscan. Please reach out to the Art Blocks team if you would like to explore this. 202 | -------------------------------------------------------------------------------- /art-blocks-api/artblocks-viewer.md: -------------------------------------------------------------------------------- 1 | # Artblocks Viewer 2 | 3 | An overview of [live.artblocks.io](https://live.artblocks.io/) 4 | 5 | ## Routes 6 | 7 | > All routes are for the environment specified in .env file and act as such. i.e. Ropsten contracts will not work on mainnet and vice versa 8 | 9 | **live.artblocks.io/** 10 | Home page of the site which returns the latest _rendered_ minted token from any of the Art Blocks contracts 11 | 12 | **live.artblocks.io/`{CONTRACT_ADDRESS}`** enter any Art Blocks or Engine contract and you be presented with the latest _rendered_ mint. 13 | 14 | - _Example:_ [Latest Artblocks_VO mint](https://live.artblocks.io/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a) 15 | 16 | **live.artblocks.io/`{CONTRACT_ADDRESS}`/`{PROJECT_INDEX}`** enter any Art Blocks or Engine contract followed by the index of the project and you be presented with the latest _rendered_ mint. 17 | 18 | - _Example:_ [Latest Chromie Squiggle mint](https://live.artblocks.io/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0) 19 | 20 | **live.artblocks.io/token/`{TOKEN_ID}`** enter any Art Blocks or Engine token id and you are presented with that token. 21 | 22 | - _Example:_ [Chromie Squiggle mint #71](https://live.artblocks.io/token/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a-71) 23 | 24 | **live.artblocks.io/random/`{CONTRACT_ADDRESS}`** enter any Art Blocks or Engine contract address and you are presented with a random active project 25 | 26 | - _Example:_ [Random Art Blocks v3 contract](https://live.artblocks.io/random/0x99a9b7c1116f9ceeb1652de04d5969cce509b069) 27 | 28 | **live.artblocks.io/random/`{CONTRACT_ADDRESS}/{PROJECT_INDEX}`** enter any Art Blocks or Engine contract address and a project index you are presented with a random token from that project 29 | 30 | - _Example:_ [Random Chromie Squiggles](https://live.artblocks.io/random/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0) 31 | 32 | ## Random Query Params 33 | 34 | You can add any query params from the customizable display listed below as well as two random specific query params. 35 | 36 | - **reloadClick**: this is to turn on click reloading where if you click the token it will give you a new token from that project. `default: false` 37 | - **reloadDelay**: this is to turn on auto refreshing after the specified time in seconds to give you a new token from that project. `default: none` 38 | 39 | **Example URLs**: 40 | 41 | - [Click turned on](https://live.artblocks.io/random/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0?reloadClick=true) 42 | - [Delay of 30 seconds and click turned on](https://live.artblocks.io/random/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0?reloadClick=true&reloadDelay=30) 43 | - [Delay of 30 seconds with no click](https://live.artblocks.io/random/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a/0?reloadDelay=30) 44 | 45 | ## Contracts 46 | 47 | This is a running list of contract addresses for various Art Blocks and Engine 48 | 49 | **Mainnet**: 50 | 51 | - Artblocks_VO: 0x059edd72cd353df5106d2b9cc5ab83a52287ac3a 52 | - Artblocks_V1: 0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270 53 | - ARTCODE: 0xd10e3dee203579fcee90ed7d0bdd8086f7e53beb 54 | - Doodle Labs: 0x28f2d3805652fb5d359486dffb7d08320d403240 55 | - CryptoCitizens: 0xbdde08bd57e5c9fd563ee7ac61618cb2ecdc0ce0 56 | - Flutter: 0x13aae6f9599880edbb7d144bb13f1212cee99533 57 | - MOMENT: 0x0a1bbd57033f57e7b6743621b79fcb9eb2ce3676 58 | - Plottables: 0xa319c382a702682129fcbf55d514e61a16f97f9c 59 | - TBOA: 0x62e37f664b5945629b6549a87f8e10ed0b6d923b 60 | 61 | ## Customizable Display 62 | 63 | You can create a customizable display for any route on artblocks-viewer. This is done through query params added to the end of the url. In order to activate this ability you must first add `?useCustomViewParams=true` to the end of whatever route you are using. [Here](https://live.artblocks.io/token/0x059edd72cd353df5106d2b9cc5ab83a52287ac3a-71?useCustomViewParams=true) is the most basic customized url of Chromie Squiggle mint #71 with just the squiggle centered in the middle of the page. 64 | 65 | All of the customization that can be done and the default values are as follows: 66 | 67 | - **useCustomViewParams**: this is to specify you are using the custom view display and all other params require this to be true. `default: false` 68 | - **width**: this can be any valid html size and is the width of the token being displayed `default: 90vw` 69 | - **height**: this can be any valid html size and is the height of the token being displayed `default: 90vh` 70 | - **backgroundColor**: this can be any six digit hex color and is the background color of the page `default: ffffff` 71 | - **showText**: this is whether or not to show the text information about the currently displayed token. All other text params depend on this to be true to work `default: false` 72 | - **textColor**: this can be any six digit hex color and is the color of the text `default: 000000` 73 | - **fontSize**: this can be any valid html size and is the size of the text `default: 20px` 74 | - **textBackground**: this can be any six digit hex color and is the background color of the text `default: none` 75 | - **textBottom**: this can be any valid html size and is the distance from the bottom of the screen of the text `default: 3em` 76 | 77 | **Example URLs**: 78 | 79 | - [Latest Chimera](https://live.artblocks.io/0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270/233?useCustomViewParams=true&backgroundColor=F8C8DC&showText=true) 80 | - [Latest Artblocks Mint](https://live.artblocks.io/0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270/?useCustomViewParams=true&backgroundColor=a2beb1&showText=true&textBackground=000000&fontSize=30px&textColor=ffffff&textBottom=1em) 81 | - [Streamlines #414](https://live.artblocks.io/token/0xa319c382a702682129fcbf55d514e61a16f97f9c-414/?useCustomViewParams=true&backgroundColor=671108&showText=true&textColor=bfb3b2&textBottom=0.5em&width=425px&height=550px) 82 | - [Algobots (with text)](https://live.artblocks.io/random/0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270/40?reloadClick=true&useCustomViewParams=true&showText=true&backgroundColor=ffffff&width=100vw&height=100vw&reloadDelay=10) 83 | - [A Plottables project (full screen)](https://live.artblocks.io/random/0xa319c382a702682129fcbf55d514e61a16f97f9c/22?reloadClick=true&useCustomViewParams=true&showText=false&backgroundColor=000000&width=100vw&height=100vw&reloadDelay=10) 84 | -------------------------------------------------------------------------------- /art-blocks-api/index.yml: -------------------------------------------------------------------------------- 1 | order: -100 2 | icon: gear 3 | label: Art Blocks API 4 | expanded: true 5 | route: /creator-docs/art-blocks-api/ -------------------------------------------------------------------------------- /art-blocks-api/queries.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 3 3 | title: Querying and API Overview 4 | 5 | --- 6 | 7 | # Querying 8 | 9 | Below are some sample queries you can use to gather information from the Art Blocks contracts. 10 | 11 | You can build your own queries using a [GraphQL Explorer](https://graphiql-online.com/graphiql) and enter your endpoint to limit the data to exactly what you need. 12 | 13 | ## Subgraph Querying Walkthrough 14 | 15 | The following provides some examples of how to use the Art Blocks subgraph to perform a handful of common queries. 16 | 17 | #### Important Notes 18 | 19 | - Performance/indexing on the hosted subgraph service is oftentimes slower compared to the decentralized subgraph. That being said, the hosted subgraph is free while the decentralized one requires pay-per-query in GRT. 20 | - The Art Blocks subgraphs currently also index any PBAB (Powered by Artblocks) contracts, in addition to the core Art Blocks contracts. Please keep that in mind and make use of the `contract_in` filter to ensure you are working with Art Blocks data only, if that is your intention. 21 | * While querying against the mainnet subgraph if using the `contract_in` filter the Art Blocks contracts to restrict for are `0x059edd72cd353df5106d2b9cc5ab83a52287ac3a` (for the V0 contract that supports projects 0-3) and `0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270` (for the V1 contract that supports projects 4-current). 22 | * The Art Blocks contract to restrict for is `0xda62f67be7194775a75be91cbf9feedcc5776d4b` on testnet. 23 | 24 | # The Basics 25 | 26 | Retrieving a specific Art Blocks project by short ID (no contract): 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 49 | 50 | 51 | 52 | 66 | 67 | 68 | 69 | 83 | 84 | 85 | 86 | 100 | 101 |
Network Contract Type Query
Mainnet Flagship 35 | 36 | ```graphql 37 | { 38 | projects(where: {projectId: "0", contract_in: ["0x059edd72cd353df5106d2b9cc5ab83a52287ac3a","0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270"] 39 | }) { 40 | id 41 | invocations 42 | artistName 43 | name 44 | } 45 | } 46 | ``` 47 | 48 |
Mainnet Engine 53 | 54 | ```graphql 55 | { 56 | projects(where: {projectId: "1", contract_in: ["0x0a1bbd57033f57e7b6743621b79fcb9eb2ce3676"]}) { 57 | id 58 | invocations 59 | artistName 60 | name 61 | } 62 | } 63 | ``` 64 | 65 |
Testnet Flagship 70 | 71 | ```graphql 72 | { 73 | projects(where: {projectId: "100", contract_in: ["0xda62f67be7194775a75be91cbf9feedcc5776d4b"]}) { 74 | id 75 | invocations 76 | artistName 77 | name 78 | } 79 | } 80 | ``` 81 | 82 |
Testnet Engine 87 | 88 | ```graphql 89 | { 90 | projects(where: {projectId: "1", contract_in: ["0x5503a3b96d845f33f135429ab18c03c79477b14f"]}) { 91 | id 92 | invocations 93 | artistName 94 | name 95 | } 96 | } 97 | ``` 98 | 99 |
102 | 103 | Retrieving a specific Art Blocks project by full ID (includes contract): 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 125 | 126 | 127 | 128 | 142 | 143 | 144 | 145 | 159 | 160 | 161 | 162 | 176 | 177 |
Network Contract Type Query
Mainnet Flagship 112 | 113 | ```graphql 114 | { 115 | project(id:"0x059edd72cd353df5106d2b9cc5ab83a52287ac3a-0") { 116 | id 117 | invocations 118 | artistName 119 | name 120 | } 121 | } 122 | ``` 123 | 124 |
Mainnet Engine 129 | 130 | ```graphql 131 | { 132 | project(id:"0x0a1bbd57033f57e7b6743621b79fcb9eb2ce3676-1") { 133 | id 134 | invocations 135 | artistName 136 | name 137 | } 138 | } 139 | ``` 140 | 141 |
Testnet Flagship 146 | 147 | ```graphql 148 | { 149 | project(id:"0xda62f67be7194775a75be91cbf9feedcc5776d4b-100") { 150 | id 151 | invocations 152 | artistName 153 | name 154 | } 155 | } 156 | ``` 157 | 158 |
Testnet Engine 163 | 164 | ```graphql 165 | { 166 | project(id:"0x5503a3b96d845f33f135429ab18c03c79477b14f-1") { 167 | id 168 | invocations 169 | artistName 170 | name 171 | } 172 | } 173 | ``` 174 | 175 |
178 | 179 | --- 180 | 181 |
182 |
183 |
184 | 185 | Retrieving a specific Art Blocks token by short ID (no contract): 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 205 | 206 | 207 | 208 | 211 | 212 | 213 | 214 | 226 | 227 | 228 | 229 | 232 | 233 |
Network Contract Type Query
Mainnet Flagship 194 | 195 | ```graphql 196 | { 197 | tokens(where: {tokenId: "0", contract_in: ["0x059edd72cd353df5106d2b9cc5ab83a52287ac3a", "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270"]}) { 198 | id 199 | tokenId 200 | } 201 | } 202 | ``` 203 | 204 |
Mainnet Engine 209 | Requires full ID (includes contract) 210 |
Testnet Flagship 215 | 216 | ```graphql 217 | { 218 | tokens(where: {tokenId: "10000000", contract_in: ["0xda62f67be7194775a75be91cbf9feedcc5776d4b"]}) { 219 | id 220 | tokenId 221 | } 222 | } 223 | ``` 224 | 225 |
Testnet Engine 230 | Requires full ID (includes contract) 231 |
234 | 235 | --- 236 |
237 |
238 |
239 | 240 | Retrieving a specific Art Blocks token by full ID (includes contract): 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 260 | 261 | 262 | 263 | 275 | 276 | 277 | 278 | 290 | 291 | 292 | 293 | 305 | 306 |
Network Contract Type Query
Mainnet Flagship 249 | 250 | ```graphql 251 | { 252 | token(id: "0x059edd72cd353df5106d2b9cc5ab83a52287ac3a-0") { 253 | id 254 | tokenId 255 | } 256 | } 257 | ``` 258 | 259 |
Mainnet Engine 264 | 265 | ```graphql 266 | { 267 | token(id: "0x0a1bbd57033f57e7b6743621b79fcb9eb2ce3676-1000000") { 268 | id 269 | tokenId 270 | } 271 | } 272 | ``` 273 | 274 |
Testnet Flagship 279 | 280 | ```graphql 281 | { 282 | token(id: "0xda62f67be7194775a75be91cbf9feedcc5776d4b-10000000") { 283 | id 284 | tokenId 285 | } 286 | } 287 | ``` 288 | 289 |
Testnet Engine 294 | 295 | ```graphql 296 | { 297 | token(id: "0x5503a3b96d845f33f135429ab18c03c79477b14f-1000000") { 298 | id 299 | tokenId 300 | } 301 | } 302 | ``` 303 | 304 |
307 | 308 | --- 309 |
310 |
311 |
312 | 313 | # Beyond The Basics 314 | 315 | Retrieve the last 5 most recently created projects across Art Blocks and Powered by Art Blocks (remember that you can use a `contract_in` filter to restrict this to only specific contracts): 316 | 317 | ```graphql 318 | { 319 | projects(first: 5, orderBy: createdAt, orderDirection: desc) { 320 | id 321 | name 322 | artistName 323 | invocations 324 | maxInvocations 325 | } 326 | } 327 | ``` 328 | 329 | Retrieve the top 10 projects across Art Blocks and Powered by Art Blocks, based on # of invocations: 330 | 331 | ```graphql 332 | { 333 | projects(first: 10, orderBy: invocations, orderDirection: desc) { 334 | id 335 | name 336 | artistName 337 | invocations 338 | maxInvocations 339 | } 340 | } 341 | ``` 342 | 343 | Retrieve the most recently minted Art Blocks token: 344 | 345 | ```graphql 346 | { 347 | tokens( 348 | first: 1 349 | orderBy: createdAt 350 | orderDirection: desc 351 | where: { 352 | contract_in: [ 353 | "0x059edd72cd353df5106d2b9cc5ab83a52287ac3a" 354 | "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270" 355 | ] 356 | } 357 | ) { 358 | id 359 | hash 360 | owner { 361 | id 362 | } 363 | project { 364 | name 365 | artistName 366 | } 367 | } 368 | } 369 | ``` 370 | 371 | Retrieve all tokens owned by a specific address, across Art Blocks and Powered by Art Blocks: 372 | 373 | ```graphql 374 | { 375 | tokens(where: { owner: "" }) { 376 | id 377 | } 378 | } 379 | ``` 380 | 381 | Retrieve the general metadata/status for the Art Blocks subgraph (useful for debugging): 382 | 383 | ```graphql 384 | { 385 | _meta { 386 | hasIndexingErrors 387 | block { 388 | number 389 | hash 390 | } 391 | } 392 | } 393 | ``` 394 | 395 | Retrieve the project script for a given project id 396 | 397 | ```graphql 398 | { 399 | project(id: "0x059edd72cd353df5106d2b9cc5ab83a52287ac3a-0") { 400 | script 401 | } 402 | } 403 | ``` 404 | 405 | Pagination should be used for large queries. The Graph enforces upper limits on `first` and `skip` parameters since they generally perform poorly when set to large values (limits as of 01/2022 are `first<=1000` and `skip<=5000`). It is much better to page through entities based on an attribute such as token ID, block number, or some other parameter. For more information, see [The Graph documentation](https://thegraph.com/docs/en/developer/graphql-api/#pagination) 406 | 407 | # Project info 408 | 409 | - Pull all projects and return their name, as well as lots of additional data: 410 | 411 | ```graphql 412 | { 413 | projects( 414 | where: { 415 | contract_in: [ 416 | "0x059edd72cd353df5106d2b9cc5ab83a52287ac3a" 417 | "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270" 418 | ] 419 | } 420 | first: 500 421 | ) { 422 | projectId 423 | name 424 | invocations 425 | artistName 426 | } 427 | } 428 | ``` 429 | 430 | - Get all the wallet owners of a project (Replace PROJECT with the project name you are looking for) 431 | 432 | ```graphql 433 | { 434 | projects(where: { name: "PROJECT" }) { 435 | id 436 | artistAddress 437 | additionalPayee 438 | } 439 | } 440 | ``` 441 | 442 | - If you're looking for the addresses of anyone that owns a mint from a project 443 | 444 | ```graphql 445 | { 446 | projects(where: { name: "PROJECT" }) { 447 | owners { 448 | id 449 | count 450 | } 451 | } 452 | } 453 | ``` 454 | 455 | - Get that txnhash for squiggle 0, you could run the following query on the AB subgraph playground 456 | 457 | ```graphql 458 | { 459 | tokens( 460 | where: { 461 | tokenId: "0" 462 | contract: "0x059edd72cd353df5106d2b9cc5ab83a52287ac3a" 463 | } 464 | ) { 465 | id 466 | tokenId 467 | transactionHash 468 | project { 469 | name 470 | } 471 | } 472 | } 473 | ``` 474 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Embroidery-on-Art-Blocks-Engine.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 450 3 | --- 4 | 5 | # Embroidery on Art Blocks Engine 6 | 7 | In addition to providing a browser-based live view and media files generated from your project script, Art Blocks Engine provides tools to embroider your generative artwork on garments and accessories. 8 | 9 | ## Requirements 10 | 11 | In order to get started, you will need: 12 | 13 | - [ ] Testnet project shell on Art Blocks Engine 14 | Refer to [documentation](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/engine-project-launch/) for setup instructions* 15 | - [ ] Embroidery machine and software drivers compatible with DST or PES files 16 | *If you are new to embroidery, we recommend the [Brother PE800](https://www.amazon.com/dp/B07C7HNX92?tag=thesprucecrafts-onsite-prod-20&linkCode=ogi&th=1&ascsubtag=4171238%7Cne17ef55f56ef441eb2184399ae4d1dd615%7CB07C7HNX92)* 17 | - [ ] JavaScript utilities for manipulating SVG markup 18 | *Clone the embroidery template repository for an example: ‣* 19 | 20 | ## Quick Start 21 | 22 | 1. [Deploy a new project shell](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/engine-project-launch/) to your Art Blocks Engine testnet contract 23 | 2. Upload a project script that includes a global function named `generateEmbroiderySVG` that returns a string containing SVG markup for embroidery 24 | 3. Use the [Embroidery File Downloader](https://minting-api.artblocks.io/embroidery/downloader) to generate embroidery files for minted tokens 25 | 26 | # Project Script Requirements 27 | 28 | In addition to following the typical [guidelines and constraints](https://docs.artblocks.io/creator-docs/creator-onboarding/readme/#guidelines-and-constraints) for Art Blocks projects, your project script should include a global function that is only used for embroidery. 29 | 30 | ## Generating SVG for Embroidery 31 | 32 | Implement a global function with the following type signature: 33 | 34 | ```tsx 35 | function generateEmbroiderySVG(width: number, height: number): string 36 | ``` 37 | 38 | For example, you may include a function similar to code below: 39 | 40 | ```jsx 41 | window.generateEmbroiderySVG = function(width, height) { 42 | let svg = document.createElementNS("http://www.w3.org/2000/svg", "svg"), 43 | path = document.createElementNS("http://www.w3.org/2000/svg", "path"), 44 | strokeColor = "#" + tokenData.hash.substring(2, 8), 45 | svgWidth = width > height ? 24.0 * width / height : 24.0, 46 | svgHeight = height > width ? 24.0 * height / width : 24.0; 47 | 48 | // the embroidery machine only follows stroked paths and ignores fills 49 | svg.setAttribute("fill", "none"); 50 | 51 | // the SVG viewbox should be configured with garment dimensions 52 | svg.setAttribute("viewBox", `0 0 ${svgWidth} ${svgHeight}`); 53 | 54 | // the color needs to be matched with an appropriate spool of thread loaded in the embroidery machine 55 | svg.setAttribute("stroke", strokeColor); 56 | 57 | // typically, the SVG path is generated with code - this hard-coded path is only a simple example 58 | path.setAttribute( 59 | "d", 60 | "M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1", 61 | ); 62 | 63 | // stroke line attributes are ignored by embroidery machines, but can make a design more appealing when viewed digitally 64 | path.setAttribute("stroke-linecap", "round"); 65 | path.setAttribute("stroke-linejoin", "round"); 66 | 67 | // stroke width is ignored by the embroidery machine, but relevant for human viewers 68 | path.setAttribute("stroke-width", "2"); 69 | 70 | svg.appendChild(e); 71 | 72 | // when viewed digitally, the SVG will scale to fill the viewport (ignored by embroidery machine) 73 | svg.setAttribute("height", "100vh"); 74 | svg.setAttribute("width", "100vw"); 75 | 76 | // the function should return the SVG markup as a string 77 | return svg.outerHTML; 78 | } 79 | ``` 80 | 81 | ## Functional Requirements 82 | 83 | In order to correctly generate files for embroidery, you must: 84 | 85 | - [ ] Implement a `generateEmbroiderySVG` global function that returns the full markup of an `` element as a string 86 | - [ ] *Optional:* accept a `width` and `height` parameter (millimeters) used to resize the contents of the SVG to accommodate different garment sizes 87 | - [ ] Render a digital-only version of the art using a separate `` or `` that is displayed to the user and thumbnailed in token metadata (similar to any digital-only Art Blocks project) 88 | - [ ] Inline all libraries and code used in your project that are not configured as an on-chain dependency 89 | 90 | ## Known Limitations 91 | 92 | - [ ] Avoid using SVG fills - instead, to create the visual appearance of a fill, the SVG should contain the exact paths the embroidery needle should follow 93 | - [ ] Avoid using asynchronous code or promises inside of the `generateEmbroiderySVG` function - the function should return valid SVG markup immediately 94 | - [ ] Provide margins (bleed) matching the precision of the embroidery machine to improve manufacturing yield 95 | - [ ] Match all colors used in your design to the colors of thread available to you for embroidering 96 | 97 | # Embroidery in Production 98 | 99 | In addition to the typical steps required for moving an Art Blocks Engine project to mainnet, there are additional considerations for embroidery projects. 100 | 101 | ## Logistics and Fulfillment 102 | 103 | There are three primary customer experiences enabled for embroidery on Art Blocks Engine: 104 | 105 | 1. **Drop-shipped or batched production** 106 | *Consider the lead times, available materials, and the process for sending files to embroidery service providers.* 107 | 2. **Live in-person pop-up events** 108 | *Consider space constraints and measure the amount of time required to fulfill a single embroidered object.* 109 | 3. **At-home embroidery for token holders** 110 | *Consider how and when you would like to provide your users with a link to download embroidery files for a project.* 111 | 112 | ## Option 1: Batched Production 113 | 114 | To facilitate automated testing and batched production, we provide a rate-limited API for converting Art Blocks Engine projects into DST and PES embroidery files. **Note:** the API endpoints provided for batched production are rate-limited, and cannot be linked from a public web site. 115 | 116 | For example, the following commands illustrate how you can download individual embroidery files for tokens on an Art Blocks Engine project: 117 | 118 | ```bash 119 | #!/bin/bash 120 | 121 | # Example of a Goerli test script DST file 122 | curl -O -J 'https://minting-api.artblocks.io/embroidery/goerli/0x81236b5A105d3ad6B56aC41a03E1Fd8893A08859/3000000.dst' 123 | 124 | # Example of a Goerli test script PES file 125 | curl -O -J 'https://minting-api.artblocks.io/embroidery/goerli/0x81236b5A105d3ad6B56aC41a03E1Fd8893A08859/3000000.pes?width_mm=400&height_mm=400' 126 | 127 | # Example using the Plottables goerli contract (currently does not work because the token isn't embroiderable) 128 | curl -O -J 'https://minting-api.artblocks.io/embroidery/goerli/0x9B0c67496Be8c6422fED0372be7a87707e3a6F09/4000003.dst?width_mm=400&height_mm=400' 129 | 130 | # Example using the Plottables mainnet contract (currently does not work because the token isn't embroiderable) 131 | curl -O -J 'https://minting-api.artblocks.io/embroidery/mainnet/0xa319C382a702682129fcbF55d514E61a16f97f9c/2000001.dst?width_mm=400&height_mm=400' 132 | ``` 133 | 134 | ## Option 2: Live Events 135 | 136 | To facilitate live events, operators of a pop-up booth can use the Embroidery File Downloader on a laptop or iPad to quickly download the relevant embroidery files for a given minted token. 137 | 138 | [Embroidery File Downloader](https://minting-api.artblocks.io/embroidery/downloader) 139 | 140 | ## Option 3: Home Embroidery 141 | 142 | If you would like to provide your token holders with a link to download DST or PES files of their minted tokens, please contact us for access to the API dashboard. To generate embroidery files in an S3 bucket that may be linked from a public web site, you will need to add your project in the API dashboard here: [https://minting-api.artblocks.io/admin/embroidery/embroideryproject/](https://minting-api.artblocks.io/admin/embroidery/embroideryproject/) 143 | 144 | # References 145 | 146 | - [https://github.com/embroidepy/vpype-embroidery/](https://github.com/embroidepy/vpype-embroidery/) 147 | - [https://github.com/EmbroidePy/pyembroidery](https://github.com/EmbroidePy/pyembroidery) 148 | - [10 Best Print on Demand Companies and Sites (2023)](https://www.shopify.com/blog/print-on-demand-companies) 149 | - [The 7 Best Embroidery Machines of 2023](https://www.thesprucecrafts.com/best-embroidery-machines-4171238) 150 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Engine-opensea-setup.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 500 3 | --- 4 | # Art Blocks Engine OpenSea Setup 5 | 6 | Setting up the OpenSea storefront for your Art Blocks Engine contract. 7 | 8 | ## OpenSea Storefront Ownership Transfer 9 | 10 | After the first token has been minted on your new Art Blocks Engine contract, you should be able to see this token in the OpenSea storefront. You will find this in the format `https://opensea.io/assets/{CONTRACT_ADDRESS}/{TOKEN_ID}` e.g. https://opensea.io/assets/0x13aae6f9599880edbb7d144bb13f1212cee99533/1000167. 11 | 12 | Once this first token is populated, the Art Blocks team will be able to transfer the OpenSea collection for your project to a wallet that you control. By default, the Art Blocks team will plan to use the same address for the OpenSea collection ownership as it is designated to be the admin of your smart contract. However, if you prefer that a different wallet address manages the OpenSea collection, please reach out to Art Blocks to request this **before** the project has been transferred to your team. 13 | 14 | After your OpenSea collection has your designated wallet added as the collection administrator, you may remove the wallet that Art Blocks controls from being an additional admin. It’s added automatically at the time of collection creation based on the contract deployer wallet address at the time of collection creation. **We recommend that you do so. That way, only you control your OpenSea storefront.** 15 | 16 | Please contact the Art Blocks and/or OpenSea teams if you have any issues during this process. 17 | 18 | 19 | ## OpenSea Storefront Options 20 | 21 | For Art Blocks Engine projects, there are two options that OpenSea can provide for collection organization: 22 | 23 | 1\. All projects are grouped in one large collection, where individual projects within a collection are shown as filter traits on the sidebar of the OpenSea UI. 24 | 25 | ![All projects in one collection.](/static/screenshot1.png) 26 | 27 | 2\. Each new project on your contract is handled as its own collection on OpenSea, where project traits are properties. 28 | 29 | ![Each project as its own collection.](/static/screenshot2.png) 30 | 31 | By default, collections are organized via method 1. above. However, if you would like your collection to be handled via method 2., please reach out to the Art Blocks team, and we can facilitate this change by OpenSea on your behalf. 32 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Engine-partner-onboarding-steps.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 900 3 | --- 4 | # Engine Partner Onboarding Steps 5 | 6 | An overview of the steps required to onboard as an Art Blocks Engine partner. 7 | 8 | ## 1. Initial outreach 9 | 10 | Interested in using Art Blocks Engine to launch a generative content platform? 11 | 12 | Reach out to **info@artblocks.io** to get started. We'll discuss your needs, explain what we offer in a partnership, and align expectations. 13 | 14 | [!badge Timeline: typically 1-2 weeks] 15 | 16 | ## 2. Project scope 17 | 18 | The Art Blocks team will work with you to determine the scope of the Art Blocks Engine project. 19 | 20 | [!badge Timeline: 1-2 weeks] 21 | 22 | ## 3. Contract agreement 23 | 24 | Once the project objectives and scope are agreed upon, you'll work with our operations team to sign our partnership agreement. 25 | 26 | [!badge Timeline: 1 week] 27 | 28 | ## 4. Smart contract details 29 | 30 | To get started, you'll provide our team with: 31 | 32 | - An Ethereum wallet address (that you currently own and control) you'll use to manage your Art Blocks Engine smart contracts 33 | - The name you’ll use for tokens from your contract (e.g., for Art Blocks, it is "Art Blocks") 34 | - The ticker symbol you’ll use for tokens from your contract (e.g., for Art Blocks, it is "BLOCKS") 35 | - Deployment Type: V3 Engine or V3 Engine Flex 36 | - [Minter Type](https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/MINTER_SUITE.md#minter-suite-documentation): flat price eth only, set price custom erc20, merkle tree allowlist, holder-gated, linear DA, exponential DA, and exponential DA with settlement 37 | - Starting project ID # (>=0): 38 | - Set autoApproveArtistSplitProposals: true or false 39 | 40 | Regarding "autoApproveArtistSplitProposals" - It needs to be set at deployment and cannot be changed later. 41 | 42 | tldr - if true, artist royalty wallet changes are auto-approved. If false, the contract admin will need to approve the artist's royalty wallet changes. This is an added check to ensure your artists aren't changing royalty wallets to a random address, which could complicate accounting/ OFAC compliance. 43 | 44 | Note: We cannot deploy your contract until you provide the above information. **The name and symbol tied to your contract cannot change once it’s deployed.**_ 45 | 46 | [!badge Timeline: 1-2 days] 47 | 48 | ## 5. Contract configuration & testnet deployment 49 | 50 | We will configure your smart contract before transferring ownership to Ethereum address provided in Step 4. Once we deploy your contract on the test network, you can start testing your generative script. 51 | 52 | [!badge Timeline: 1 week] 53 | 54 | ## 6. Testnet infrastructure integration 55 | 56 | Art Blocks will integrate your contracts with our rendering infrastructure and provide access to our staging website for you to perform project onboarding and configuration via the Art Blocks site on the test network. 57 | 58 | Contracts are deployed twice per month and typically take 1 week to complete and transfer. 59 | 60 | [!badge Timeline: 1 week] 61 | 62 | ## 7. Integration with partner’s site 63 | 64 | Your team will integrate your site’s front-end with the contract created by Art Blocks to test your outputs on the testnet. 65 | 66 | [!badge Timeline: weeks-months (depends on partner)] 67 | - [x] Connect your front end to testnet contracts 68 | 69 | ## 8. Test mints on partner site 70 | 71 | Your team ensures the minting process is working on the test network by minting your NFTs using the front-end of your site. 72 | 73 | [!badge Timeline: weeks-months (depends on partner)] 74 | - [x] Mint test outputs 75 | - [x] Test drop mechanic (flat price, Dutch Auction, whitelists, etc.) 76 | - [x] Test purchase with custom ERC20 (if applicable) 77 | - [x] Request a script audit from Art Blocks 78 | - [x] Test your script across different hardware/software ([browserstack.com](https://www.browserstack.com/)) 79 | - [x] Let the Art Blocks team know testing is complete and you're ready for a mainnet deployment 80 | 81 | ## 9. Deployment to mainnet 82 | 83 | Art Blocks deploys the mainnet version of your contract and integrates it with our infrastructure. 84 | 85 | [!badge Timeline: 2 weeks] 86 | 87 | ## 10. Infrastructure integration (mainnet) 88 | 89 | Your team integrates the mainnet contract with your site and prepares to generate your first NFT (mint #0) 90 | 91 | [!badge Timeline: Depends on partner] 92 | - [x] Connect your front end with the *new* mainnet contracts, using the same minting mechanics from testnet (drop type & currency) 93 | - [x] Mint #0 from your front end 94 | 95 | 96 | ## 11. Mint #0 97 | 98 | You can mint your project's first official token via your site! 99 | 100 | ## 12. Set secondary royalties 101 | 102 | Art Blocks will set *our* secondary royalty before we transfer contract ownership, but you are responsible for setting your own secondary royalty across all secondary marketplaces. 103 | 104 | OpenSea - https://docs.opensea.io/docs/10-setting-fees-on-secondary-sales 105 | LooksRare - https://docs.looksrare.org/guides/collection-management/set-or-edit-collection-royalties 106 | x2y2 - https://docs.x2y2.io/guides/collection-management/manage-your-collection 107 | 108 | Note: The vast majority of secondary activity takes place on OpenSea. Currently, OpenSea does not recognize on-chain royalties and needs to be set through their interface. However, they plan to recognize [Roylaty Registry](https://royaltyregistry.xyz/lookup) in the near-ish future. We highly encourage you to sign up for the Royalty Registry to avoid missed secondary royalties. 109 | 110 | Instructions on setting up Royalty Registry - https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/engine-royalty-registry-setup/ 111 | 112 | 113 | ## 13. Project launch 114 | 115 | You can choose a launch date for your project. Please allow at least one week between a successful mint #0 and a go-live date. 116 | 117 | [!badge Timeline: 1 week from completion of step 11] 118 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Engine-project-launch.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 800 3 | --- 4 | 5 | # Engine Project Deployment and Launch Guide 6 | 7 | This guide provides basic instructions for deploying and launching a new project on the V2 and V3 Engine smart contracts. You will learn how to create a project shell, assign a minter to each project, and setup the necessary configurations before minting and launching your project. This documentation aims to simplify the process and ensure a smooth project launch on the Art Blocks Engine platform. 8 | 9 | There are slight variations between V2 and V3 contracts, which will be noted in the relevant sections. 10 | 11 | ## Project Shell Deployment 12 | 13 | [!embed](https://www.loom.com/embed/9cb61eef17724107a6e7916d682c8bd5) 14 | 15 | 1. Collect the required information for the project: 16 | - Project title (e.g., "Fun Lines") 17 | - Artist's wallet address (e.g., 0x78592a6fBE68fEBf226040a5D25ad7e69F2FeAb6) 18 | - (V2 only) Price-per-mint specified in WEI (e.g., 350000000000000000, or 0.35 ETH) 19 | 2. Navigate to your Engine Core Contract on Etherscan and connect your wallet. You can find this link in your `DEPLOYMENTS.md` log. [https://goerli.etherscan.io/address/0xd2363Acbf8CdF01A5FdfcB8f0295e0a5dF94518D#code](https://goerli.etherscan.io/address/0xd2363Acbf8CdF01A5FdfcB8f0295e0a5dF94518D#code)) 20 | 3. Click the "Write contract" tab and use the `addProject` method to create a new project shell, specifying the information collected in step 1. 21 | 4. Connect to the Art Blocks website with the artist wallet used in Step 3. Your artist should be able to begin entering project details. 22 | 23 | Testnet URL: `https://artist-staging.artblocks.io/engine/[flex OR fullyonchain]/projects/[coreContractAddress]/[projectID]` 24 | example: https://artist-staging.artblocks.io/engine/flex/projects/0x28b82AA5bb6d00363ae0FBC5ecaD689Ae49BC82B/0 25 | 26 | Mainnet URL: `https://www.artblocks.io/engine/[flex OR fullyonchain]/projects/[coreContractAddress]/[projectID]` 27 | example: https://www.artblocks.io/engine/fullyonchain/projects/0xa319C382a702682129fcbF55d514E61a16f97f9c/1 28 | 29 | 5. If you encounter issues finding or seeing your project on the Art Blocks site, disconnect and reconnect your wallet, ensuring you are connected with the previously specified artist wallet. 30 | 31 | ## Assigning a Minter (V3 only, New Shared Minter Suite) 32 | 33 | Minters are assigned on a per-project basis on V3 contracts, and minters must be assigned by the **artist's wallet**. 34 | 35 | > note: for legacy minter suite directions, see the next section 36 | 37 | !!!info 38 | Art Blocks is working on a new creator dashboard that will more easily facilitate the minter assignment process. This will only be possible using the new shared minter suite, because those minters are indexed by the subgraph. Until the new creator dashboard is released, please follow these instructions to assign a minter to your project. 39 | !!! 40 | 41 | 1. Assign the minter to your project by using the `MinterFilterV2` contract found in your deployment file. The artist's wallet should use function #9 `setMinterForProject`, entering the `_projectID`, `_coreContract` address, and `_minter` address. You can get the globally approved minter addresses via the `getAllGloballyApprovedMinters()` view function on the `MinterFilterV2` contract. 42 | 43 | 2. Once the minter is linked to your project, set the project details on the minter contract. 44 | 45 | For example, if you are using a shared Dutch Auction minter, navigate to the contract on Etherscan. Then, use the function `setAuctionDetails` to enter details like `_projectId`, `_coreContract`, `_auctionTimestampStart`, `_priceDecayHalfLifeSeconds`, `_startPrice`, and `_basePrice`. This must be done using the artist's wallet. 46 | 47 | ## Assigning a Minter (V3 only, Legacy Non-Shared Minter Suite) 48 | 49 | !!!info 50 | We recommend using the new shared minter suite, which is easier to use and more flexible. If you are using the legacy non-shared minter suite, follow these instructions. For more information about migrating to the new shared minter suite, please see the [Minter Suite Migration Runbook](minter-suite-migration-runbook.md). 51 | !!! 52 | 53 | [!embed](https://www.loom.com/share/66f542b3ef024f7c80059115e76bae8d) 54 | 55 | Minters are assigned on a per-project basis on V3 contracts, and minters must be assigned by the **artist's wallet**. For the artist wallet to assign a minter, follow these steps: 56 | 57 | 1. Assign the minter to your project by using the `MinterFilterV1` contract found in your deployment file. The artist's wallet should use function #6 `setMinterForProject`, entering the `_projectID` and `_minterAddress`. You can find the minter address in your deployment log, which is pinned in your partner channel. 58 | 2. Once the minter is linked to your project, set the project details on the minter contract. The deployed minter addresses can be found in your deployment file. 59 | 60 | For example, if Art Blocks deployed a Dutch Auction minter for your core contract, navigate to the `MinterDAExpV4` contract on Etherscan (in your `DEPLOYMENT.md` log). Then, use the function `setAuctionDetails` to enter details like `_projectId`, `_auctionTimestampStart`, `_priceDecayHalfLifeSeconds`, `_startPrice`, and `_basePrice`. Make sure this is done using the artist's wallet. 61 | 62 | ## Pre-mint-#0 Flight Check 63 | 64 | Before minting your first token (#0) on your new project shell, verify the following: 65 | 66 | 1. The baseTokenURI has been set, following the format: 67 | 68 | - Mainnet: http://token.artblocks.io/{CORE_CONTRACT_ADDRESS}/ 69 | - Testnet: https://token.staging.artblocks.io/{CONTRACT_ADDRESS}/ 70 | 71 | 2. The max invocations for the project have been set. (note: project size **cannot** be increased once set on V3 contracts) 72 | 3. Mint through your own front end. On testnet, you'll want to test each minter type and currency you plan to use on mainnet. 73 | 74 | ## Pre-launch (pre-open-minting) Flight Check 75 | 76 | For a project to be available for public purchase, the project must be activated by the admin, and unpaused by the artist. 77 | 78 | tldr: 79 | inactive + paused (default state) = private project shell and unable to purchase 80 | active + paused = public project shell and **_only_** the artist wallet can purchase 81 | active + unpaused = open to purchase 82 | 83 | Before launching your project for open minting, verify the following: 84 | 85 | 1. The project has been activated by the contract admin. 86 | 2. The project is not yet unpaused. 87 | 88 | Once unpaused the project will be open, depending on the minter being used (DA will not open until specified `startTime`) 89 | 90 | [!embed](https://www.loom.com/share/65a8e19513944d3c9a39952696c11f43) 91 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Engine-royalty-registry-setup-(V2-only).md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 500 3 | --- 4 | 5 | # Art Blocks Engine Royalty Registry Setup (V2 contracts only) 6 | 7 | ## Royalty Registry 8 | 9 | The [Royalty Registry](https://royaltyregistry.xyz/lookup) is an on-chain tool used by many marketplaces ((soon) OpenSea, Coinbase NFT, etc.) to query royalty payment addresses and percentages when a token is sold. The Royalty Registry lives on the Ethereum blockchain and is decentralized. 10 | 11 | !!!danger 12 | Art Blocks Engine contracts integrate with the Royalty Registry directly to handle many projects and artists on a single contract. Please do not use the [Royalty Registry's "Configure" UI](https://royaltyregistry.xyz/configure) to configure the royalties for your Engine contracts. Doing so will result in incorrect royalty payments across many projects. Instead, see the documentation below. 13 | !!! 14 | 15 | !!!info 16 | Note that the [Royalty Registry's "Lookup" UI](https://royaltyregistry.xyz/lookup) is a great tool for confirming that your Engine contracts are configured correctly after the configuration steps below have been completed. 17 | !!! 18 | 19 | ## Royalty Payment Addresses 20 | 21 | For Engine contracts, the following addresses may receive royalties: 22 | 23 | | Party | Typical Royalty Percentage | 24 | | ---------------------------- | -------------------------------------------------------------- | 25 | | Platform (Engine Partner) | default 2.5% | 26 | | Render Provider (Art Blocks) | default 2.5% | 27 | | Artist | typically 5%, but configurable by artist | 28 | | Additional Payee | split between Artist & Additional Payee varies across projects | 29 | 30 | ## Configuring Royalties 31 | 32 | V3 and V2 Engine contracts are configured differently. V3 Engine contracts are the latest version of the Art Blocks Engine contracts. Since they were designed after the Royalty Registry was released, they automatically integrate with the Royalty Registry. V2 Engine contracts also integrate with the Royalty Registry, but have a shim-layer that must also be configured. This is because V2 Engine contracts were designed before the Royalty Registry was released. 33 | 34 | ## Configuring V3 Engine Contracts 35 | 36 | Simply configure the relevant royalty payment details on the token contract itself: 37 | 38 | **admin (contract-wide):** 39 | 40 | - Ensuring platform and render provider payment addresses are correct, updateable by contract admin by calling `updateProviderSalesAddresses` on the Engine core contract 41 | - Ensuring platform and render provider payment percentages are correct, updateable by contract admin by calling `updateProviderSecondarySalesBPS` on the Engine core contract 42 | 43 | **artist (project-specific):** 44 | 45 | - Ensuring the project's artist royalty percentage is correct, updateable on the website by the artist in their project dashboard. 46 | - Ensuring the project's artist and additional payee splits are correct, updateable on the website by the artist in their project dashboard. 47 | 48 | ## Configuring V2 Engine Contracts 49 | 50 | ### Required V2 Setup 51 | 52 | The following steps are required before Art Blocks Engine contracts will integrate properly with the Royalty Registry. 53 | 54 | **A. Pre-setup:** 55 | 56 | - Ensure every project has the desired artist royalty percentage set on the Engine contract. 57 | - IMPORTANT: This percentage represents the percentage of the total token sale that will be paid to a combination of artist & additional payee. It is typically 5%. Additionally, the default 2.5% to the Engine platform (you) and 2.5% to render provider (Art Blocks) will be also added by the Royalty Registry override contracts below. 58 | - **Only artists** may update their project's royalty percentage. They can call `updateProjectSecondaryMarketRoyaltyPercentage(<_projectId>, <_royaltyPercentage>)` on the Engine contract from their artist wallet. Typically royalty percentage would be the number 5, representing 5%. 59 | > **Note:** This percentage is different than what OpenSea has asked us to do with their off-chain royalty system. In the old system, typically 5%+2.5%+2.5%=10% was set on OpenSea's website because they only supported bulk payments to a single address. In the new on-chain system, payments to more than a single address will be supported. 60 | 61 | **B. Royalty Registry Integration:** 62 | 63 | 1. Create a new override on the Royalty Registry for your Engine core contract 64 | - View the Royalty Registry's mainnet registry contract on etherscan: [https://etherscan.io/address/0xad2184fb5dbcfc05d8f056542fb25b04fa32a95d#writeProxyContract](https://etherscan.io/address/0xad2184fb5dbcfc05d8f056542fb25b04fa32a95d#writeProxyContract) 65 | - Using the `Connect to Web3` button, connect your Engine `admin` wallet to etherscan when on the "Write as Proxy" tab. 66 | - Call the `setRoyaltyLookupAddress` function with the following arguments: 67 | - `tokenAddress`: The address of your Engine core contract 68 | - `royaltyLookupAddress`: The address of the standard Art Blocks Engine Royalty Registry override contract, [0x31E1cC72E6f9E27C2ECbB500d978de1691173F5f](https://etherscan.io/address/0x31e1cc72e6f9e27c2ecbb500d978de1691173f5f#code) 69 | 2. Set your Platform royalty payment address 70 | - Connect your Engine `admin` wallet to the Art Blocks Engine royalty override contract, [0x31E1cC72E6f9E27C2ECbB500d978de1691173F5f](https://etherscan.io/address/0x31e1cc72e6f9e27c2ecbb500d978de1691173f5f#writeContract), on etherscan 71 | - Call the `updatePlatformRoyaltyAddressForContract` function with your Engine token contract address as `_tokenContract`, and your desired platform royalty payment address as `_platformRoyaltyAddress` 72 | 73 | Now you will automatically be receiving royalties from sales on secondary markets that support use of the Royalty Registry! 74 | 75 | ### Optional V2 Configuring 76 | 77 | Royalty percentages of 2.5% are used by default by the Art Blocks Engine royalty override contract. The `admin` of any given Engine core contract can override these percentages by calling `updatePlatformBpsForContract` or `updateRenderProviderBpsForContract` on the Art Blocks Engine royalty override contract, [0x31E1cC72E6f9E27C2ECbB500d978de1691173F5f](https://etherscan.io/address/0x31e1cc72e6f9e27c2ecbb500d978de1691173f5f#writeContract), on etherscan 78 | 79 | > Note that royalty proportions are defined in terms of Basis points. For example, 250 BPS = 2.5% royalty. See [this article](https://www.investopedia.com/terms/b/basispoint.asp) for more information. 80 | 81 | After initial setup, the Platform (Engine partner) royalty payment address may be updated at any time by the `admin` of a given Engine core contract by calling the `updatePlatformRoyaltyAddressForContract` function on the Art Blocks Engine royalty override contract, [0x31E1cC72E6f9E27C2ECbB500d978de1691173F5f](https://etherscan.io/address/0x31e1cc72e6f9e27c2ecbb500d978de1691173f5f#writeContract), on etherscan 82 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Engine-technical-details.md: -------------------------------------------------------------------------------- 1 | # Art Blocks Engine Flex Technical Details 2 | 3 | This page goes deeper into some technical considerations when working with the most current version of Artblocks Engine Flex. 4 | The latest version of the Engine Flex contract (v3) and interface can be found here: 5 | - https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/contracts/engine/V3/GenArt721CoreV3_Engine_Flex.sol 6 | - https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/contracts/interfaces/0.8.x/IGenArt721CoreContractV3_Engine_Flex.sol 7 | 8 | ## Introduction To External Asset Dependencies 9 | 10 | ```solidity 11 | struct ExternalAssetDependency { 12 | string cid; 13 | ExternalAssetDependencyType dependencyType; 14 | address bytecodeAddress; 15 | } 16 | ``` 17 | 18 | The Engine Flex contract introduces the concept of external asset dependencies. These essentially function as on-chain pointers to off-chain assets stored using decentralized storage technologies and, with the latest version of flex, also supports fully on-chain data storage. An external asset dependency is comprised of its content identifier (CID), if it's using Arweave or IPFS, a bytecodeAddress if it's specifically dealing with fully on-chain data, and a dependencyType, which maps to an Engine Flex supported platform. 19 | 20 | Engine Flex currently supports adding external asset dependencies of the following types: 21 | - IPFS 22 | - Arweave 23 | - Onchain (data lives entirely on the blockchain) 24 | 25 | ## Adding, Updating & Removing External Asset Dependencies 26 | 27 | When working with and manipulating a project's external asset dependencies, you'll be relying on the following functions: 28 | 29 | ```solidity 30 | function addProjectExternalAssetDependency(uint256 _projectId, string memory _cidOrData, ExternalAssetDependencyType _dependencyType) 31 | function updateProjectExternalAssetDependency(uint256 _projectId, uint256 _index, string memory _cidOrData, ExternalAssetDependencyType _dependencyType) 32 | function removeProjectExternalAssetDependency(uint256 _projectId, uint256 _index) 33 | ``` 34 | Note the parameter `_cidOrData`, which allows you to either pass in a CID if you are working with the IPFS/Arweave dependencyTypes or a data string if you are working with the onchain dependencyType. 35 | 36 | For convenience and utility, the contract also provides the following function, allowing you to easily grab a project's external asset dependency at a specific index: 37 | ```solidity 38 | function projectExternalAssetDependencyByIndex(uint256 _projectId, uint256 _index) 39 | ``` 40 | This convenience function returns data in the form of the following format: 41 | ```solidity 42 | /** 43 | * @notice An external asset dependency with data. This is a convenience struct that contains the CID of the dependency, 44 | * the type of the dependency, the address of the bytecode for this dependency, and the data retrieved from this bytecode address. 45 | */ 46 | struct ExternalAssetDependencyWithData { 47 | string cid; 48 | ExternalAssetDependencyType dependencyType; 49 | address bytecodeAddress; 50 | string data; 51 | } 52 | ``` 53 | Note that for dependencyTypes other than onchain (IPFS, Arweave), the returned bytecodeAddress will be the zero address and data will be an empty string. Conversely, if the dependencyType is onchain, the returned cid will be an empty string. 54 | 55 | Some important factors to keep in mind with the above functions: 56 | - Only allowlisted/artist addresses can call these. 57 | - `ExternalAssetDependencyType _dependencyType` is a solidity enum, which can be passed into these functions as a uint8. This enum only defines three options as of now, `IPFS`,`ARWEAVE`, and `ONCHAIN`, which can be represented as `0`,`1`, and `2` respectively. 58 | 59 | ### Note On Removing External Asset Dependencies 60 | 61 | In the interest of saving gas, the `removeProjectExternalAssetDependency()` function is implemented in such a way that it does not preserve the order of the project's external asset dependency mapping. Specifically, the way this removal logic works is as follows: when an index to remove is passed in, the element at that index being removed is swapped with the element at the last index of the list of assets. Now that the last index holds the element to be removed, that element is removed off the list. This method, in addition to being more gas efficient, also ensures that our list/mapping does not have any "holes". The tradeoff, however, is that the removal causes the order of the external asset dependencies in this list to change, albeit in a deterministic manner: the element at the last index always moves to the removed index. This is important to keep in mind when writing your project script, though you can always update the ordering manually as you see fit by utilizing the `updateProjectExternalAssetDependency()` function. 62 | 63 | You can view directly the full implementation of this removal function here: https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/contracts/engine/V3/GenArt721CoreV3_Engine_Flex.sol#L524 64 | 65 | ## Preferred Gateways 66 | 67 | ```solidity 68 | string public preferredIPFSGateway; 69 | string public preferredArweaveGateway; 70 | ``` 71 | 72 | The Engine Flex contract allows you to specify preferred gateways for the currently supported dependency types (IPFS & Arweave). Gateways are accessible HTTP interfaces and, when combined with an asset CID, expose urls for assets being stored on these off-chain decentralized platforms. These preferred gateways are updateable with a string param via the following functions: `updateArweaveGateway()` & `updateIPFSGateway()`. 73 | 74 | Please note that these preferred gateways are set per-contract, not per-project. 75 | 76 | ## Working With External Asset Dependencies In Your Project Script 77 | 78 | When you request the live view for a given token of a project, the `hash` and `tokenId` of the token are provided in the `tokenData` object and the Art Blocks Generator injects this into the served HTML live view. This `tokenData` object has now been extended with the following external asset dependency related data, if it is available: 79 | 80 | ```js 81 | let tokenData = { 82 | hash: "", 83 | tokenId:"", 84 | externalAssetDependencies: [ 85 | { 86 | cid: "", 87 | dependencyType: "", 88 | data: "" 89 | }, 90 | ... 91 | ], 92 | preferredIPFSGateway:"", 93 | preferredArweaveGateway: "" 94 | } 95 | ``` 96 | 97 | Your project script can then easily make use of these dependencies by combining the CID of the asset with the appropriate gateway, if you are dealing with IPFS/Arweave dependencies. As a simple example: If you have an external asset dependency with a CID `QmXxgX5Qyhqz1t9wDFkvJtjVKYe1f8Uj714RV2n1LS76Pg` and a dependencyType of `IPFS`, you can construct the full url of your external asset dependency by combining the `preferredIPFSGateway`, which let's assume is `https://ipfs.io/ipfs/`, with the asset CID. This gives you the full url of the asset, `https://ipfs.io/ipfs/QmXxgX5Qyhqz1t9wDFkvJtjVKYe1f8Uj714RV2n1LS76Pg`, and allows your project script to download it with `fetch` and use it as it sees fit. For fully onchain external asset dependencies, the full data string that is stored on the blockchain will be injected. 98 | 99 | Note that for IPFS/Arweave external asset dependencies if your CID is pointing to a directory of assets, rather than a single asset, your project script will need to be aware of the file naming structure of this directory to fetch the assets individually. Using the previous example, imagine that CID `QmXxgX5Qyhqz1t9wDFkvJtjVKYe1f8Uj714RV2n1LS76Pg` was pointing to a directory of 10 PNG images, with filenames corresponding to the numbers 1-10. Your project script would generate the same full url with the information provided, `https://ipfs.io/ipfs/QmXxgX5Qyhqz1t9wDFkvJtjVKYe1f8Uj714RV2n1LS76Pg`, but also append the specific file you want to fetch by being aware of the naming conventions, ie `https://ipfs.io/ipfs/QmXxgX5Qyhqz1t9wDFkvJtjVKYe1f8Uj714RV2n1LS76Pg/1.png`. 100 | 101 | ## Leveraging the Art Blocks Dependency Registry 102 | 103 | If you want to include additional libraries (e.g., Tone.js) supported by the Art Blocks Dependency Registry, you can add them to your project's external asset dependencies. Libraries that are fully on-chain will be clearly labeled in the drop-down as (fully on-chain). 104 | 105 | ![The drop-down label for the flex asset.](/static/screenshot4.png) 106 | 107 | ## Loading JS Libraries As External Asset Dependencies 108 | 109 | If you are specifically looking to utilize an IPFS/ARWEAVE type external asset dependency as a JavaScript library in your project script, you cannot simply add it as a script element onto the page. You must load it in a blocking manner so that the browser does not attempt to run your project script code before the lib is fully loaded. Here is an example of how to do this with ES6 dynamic imports (supported by most modern browsers: https://caniuse.com/es6-module-dynamic-import): 110 | 111 | ```js 112 | (async () => { 113 | await import('JS_EXTERNAL_ASSET_DEPENDENCY_FULL_URL_GOES_HERE'); 114 | 115 | // project script follows below 116 | })() 117 | ``` 118 | 119 | Here's another method without using ES6 dynamic imports, instead relying on using a callback that gets fired after the JS external asset dependency is injected into the html via a script tag: 120 | ```js 121 | function loadScript(url, callback) 122 | { 123 | // adding the script element to the head 124 | var head = document.getElementsByTagName('head')[0]; 125 | var script = document.createElement('script'); 126 | script.type = 'text/javascript'; 127 | script.src = url; 128 | 129 | // then bind the event to the callback function 130 | // there are several events for cross browser compatibility 131 | script.onreadystatechange = callback; 132 | script.onload = callback; 133 | 134 | // fire the loading 135 | head.appendChild(script); 136 | } 137 | 138 | const myProjectScriptCode = function() { .... } 139 | 140 | loadScript('JS_EXTERNAL_ASSET_DEPENDENCY_FULL_URL_GOES_HERE', myProjectScriptCode); 141 | ``` 142 | 143 | ## Locking A Project's External Asset Dependencies 144 | 145 | Artists and allowlisted addresses also have the ability to lock a project's external asset dependencies: 146 | ```solidity 147 | function lockProjectExternalAssetDependencies(uint256 _projectId) 148 | ``` 149 | This irreversible action removes the ability to add, update or remove from a project's external asset dependencies. 150 | 151 | Important notes: 152 | - Preferred gateways do not get locked with this action and, in general, cannot be locked. This is intentional to allow support for modifying the preferred gateway over time, which may change while CIDs remain fixed/permanent. 153 | - You can lock a project's external asset dependencies regardless of whether or not the project itself is locked. And you can continue to modify a project's external dependencies even if the project is locked, as long as the external asset dependencies for the project are not locked. 154 | 155 | ## Why should I use the Engine Flex specific fields for CIDs and IPFS gateways rather than hard-coding these values in the script? 156 | 157 | The Engine Flex contract was designed to expose specific on-contract fields for storing external asset dependencies (either via auxiliary on-chain storage, IPFS CIDs, or Arweave CIDs). For collectors and archivists preserving these art works, this increases the introspect-ability of where these external assets are stored, e.g. allowing for a more streamlined and robust process for replicating external assets stored on IPFS for a given project in the future. 158 | 159 | Additionally, after project scripts are locked, if an IPFS gateway is hardcoded it isn't possible to update this in the future if the gateway (but not the underlying asset CIDs) needs to change for whatever reason (partner is migrating gateway providers from Pinata to Infura, partner is shutting down private gateway in favor of a public one, etc.). If using the specified on-chain fields, the CIDs can be locked independently from the gateway, allowing flexibility to preserve future compatibility of the on-chain generator down the road. 160 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Filebase-IPFS.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 290 3 | --- 4 | 5 | # Using Filebase for External Assets 6 | 7 | Filebase is a geo-redundant IPFS pinning service and decentralized storage provider. When a file is uploaded to an IPFS bucket on Filebase, it is automatically pinned to the IPFS network with 3 duplicate copies, each of which is stored on an IPFS node located across 3 unique, geographic regions. 8 | 9 | Filebase offers an easy-to-use Web Console Dashboard for non-technical users, and an S3-compatible API for developers to utilize in a wide variety of tool configurations or SDKs. 10 | 11 | ## Signing Up 12 | 13 | Filebase uses a web-based console that can be found at https://filebase.com/signup. Existing accounts can go directly to https://console.filebase.com. 14 | 15 | To sign up for a Filebase account, navigate to https://filebase.com. To make a new account, click the ‘Try for Free’ button in the top right corner of the webpage. ![signup](/static/Filebase_setup1.png) 16 | 17 | Filebase is a free-to-use platform for all users. All users can store up to 5GB of data, with a maximum of 1,000 individual files on the IPFS network with no credit card required. 18 | 19 | Next, fill out the fields of the form, including an email address and password, and agree to the Filebase terms to create your account. 20 | 21 | You will receive an email with confirmation instructions. Click the link included in the email to confirm your account and finish the registration process. 22 | Once you’ve completed these steps, your Filebase account has been created. 23 | 24 | ## Uploading Content 25 | Once signed in, you will be brought to the Filebase dashboard. ![web_dashboard](/static/Filebase_setup2.png) 26 | 27 | To upload content, first you will need an IPFS bucket. Select 'Buckets' from the left menu bar, then select 'Create Bucket'. ![buckets](/static/Filebase_setup3.png) 28 | 29 | Give your bucket a name, then select IPFS for the network. ![bucket_ipfs](/static/Filebase_setup4.png) 30 | 31 | Then, select your bucket from the Buckets menu and select 'Upload'. You can choose to upload a File, Folder, or existing IPFS CID to Filebase. For this example, we'll use a single file. ![upload](/static/Filebase_setup5.png) 32 | 33 | You will be prompted to select a file from your computer. Once uploaded, it'll be displayed in the Filebase web console and it will be given an IPFS CID value. ![cid](/static/Filebase_setup6.png) 34 | 35 | When a file is uploaded to IPFS, the file’s contents are used to generate a cryptographic hash value. Then, this hash value is used to generate another value, which is used as the file’s content identifier (CID). CIDs are used to access files stored on IPFS, but instead of locating the file on the network based on its name, the CID is based on the file's contents. Any changes to the file's contents or metadata will result in a new, unique CID. 36 | 37 | The CID value is what is used within an Art Blocks generative script, under the 'CID' field. 38 | 39 | To preview your file using its IPFS CID and the Filebase public gateway, you can use the following URL format in any web browser: 40 | 41 | https://ipfs.filebase.io/ipfs/[CID] 42 | 43 | The Filebase public IPFS gateway is [https://ipfs.filebase.io/ipfs](https://ipfs.filebase.io/ipfs) and can be used by all Filebase uses to host Filebase pinned CIDs. For increased configuration options, performance, content whitelisting, and custom branding, a Filebase [Dedicated Gateway](https://docs.filebase.com/ipfs/ipfs-gateways/getting-started-with-ipfs-dedicated-gateways) can be used through one of Filebase's [paid IPFS plans.](https://docs.filebase.com/getting-started/billing-and-pricing/pricing-model#subscription-tiers) 44 | 45 | For more information, visit Filebase's extensive [documentation](https://docs.filebase.com) or send them an email at [hello@filebase.com](hello@filebase.com)! or reach out directly to the Art Blocks team. 46 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/IPFS-Setup.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 300 3 | --- 4 | 5 | # Using Pinata for External Assets 6 | 7 | Pinata is an excellent IPFS resource built with creators and non-technical users in mind, making it easy to upload content that you can use inside Art Blocks! This will walk you through the basics of uploading content to Pinata. 8 | 9 | ## Signing Up 10 | 11 | You can sign up for a free account which will allow up to 100 files and 1GB of storage! To get started visit [pinata.cloud](https://www.pinata.cloud/) and click the “Sign Up” button in the top right. It will ask you for a name, email, and password. 12 | 13 | ## Uploading Content 14 | Once you’re signed in you will see the Files Page which looks something like this: ![setup](/static/Pinata_setup_1.png) 15 | 16 | 17 | To start uploading content, simply click on the “Upload +” button and select “File” ![upload](/static/Pinata_setup_2.png) 18 | 19 | 20 | Of course from there click “Select File” and choose the file on your computer ![select](/static/Pinata_setup_3.png) 21 | 22 | 23 | Then give it a name, and click upload; that’s it! ![name](/static/Pinata_setup_4.png) 24 | 25 | 26 | Once it’s done uploading you will see the file listed on your files page! ![complete](/static/Pinata_setup_5.png) 27 | 28 | What’s important to note is the “CID” which stands for “Content Identifier.” It’s the core of IPFS and how files can be shared across the IPFS network. This is what you would input into the “cid” portion of an Art Blocks generative script and would look something like this: 29 | 30 | QmNrCnsNazd54aAQixQCVtikJNfizEXGKR6yLhr9P1TTJV 31 | 32 | If you want to preview your file you can simply click on the name of the file on the left side and it will open a preview in a new window. 33 | 34 | The default Pinata gateway is [https://gateway.pinata.cloud](https://gateway.pinata.cloud) but keep in mind that it should only be used for testing files. For production work you may want to consider getting a [Dedicated Gateway](https://www.pinata.cloud/blog/the-power-of-dedicated-gateways) on a paid plan. 35 | 36 | If you have further questions be sure to visit Pinata's [docs](https://docs.pinata.cloud) and do not hesitate to send them an email at [team@pinata.cloud](team@pinata.cloud)! or reach out directly to the Art Blocks team. 37 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Marketing-and-Launch-Prep: -------------------------------------------------------------------------------- 1 | --- 2 | order: 200 3 | --- 4 | 5 | # Launch Prep 101 6 | A successful marketing campaign will help new Engine partners connect and grow with their audience. Crypto markets are volatile, and sales are not guaranteed. One way Engine partners achieve sustainable success can be to build an active and engaged audience. 7 | 8 | ## Project pricing 9 | Balancing your initial pricing model can be complex, and your team should consider market conditions in your decision. Thankfully, Art Blocks Engine partners can use the tools in our Minter Suite for a nuanced launch approach. Our Minter Suite has drop mechanisms, including flat price, linear dutch auction, exponential dutch auction, custom erc20 tokens, and an allowlist. 10 | 11 | It’s also important to consider your primary audience. Are they crypto-native and follow every generative project? Are they retail visitors that may be buying their first generative output? Are you creating a bespoke experience that commands a premium? 12 | 13 | For oversubscribed projects that will have a lot of attention, we usually recommend a Dutch Auction mechanic to allow for price discovery on primary sales before settling at a resting price. But, if you want to reward your established community with early access, maybe an allowlist is right for you. 14 | 15 | Given our vantage point in the industry, we’re happy to connect and chat through the implications of different pricing models. 16 | 17 | ## Pre-launch mints 18 | It’s tradition for an artist to keep mint #0 from a new project. You can also pre-mint a few tokens for private buyers, specific community members, or for promotional use. But you should be open and honest if you plan to mint pieces before they’re publicly available. 19 | 20 | It’s important to note that if an artist or platform mints pieces from their collection, the mint price should be set to the anticipated sales price or the resting price from a Dutch Auction. 21 | 22 | ## Cross promotion 23 | The Art Blocks Twitter accounts will amplify Engine partner’s communications at the discretion of the Art Blocks team. Partner’s communication requests will default to [Art Blocks Engine’s Twitter account](https://twitter.com/ArtBlocksEngine). But, we’re proud of our partners' work, and occasionally, our [Flagship account](https://twitter.com/artblocks_io) will amplify messages that align with our brand identity and use generative minting technology in new and interesting ways. 24 | 25 | It’s important to note that brands should not rely on the Art Blocks collector base as the primary audience for new platform launches, and we encourage your team to strategize ways to increase the reach of generative content into new collector markets. 26 | 27 | ## Brand Assets 28 | Partners are only permitted to use approved brand assets (provided by Art Blocks) on their website and promotional materials. Please reach out if you have any questions. 29 | 30 | # Marketing Tools for Engine Partners 31 | Art Blocks carefully selects our partners based on platforms, ideas, and people we believe in. 32 | One benefit of releasing as an Art Blocks Engine partner is that you are now entering a vibrant ecosystem of generative enthusiasts. Our main advice for promoting your new platform is to build and foster your community. 33 | 34 | ### Discord 35 | Discord is a messaging platform made for online communities (think: Slack for everyone). It’s one of the primary ways Art Blocks interfaces with our community. Discord allows you to have a moderation team, set up public and private channels, host events, and much more. We highly recommend setting up a Discord server with some basic rules for conduct and channels relevant to your project. 36 | 37 | Art Blocks also has a list of Discord bots + tools we use in our server, and we’d be happy to share those tools with our partners. Contact your account manager if you’re interested in the tools Art Blocks uses. 38 | 39 | ### Twitter 40 | Twitter is a great place to promote your project. Our main piece of advice is to participate! Tweet, reply, and share works in progress. Engage with those who comment on your posts. Follow other generative artists, collectors, and Web3 thought-leaders. Alongside Discord, this is where you start conversations and find your audience. Sharing your work is equally as important as participating in conversations. 41 | 42 | Other Tips 43 | 44 | Have a virtual hype man? Gift them with a token! Show appreciation to your fans. 45 | Create additional materials that frame and give context to your upcoming platform. This can be done through good storytelling, Youtube videos, article, etc. 46 | 47 | ## Vibecheck 48 | Art Blocks Engine partners benefit from AB’s growing pains as a pioneer in the industry. From our vantage point, we can highlight mistakes we’ve previously made and help your team avoid those challenges. 49 | 50 | If you’re planning a unique drop mechanic, distribution mechanism, giveaway, or anything aside from a straightforward project release, you can always connect with the Art Blocks team to get our perspective on how the project may be publicly received. Reach out to your account manager to schedule a brainstorming session. 51 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/Mobile-Minter.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 400 3 | --- 4 | 5 | # Mobile Minting for In-Person Activations 6 | 7 | The Art Blocks Mobile Minter is a specialized app for iPad and iPhone designed to streamline the minting process during in-person events. Unlike the standard Art Blocks website, which is accessible from any device, the Mobile Minter is tailored for events where minting is exclusive to attendees or offered as an event gift. 8 | 9 | ### Features 10 | 11 | The Mobile Minter is capable of: 12 | 13 | - Minting Art Blocks tokens with a pre-funded wallet to cover gas fees 14 | - Minting tokens to an ENS name or a copied Ethereum address 15 | - Authenticating users with FaceID/TouchID for quick access during live events 16 | - Minting tokens without requiring manual signing and submission of Ethereum transactions 17 | 18 | ### Requirements 19 | 20 | The Mobile Minter is perfect for situations where: 21 | 22 | - A project is paused and not available for online minting 23 | - An artist wants to distribute their work at a live event 24 | - An iPad or iPhone with the latest iOS version is available 25 | - A small amount of Ethereum is on hand to cover gas fees for token recipients 26 | - You've set up a Stripe account to accept fiat payment (optional) 27 | 28 | --- 29 | 30 | ## Getting Started 31 | 32 | To use the Mobile Minter, follow these steps to set up your project and device according to the system requirements. 33 | 34 | ### Step 1. Project Configuration 35 | 36 | 39 | 40 | To set up the Mobile Minter for your project: 41 | 42 | 1. [Send a Slack message in Slack](https://app.slack.com/client/T02TTJYK6G1/C03DHF7ERRT) requesting access to the Mobile Minter 43 | 2. Art Blocks staff (@Shantanu Bala) will provide a wallet address that will be used to pay for gas fees for transactions 44 | _Note: The app manages this wallet, and any remaining funds can be returned to you at any time_ 45 | 3. Pause your project to restrict minting to the artist only 46 | 4. Transfer artist ownership to the wallet address from Step #2, making the Mobile Minter the sole minting wallet for the project 47 | 5. After completing these steps, Art Blocks staff (@Shantanu Bala) will give you login details to start using the mobile app 48 | 49 | ### Step 2. Device Setup 50 | 51 | To prepare your mobile device: 52 | 53 | 1. Update your iPhone or iPad to the latest iOS version 54 | 2. Set up and ensure FaceID or TouchID is functional on your device 55 | 3. Download the TestFlight app from the App Store: [TestFlight](https://apps.apple.com/us/app/testflight/id899247664) 56 | 4. [Join the Mobile Minter beta](https://testflight.apple.com/join/SlbRPkXG) on TestFlight: 57 | 5. Sign in, set up FaceID, and proceed to minting 58 | 59 | ### Step 3. Minting 60 | 61 | [Mobile Minter iPad app](https://youtu.be/yblIBFckCeg) 62 | 63 | Click the link above to view a screen recording of the Mobile Minter app on iPad. This test demonstrates the steps to mint a project on the Goerli test network. To mint a new token, users follow these steps: 64 | 65 | 1. Open the Mobile Minter app on an iPhone or iPad device 66 | 2. Sign in using FaceID 67 | 3. Select a project from the list of available projects 68 | 4. Input an ENS name or wallet address 69 | 5. Confirm the minting details 70 | 6. Wait for the token minting transaction to be confirmed 71 | 72 | --- 73 | 74 | ## Payment Processing 75 | 76 | The Mobile Minter utilizes [Stripe Terminal](https://stripe.com/terminal) for handling payments. Art Blocks does not offer merchant accounts or handle tax remittance for partners. To process fiat payments with Stripe Terminal, all Art Blocks Engine partners must [create and configure their own Stripe account](https://dashboard.stripe.com/register). 77 | 78 | The backend (Art Blocks Minting API) and point of sale (Mobile Minter app) software are provided by Art Blocks. However, the hardware must be procured by Art Blocks Engine customers. 79 | 80 | ### Stripe Reader M2 81 | 82 | We recommend using the Stripe Reader M2 with the Mobile Minter due to its convenient NFC payment support, Bluetooth connectivity, long-term SDK support, and reliable chip/magstripe fallback. You will need to order the M2 directly from Stripe. 83 | 84 | [Stripe Reader M2](https://stripe.com/docs/terminal/readers/stripe-m2) 85 | 86 | ### Direct Charges 87 | 88 | The Mobile Minter uses Stripe Connect to make a [direct charge](https://stripe.com/docs/connect/direct-charges) using your Stripe account. Stripe Connect processes direct charges for your Art Blocks Engine project using your own Stripe account (connected account) while using our platform - note that the charge amounts and fees are mock examples provided by Stripe. 89 | 90 | ### Stripe API Secrets 91 | 92 | **Do not share** your live Stripe API keys with anyone, including Art Blocks employees. Instead, Art Blocks will supply a secure OAuth link from Stripe for your usage. Connected accounts are managed using the process outlined by Stripe: 93 | 94 | [Managing connected accounts with the Dashboard](https://stripe.com/docs/connect/dashboard) 95 | 96 | --- 97 | 98 | ## Displaying Live Mints 99 | 100 | Web-enabled TVs or displays can showcase a real-time view of the latest tokens minted through the Mobile Minter. The Art Blocks documentation site offers an [overview of configuration options for the live viewer](https://docs.artblocks.io/creator-docs/art-blocks-api/artblocks-viewer/#artblocks-viewer). 101 | 102 | ### Example Embed 103 | 104 | You can embed [live.artblocks.io](http://live.artblocks.io) using an iframe on a web page containing your organization’s branding. 105 | 106 | [Example embed of [live.artblocks.io](http://live.artblocks.io) without any configuration parameters ([docs](https://docs.artblocks.io/creator-docs/art-blocks-api/artblocks-viewer/#artblocks-viewer))](https://live.artblocks.io/) 107 | 108 | Example embed of [live.artblocks.io](http://live.artblocks.io) without any configuration parameters ([docs](https://docs.artblocks.io/creator-docs/art-blocks-api/artblocks-viewer/#artblocks-viewer)) 109 | 110 | --- 111 | 112 | ## Frequently Asked Questions 113 | 114 | ### Can the Mobile Minter be used with projects that are not paused? 115 | 116 | Yes, the Mobile Minter can be used for active projects. However, pausing the project and transferring artist ownership to the app restricts minting exclusively through the app. If a project remains unpaused, anyone online can mint tokens. 117 | 118 | ### Can users pay for gas fees themselves? 119 | 120 | Currently, gas fees must be pre-funded by the artist or the organization using the Mobile Minter app, through the Mobile Minter's hot wallet. 121 | 122 | ### Can my prepaid gas fee balance be returned to me? 123 | 124 | Yes, please contact us to arrange the return of any remaining funds to the original depositing wallet. To have the remaining ETH returned, ensure that the funds were initially transferred to the Mobile Minter's hot wallet from an address capable of receiving ETH on behalf of your organization. The unspent ETH can only be sent back to the original sender's wallet. 125 | 126 | ### Can multiple projects be managed simultaneously through the Mobile Minter app? 127 | 128 | Yes, the Mobile Minter app allows you to manage multiple projects for in-person events. You can easily switch between projects during the event, ensuring a seamless minting experience for attendees. 129 | 130 | ### What currencies are supported for payments in the Mobile Minter app? 131 | 132 | The Mobile Minter app processes fiat payments via Stripe Terminal, which supports a variety of currencies. The available currencies depend on your Stripe account and the country where your business operates. You will be the merchant of record, and Art Blocks will collect its platform fees in ETH or USD. For a list of supported currencies for your customers, please refer to the [Stripe documentation](https://stripe.com/docs/currencies). 133 | 134 | ### Is it possible to customize the appearance of the Mobile Minter app for my event? 135 | 136 | While the Mobile Minter app does not offer customization, you can embed [live.artblocks.io](https://live.artblocks.io/) inside of a page that showcases your event's theme and branding. Please refer to the [Art Blocks documentation site](https://docs.artblocks.io/creator-docs/art-blocks-api/artblocks-viewer/#artblocks-viewer) for an overview of configuration options for the live viewer. 137 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/README.md: -------------------------------------------------------------------------------- 1 | # Art Blocks Engine 101 2 | 3 | --- 4 | 5 | Interested in learning about an Art Blocks Engine partnership? Email engine@artblocks.io to get the conversation started! 6 | 7 | --- 8 | 9 | A high-level process map for Art Blocks Engine onboarding. 10 | 11 | 1. After the terms of engagement are finalized, you’ll sign the Engine service and setup agreement. 12 | 2. Provide the following information to Art Blocks for your Engine project: 13 | 1 The admin address to own these contracts. This address controls the core contract and the minter contract. 14 | 2 The name of tokens from your contract (e.g. for Art Blocks it is "Art Blocks" https://etherscan.io/address/0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270#code). 15 | 3 The ticker for tokens from your contract (e.g. for Art Blocks it is "BLOCKS" https://etherscan.io/address/0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270#code). 16 | 3. Art Blocks' will deploy a set of testnet smart contracts for your team to begin integrating with. 17 | * After testnet deployment, there are two steps that may proceed in parallel. 18 | 1. Your team can integrate your front end to allow for minting via your new Engine smart contract (using deployed Engine smart contracts). 19 | 2. Art Blocks will need to integrate your newly deployed testnet smart contracts with our rendering infrastructure on testnet. After that, your team will connect to the staging site https://artist-staging.artblocks.io and interact with projects on the testing network you created as if they were on Art Blocks. 20 | * An ETA for this infrastructure integration piece will be given at the time of testnet contract deployment. On average, this will take 1 week from the time of testnet deployment. 21 | * To create a new project shell, you should use the addProject method of your newly deployed Engine Core Contract. This can be done by connecting to the contract via Etherscan. 22 | 4. Your team will integrate a custom web frontend with your deployed Engine smart contracts (e.g., implementing their own purchase + display flow) and with the Art Blocks API as needed. An example of frontend purchase flow logic is provided here as a reference for integrating partners: 23 | 24 |
25 | Example frontend purchase flow logic in JavaScript 26 | 27 | ```js 28 | /** CONNECTION **/ 29 | // A Web3Provider wraps a standard Web3 provider, which is 30 | // what Metamask injects as window.ethereum into each page 31 | const provider = new ethers.providers.Web3Provider(window.ethereum) 32 | // Connect to Dapp. This should happen in response to a user interaction 33 | await provider.send("eth_requestAccounts", []); 34 | // A signer is required to make any write transactions 35 | const signer = provider.getSigner(); 36 | const userAddress = await signer.getAddress() 37 | 38 | /** PRE PURCHASE **/ 39 | // Check that the project is unpaused, active, and 40 | // has not yet reached its maxInvocations. Also get 41 | // price per token. 42 | const genArt = new ethers.Contract('', GEN_ART_ABI, provider) 43 | const { paused } = await genArt.projectScriptInfo('') 44 | const { invocations, maxInvocations, pricePerTokenInWei, active, currencyAddress } = await genArt.projectTokenInfo('') 45 | if (Number(invocations) >= Number(maxInvocations) || paused || !active) { 46 | // Disable purchase 47 | return 48 | } 49 | 50 | /** PRE PURCHASE (ERC-20) **/ 51 | const NULL_ADDRESS = '0x0000000000000000000000000000000000000000' 52 | const projectUsesErc20 = currencyAddress && currencyAddress !== NULL_ADDRESS 53 | if (projectUsesErc20) { 54 | // Set up ERC-20 contract 55 | const erc20 = new ethers.Contract('', ERC20_ABI, signer) 56 | 57 | // Check that the user has the required amount of ERC-20 58 | const balance = await erc20.balanceOf(userAddress) 59 | if (balance.lt(pricePerTokenInWei)) { 60 | // Show insufficient funds error 61 | return 62 | } 63 | 64 | // Check allowance for minterAddress allowed by user 65 | const allowance = await erc20.allowance( 66 | userAddress, 67 | '' 68 | ) 69 | 70 | // If the user has not yet allowed enough of their ERC-20 to be used 71 | // by the minter, have them approve enough. 72 | if (allowance.lt(pricePerTokenInWei)) { 73 | // Trigger user wallet dialogue. This should be done in response to user interaction. 74 | const approveTransaction = await erc20.approve('', pricePerTokenInWei) 75 | // Wait for approve transaction confirmation 76 | await approveTransaction.wait(1) 77 | } 78 | } 79 | 80 | /** PURCHASE **/ 81 | // Set up minter contract connected to users wallet 82 | const minter = new ethers.Contract('', MINTER_ABI, signer); 83 | // Initiate purchase transaction (user must confirm through metamask). 84 | // If paying in ether, we must include a payable value otherwise payable value will be 0. 85 | const transaction = await minter.purchase('', { value: projectUsesErc20 ? '0' : pricePerTokenInWei}) 86 | // Wait for the transaction to be confirmed. The number passed to the wait function specifies the 87 | // number of block confirmations to wait for. You may want to wait longer than a single 88 | // block to prevent showing the wrong output in case of a chain reorg. The Art Blocks site 89 | // waits for 3 block confirmations. 90 | const receipt = await transaction.wait(3) 91 | // Iterate through events to find mint event 92 | const mintEvent = (receipt.events || []).find( 93 | (receiptEvent) => { 94 | const event = genArt.interface.getEvent( 95 | receiptEvent.topics[0] 96 | ) 97 | return event && event.name === 'Mint' 98 | } 99 | ) 100 | 101 | // Decode the mint event 102 | const mintEventDecoded = genArt.interface.decodeEventLog( 103 | 'Mint', 104 | mintEvent.data, 105 | mintEvent.topics 106 | ) 107 | // Token ID as BigNumber object 108 | const tokenIdBigNum = mintEventDecoded['_tokenId'] 109 | // Token ID as string 110 | const tokenId = tokenIdBigNum.toString() 111 | // Use the token id to display the newly minted token with the iframe'd generator 112 | ``` 113 |
114 | 115 | 116 | 5. Your team will use https://artist-staging.artblocks.io site to upload your project script source code and configure all project metadata details: 117 | - project description 118 | - the license associated with outputs 119 | - artist website 120 | - etc. 121 | 122 | If you need help, the Art Blocks team will help guide you through the process. 123 | 124 | 6. After you've set up and tested an Engine project, you can request a script audit from Art Blocks to guarantee resolution-agnosticism and determinism. 125 | 126 | **Warning:** if you opt-out of this step, it may result in undiagnosed issues with the rendered outputs. An unaudited project may not conform to the Art Blocks resolution-agnostic and deterministic standards. This means outputs may differ between screen sizes, devices, and operating systems or could be different from view to view. 127 | 128 | 129 | 7. After the complete end-to-end integration has been vetted on testnet, the above process may proceed on mainnet. 130 | 131 | Vetting includes minting in (1) each minting format, (2) from the Engine partner's frontend minting experience, and (3) while integrated with the Art Blocks' provided rendering infrastructure. 132 | 133 | 134 | 8.** Repeat steps 2-7 for mainnet deployment.** 135 | 136 | In summary, mainnet deployment entails: 137 | - Deploy mainnet contracts. 138 | - Integrate mainnet contracts with Art Blocks' rendering and API infrastructure. 139 | - Update your mainnet website to reference deployed mainnet contracts. 140 | - Create a new mainnet project shell on your smart contract using `addProject,` and upload all project details and project script using the artist interface at `https://artblocks.io.` 141 | - Mint at least one piece (mint #0) in a controlled environment on mainnet, being sure to mint in each format you plan to for your open release. 142 | 143 | 9. After the above has all been performed, you should run through the following "pre-flight" checklist and ensure there are no loose threads: 144 | * If accepting ETH, check that the wallets **are not** multisig wallets like Gnosis Safe (check the minter owner, rendering provider, artist, and any additional payee). 145 | * **Note: **It is possible to use multisig wallets if our client's front-end properly populates access lists in their front end, but minting from Etherscan will not work. 146 | * **Important for mainnet**: Test-mint a token in each currency that will be accepted for a project. Verify that your front end is used to successfully mint using each currency to ensure a proper end-to-end test. 147 | * If actions of whitelisting/removing minters are expected, test those actions. 148 | * If actions of changing max invocations are expected, test those actions. 149 | * When using your front-end to mint, ensure at least a 10% margin is added to each transaction's [estimated Gas Limit](https://docs.ethers.io/v5/api/providers/provider/#Provider-estimateGas), as originated by your frontend logic. 150 | * If a 0% margin is used during a live NFT sale, the blockchain state will likely change between a user-submitted transaction and when it's mined. Therefore, small changes in the required Gas Limit will likely result in transaction failures if the gas necessary increases. 151 | 152 | 10. You are now ready to sync with the Art Blocks team on planning for a launch date, which is **at least 1 week** from when the above steps have all been completed. 153 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/custom-dashboard-mutations.md: -------------------------------------------------------------------------------- 1 | # Common Custom Dashboard Mutations 2 | 3 | ## Introduction 4 | 5 | As an Engine partner, you have the option to create a custom artist/admin dashboard. While the majority of your project configuration will occur through on-chain transactions, there are specific off-chain fields that need to be set directly via our GraphQL API. 6 | 7 | This documentation outlines the permissions necessary for executing relevant actions and mutations. Please note that a user can only execute a mutation with the artist role for a project if their public address matches the artist address set for the project. A user can execute a mutation with the allowlisted role only if they are the super admin on the project's contract's ACL contract (V3 and up), or if they have been whitelisted on the project's contract (V2 and below). 8 | 9 | For all mutations listed in this documentation, the user must include the x-hasura-role header in their request, specifying either artist or allowlisted as the role, as appropriate. 10 | 11 | 12 | ## Actions 13 | 14 | Actions are specialized mutations that go beyond simple CRUD operations. Within your custom creator dashboard, you might find the `updateFeatures` and `updateProjectMedia` actions particularly useful. 15 | 16 | The `updateFeatures` action initiates a test run of a feature script for a test token. Upon validating that the output aligns with the provided feature fields, it updates both the `feature_fields` and `feature_script` on the project. Both artists and allowlisted users can execute this action. Artists can make updates either before the project is completed, or afterwards, if the allowlisted user has toggled the `enable_artist_update_after_completion` flag on the project's associated features row. 17 | 18 | The `updateProjectMedia` action refreshes various media assets linked to a project's tokens. The refreshed media depends on the parameters passed to the action, which may include different formats of preview images and features. This action is accessible to both artists and allowlisted users. However, the execution of this action is rate-limited to once 24 hours for artists. 19 | 20 | Here are the parameters accepted by the `updateProjectMedia` action: 21 | - `projectId`: The ID of the project to be updated. 22 | - `features`: A boolean that indicates whether to recalculate features for the project's tokens. 23 | - `render`: A boolean that indicates whether to re-render the preview images for the project. 24 | - `renderVideo`: A boolean that indicates whether to re-render preview videos/gifs for the project. 25 | 26 | All these actions are executed via specific mutations in the GraphQL API. 27 | 28 | 29 | ## Tags 30 | 31 | Tags and projects share a many-to-many relationship, managed through the `entity_tags` table. Tags serve as non-functional descriptors that can be used to categorize projects. To associate a tag with a project, the `insert_entity_tags` mutation is used. 32 | 33 | In the context of an Engine dashboard, you're likely most interested in presentation tags, which can be fetched with the following query: 34 | 35 | ``` 36 | query { 37 | tags(where: {grouping_name: {_eq: presentation}}) { 38 | name 39 | } 40 | } 41 | ``` 42 | 43 | Both the artist and contract admin roles have the permissions to execute the `insert_entity_tags` mutation. Here's an example of how to use this mutation: 44 | 45 | ``` 46 | mutation { 47 | insert_entity_tags(objects: [{ project_id: "0x...", tag_name: "animated"}]) 48 | } 49 | ``` 50 | 51 | 52 | ## Project 53 | 54 | The table below lists permissions for directly updating relevant off-chain fields on the project row. Many of these fields are optional and are intended to enrich the descriptive content on your frontend. Fields marked with an asterisk (*) have a functional impact on the project. 55 | 56 | | Field | Artist Permission | Allowlisted Permission | Description 57 | |---|---|---|---| 58 | | `artist_display_notes` | X | X | Contains the artist's intentions for how the artwork should be displayed. 59 | | `link_to_license` | X | X | Provides a link to the copyright license for the project (e.g., "https://creativecommons.org/licenses/by-nc-nd/4.0/"). 60 | | `creative_credit` | X | X | Allows artists to acknowledge contributors, inspirations, or other sources of influence. 61 | | `disable_sample_generator` | X | X | Indicates the artist's preference for displaying project previews. Influences whether the "explore possibilities" modal is displayed on the project page on our flagship site. 62 | | `featured_token_id` | X | X | Enables the artist to specify a token ID to feature. Determines the token displayed as the project's cover image on our flagship site. 63 | | `sales_notes` | X | X | Provides specific details about the sales mechanics of the project. 64 | | `charitable_giving_details` | X | X | Outlines any charitable giving aspects associated with the project. 65 | | `render_delay`* | X | X | Sets the delay (in seconds) before our renderer captures a snapshot of the project for preview images. 66 | | `generate_video_assets`* | X | X | Determines whether GIFs and MP4s are generated during individual token refreshes, batch token refreshes, and new token mints. 67 | | `primary_render_type` | X | X | Specifies the preferred format for displaying the project on detail pages. 68 | | `preview_render_type` | X | X | Specifies the preferred format for the project's preview images. 69 | | `artist_interview` | - | X | Provides a link to an interview with the artist. 70 | | `start_date` | - | X | Sets the intended start time of the project, indicating when it will become unpaused and active. 71 | 72 | All these fields are updated using the `update_projects_metadata_by_pk` mutation. 73 | 74 | --- 75 | 76 | Please note: In the tables above, 'X' stands for write permissions, and '-' stands for no write permissions. -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/faqs.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 100 3 | --- 4 | 5 | # FAQs 6 | 7 | - [What are the Art Blocks Engine offerings?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#what-are-the-art-blocks-engine-offerings) 8 | - [What's included with Art Blocks Engine?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#whats-included-with-art-blocks-engine) 9 | - [What effect does ‘locking’ a project have?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#what-effect-does-locking-a-project-have) 10 | - [How can we add more team members to Discord?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#how-can-we-add-more-team-members-to-discord) 11 | - [How long will the process take from start to public launch?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#how-long-will-the-process-take-from-start-to-public-launch) 12 | - [What information do we need to provide?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#what-information-do-we-need-to-provide-to-deploy-our-smart-contracts) 13 | - [Does Art Blocks create a front-end site for our project?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#does-art-blocks-create-a-front-end-site-for-our-project) 14 | - [How long will each stage of the process take?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#how-long-will-each-stage-of-the-process-take) 15 | - [Core contract vs. Minter contract?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#core-contract-vs-minter-contract) 16 | - [How do we list Art Blocks Engine pieces on OpenSea?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#how-do-we-list-art-blocks-engine-pieces-on-opensea) 17 | - [What's the difference between a testnet token and a mainnet token?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#whats-the-difference-between-a-testnet-token-and-a-mainnet-token) 18 | - [Flex: What are the limitations around file size and file type for external assets? How many external assets can a project have?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#flex-what-are-the-limitations-around-file-size-and-file-type-for-external-assets-how-many-external-assets-can-a-project-have) 19 | - [Flex: Can JS external asset dependencies make external calls to other APIs/assets?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#flex-can-js-external-asset-dependencies-make-external-calls-to-other-apisassets) 20 | - [How does project size work on the Minter contract vs Core contract?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#how-does-project-size-work-on-the-minter-contract-vs-core-contract) 21 | - [How does `autoApproveArtistSplitProposals` work?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#how-does-autoApproveArtistSplitProposals-work) 22 | - [When should I enable GPU rendering?](https://docs.artblocks.io/creator-docs/art-blocks-engine-onboarding/art-blocks-engine-101/faqs/#when-should-I-enable-GPU-rendering) 23 | 24 | ## What are the Art Blocks Engine offerings? 25 | 26 | **Art Blocks Engine:** 27 | Used for on-chain storage of generative systems. Projects can use no dependencies or one dependency from a list of decentralized libraries. [See the allowed dependencies here.](https://docs.artblocks.io/creator-docs/creator-onboarding/readme/#limited-dependencies) 28 | 29 | **Art Blocks Engine Flex:** 30 | Allows generative systems to reference off-chain assets stored on IPFS or Arweave, enabling creative tools like photography, AI, and GAN. 31 | 32 | Email us at Engine@artblocks.io to discuss which offering best suits your needs. 33 | 34 | ## What's included with Art Blocks Engine? 35 | 36 | For a new partnership, the standard current Art Blocks Engine offerings include: 37 | 38 | 1. Deployment of Engine smart contracts suite to testnet and mainnet (includes gas costs). 39 | 2. Integration of deployed Core contract with decentralized Graph indexing architecture on testnet and mainnet, includes GRT costs incurred for subgraph update deployment. 40 | 3. Integration of deployed contracts and subgraph with Art Blocks' project setup site and rendering/metadata infrastructure (APIs: Token, Generator, Rendered Image). 41 | 4. (in-migration) Integration with the shared Art Blocks Minter Suite. Art Blocks is rolling out a shared minter suite that will be available for Engine Partners to use to mint their projects. Previously deployed V3 Engine contracts will have the ability to migrate to the new shared minter suite. This means the same minting contracts used for Art Blocks Flagship will be available for Engine partners. In addition to the ability to query minter state via subgraph or Hasura queries, Art Blocks has future plans to expand our offering to include the ability to configure minter settings in an Artist Dashboard, and the ability to use a new Art Blocks minting SDK to more easily mint tokens on your frontend. 42 | 43 | ## What effect does ‘locking’ a project have? 44 | 45 | Locking a project (specifically on V2 Contracts) permanently freezes the artist name, project name, project scripts, project license, and project IPFS hash on the blockchain. Additionally, maximum invocations of a project can never be increased. 46 | 47 | **Locked projects can not be unlocked** 48 | 49 | A summary of how the smart contract functions behave: 50 | 51 | - `toggleProjectIsLocked` 52 | - only callable by admin whitelisted wallets on the core contract 53 | - can only lock projects (i.e. **locked projects can not be unlocked**) 54 | - The following functionality is only allowed on unlocked projects: 55 | - `updateProjectName` 56 | - `updateProjectArtistName` 57 | - `updateProjectLicense` 58 | - project script changes: 59 | - `addProjectScript` 60 | - `updateProjectScript` 61 | - `removeProjectLastScript` 62 | - `updateProjectScriptJSON` 63 | - `updateProjectIpfsHash` 64 | - The following functionality is affected by a project being unlocked vs. locked: 65 | - `updateProjectMaxInvocations` 66 | - before being locked, maximum invocations may be increased 67 | - after being locked, maximum invocations may only be decreased 68 | 69 | ### Changes for V3 contracts (deployed after March '23) 70 | 71 | - In addition to the above, artists can update project description when project is unlocked. However, only contract admins can update project the description when the project is locked. 72 | - **V3 contracts autolock four weeks after a project is complete.** 73 | 74 | ## How can we add more team members to Discord? 75 | 76 | Contact your account manager for an invite link to the private Discord server. 77 | 78 | ## How long will the process take from start to public launch? 79 | 80 | The process typically takes 10 weeks from initial conversation to public launch, but is **highly** dependent on partner's resource allocation. To reduce delays, have a front-end developer, artist, go-to-market strategy, and sufficient onboarding time ready. 81 | 82 | ## What information do we need to provide to deploy our smart contracts? 83 | 84 | To get started, you'll provide our team with: 85 | 86 | - Network: (Mainnet or Testnet) 87 | - A testnet/mainnet Ethereum wallet address (that you currently own and control) you'll use to manage your Art Blocks Engine smart contracts. 88 | - The name you’ll use for tokens from your contract (e.g., for Art Blocks, it is "Art Blocks") 89 | - The ticker symbol you’ll use for tokens from your contract (e.g., for Art Blocks, it is "BLOCKS") 90 | - Deployment Type: V3 Onchain Engine or V3 Flex Engine 91 | - Minter Type: set price eth only, set price custom erc20, merkle tree allowlist holder-gated, linear DA, exponential DA, and exponential DA with settlement 92 | - _note: minter selection will not be needed after migrating to shared minter suite_ 93 | - Starting project ID # (>=0): 94 | - Set `autoApproveArtistSplitProposals` true or false\*\* 95 | 96 | \*\*It needs to be set at deployment and cannot be changed later. 97 | 98 | tldr - if true, artist royalty wallet changes are auto-approved. If false, the contract admin will need to approve the artist's royalty wallet changes. This is an added check to ensure your artists aren't changing royalty wallets to a random address, which could complicate accounting/ OFAC compliance. 99 | 100 | We cannot deploy your contract until you provide the above information. **The name and symbol tied to your contract cannot change once your contract is deployed.** 101 | 102 | ## Does Art Blocks create a front-end site for our project? 103 | 104 | No, partners are responsible for creating and designing their customer-facing experience. 105 | 106 | However, we do have a [front-end React template](https://github.com/ArtBlocks/artblocks-engine-react) with web3 functionality you need to launch a minting site. You will still be responsible for designing the user experience, but this significantly reduces the time needed to complete a front-end. 107 | 108 | ## How long will each stage of the process take? 109 | 110 | 1. Initial outreach - **1-2 weeks** 111 | 2. Project scope - **1-2 weeks** 112 | 3. Contract agreement - **1 week** 113 | 4. Smart contract details - **1-2 days** 114 | 5. Contract configuration & testnet deployment - **1 week** 115 | 6. Testnet infrastructure integration -** 1 week** 116 | 7. Integration with partner’s site - **Varies** (dependent on partner) 117 | 8. Test mints on partner site - **Varies** (dependent on partner) 118 | 9. Deployment to mainnet - **1-2 weeks** 119 | 10. Mainnet infrastructure integration -** Varies** (dependent on partner) 120 | 11. Mint #0 - **Instant** 121 | 12. Project launch! - **1 week** after step 11 122 | 123 | ## Contract Ecosystem 124 | 125 | **Core contract:** 126 | This is the smart contract that controls the artwork created by the artist. No financial transactions occur on this smart contract. 127 | 128 | **AdminACL:** 129 | By default, Engine smart contracts have two sets of permissions, Admin and Artist. The AdminACL contract controls which wallets can access which functions on your core contract. If you'd like to assign more granular control of your smart contract to different wallets, you can fork and customize the AdminACL contract. 130 | 131 | **Minter Filer:** 132 | The minter filter configures minter-types to specific projects. 133 | 134 | **Minter contract:** 135 | These smart contracts receive funds and split them between the artist(s) and the platform. Artists receive funds directly from these contracts. 136 | 137 | ## How do we list Art Blocks Engine pieces on secondary markets? 138 | 139 | Secondary marketplaces will automatically detect and display projects on your contract. If you’d like each project to have its own storefront on OpenSea, please contact an account manager to facilitate the change. 140 | 141 | ## What's the difference between a testnet token and a mainnet token? 142 | 143 | **Testnet tokens are free, unlimited, and worthless.** They only exist as a tool for the testing environment before spending actual money (Ether) deploying on Ethereum’s mainnet. 144 | 145 | ## Flex: What are the limitations around file size and file type for external assets? How many external assets can a project have? 146 | 147 | There are no explicit limitations on the contract side, neither for file size or type or how many external assets a project can have. Ultimately, this is at the discretion of the artist, but Art Blocks recommends paying close attention to ensure that artworks are as accessible as possible for as many different types of users as possible. Generally speaking, the above factors should be influenced by trying to achieve the best user experience for the artwork in terms of performance and load time. 148 | 149 | Some additional recommendations: 150 | 151 | - Try to keep the overall download size for users viewing the work to be under ~10mb OR ensure the artwork description mentions the heavier load/longer loading time. Additionally, consider whether or not it may make sense to have a loading indicator as part of the artwork itself. 152 | - When working with less common file types, remember to test on various platforms/browsers, to ensure the best cross-platform compatibility possible. 153 | 154 | ## Flex: Can JS external asset dependencies make external calls to other APIs/assets? 155 | 156 | Having your JS external asset dependencies making external calls, whether it's to an API or other assets, is not a supported use of the Engine Flex offering, as it breaks the assumption of only utilizing off-chain decentralized platforms. We encourage you to, instead, serialize any data you may need from these external calls into assets (JSON, TXT, etc) that are also stored on the platforms Engine Flex currently supports (IPFS and Arweave). 157 | 158 | ## For the status of a project on the contract, how does 'active' and 'paused' differ? 159 | 160 | The value of `paused` is determined by artist, whereas `active` is determined by contract admin. Both need to be in a mintable state (`paused`=false, `active`=true) for a project to be publicly available to mint. 161 | 162 | ## Why is there a small delay between the token's mint transaction confirming and it being viewable on the Art Blocks Generator (live view)? 163 | 164 | Art Blocks uses the decentralized Graph network to index on-chain data in our publicly available subgraph. There can be a slight delay between the first block confirmation on the ethereum network for a transaction and that transaction being indexed by our subgraph. To mitigate this, as an Art Blocks engine provider, your client should be waiting multiple block confirmations (we recommend at least 2 blocks) before it shows the generator view to the user. The generator will return an error message if the token is not indexed yet, accompanied by 4XX status code. Many clients also employ a polling strategy, only showing the requested generator view once the requested generator url is returning a 2XX status code. 165 | 166 | ## How does project size work on the Minter contract vs Core contract? 167 | 168 | A project's max invocations on Art Blocks contracts are handled differently on the Core contract and the Minter contract. 169 | 170 | On the **Core contract**, setting a project size establishes the project's maximum size, and this value **cannot** be increased once set. The max invocations on the core contract define the absolute upper limit for the number of mints for a specific project. 171 | 172 | On the other hand, each **Minter contract** allows you to set max invocations for the specific minter using the `manuallyLimitProjectMaxInvocations` function. This setting does not lock the project size but controls the maximum number of mints allowed by that particular minter. When updating the maxInvocations value for a project in the Minter contract, you must adhere to these conditions: 173 | 174 | 1. The new value of \_maxInvocations should not be greater than the maxInvocations set in the core contract. 175 | 2. The new value of \_maxInvocations should not be less than the current number of invocations. 176 | 177 | ## How does `autoApproveArtistSplitProposals` work? 178 | 179 | When `true`, `aproveArtistSplitProposals` is a feature that allows artists to automatically change their royalty split payout address and the split percentage without requiring approval from the contract admin. This makes the process faster and more convenient for artists but may increase the risk of unauthorized changes to royalty wallets, which could complicate accounting or OFAC compliance. 180 | 181 | If set to `else` the contract admin will need to approve any changes to the artist's royalty wallet, adding a layer of security and control. 182 | 183 | ## When should I enable GPU rendering? 184 | 185 | If your image preview is showing a blank, incomplete, or invalid rendering for a token, turning on GPU rendering may resolve the issue. GPU rendering is managed by the Art Blocks team and enabling is determined on a case-by-case basis. Before requesting GPU rendering, check your project script code for any potential issues and/or try increasing your render delay (up to 10min). Reach out to the Art Blocks team to enable GPU rendering on a specific project if the token issues continue after adjusting the delay. 186 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/minter-suite-migration-runbook.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: -5 3 | --- 4 | 5 | # Minter Suite Migration Runbook 6 | 7 | !!!warning 8 | This documentation is a work in progress. Minter suite migration is ongoing, and initial migrations are being actively worked. Please reach out to the Art Blocks team with any questions. 9 | !!! 10 | 11 | This page provides a step-by-step guide on how to migrate a V3 Art Blocks Engine core contract from the legacy non-shared minter suite to the new shared minter suite. This migration is required for all V3 Engine contracts that want to use the new shared minter suite, which has the following benefits: 12 | 13 | - All minter contracts are indexed by the Art Blocks subgraph, and can therefore be configured in the new Artist Dashboard website (coming soon) 14 | - All minter Art Blocks Flagship minting contracts become available for use by Engine projects 15 | - Collectors can purchase from the same trusted contract they interact with on Flagship. 16 | - Art Blocks will release an SDK to simplify the minting process for Engine projects (coming soon) 17 | 18 | Migration is not available for V2 Engine contracts; for Engine partners that wish to upgrade to a V3 Engine contract, please contact the Art Blocks team. 19 | 20 | Migration is not required for V3 Engine contracts that wish to continue using the legacy non-shared minter suite. However, we recommend migrating to the new shared minter suite for the benefits listed above. 21 | 22 | ## Migration Steps 23 | 24 | ### 1. Engine partner frontend updated to support new minter suite 25 | 26 | The Engine partner's frontend must be updated to support the new shared minter suite. In general, the new shared minter suite requires the following changes: 27 | 28 | - When specifying a project to configure or purchase from, an additional input arg of `coreContract` (address) must be specified. This is because one minter/minter filter contract is used for many core contracts. 29 | - View functions on the minter contracts may have changed slightly. This is due to some minor architectural changes to the minter contracts that we believe simplifies their codebase and make them more extensible. 30 | 31 | The source code of all new, shared minter contracts is available on the [Art Blocks smart contracts monrorepo](https://github.com/ArtBlocks/artblocks-contracts/tree/main/packages/contracts/contracts/minter-suite/Minters). The complete list of all new, shared minter contracts is: 32 | 33 | - MinterSetPriceV5 34 | - MinterSetPriceERC20V5 35 | - MinterSetPriceMerkleV5 36 | - MinterSetPriceHolderV5 37 | - MinterSetPricePolyptychV5 38 | - MinterSetPricePolyptychERC20V5 39 | - MinterDAExpV5 40 | - MinterDALinV5 41 | - MinterDAExpHolderV5 42 | - MinterDALinHolderV5 43 | - MinterDAExpSettlementV3 44 | 45 | !!!info 46 | In the coming months, the Art Blocks team will be releasing a new minting SDK that can be used to support the new shared minter suite. Documentation for the SDK will be referenced here when it becomes available. 47 | !!! 48 | 49 | ### 2. Schedule downtime for any live projects 50 | 51 | The migration process requires all artists with live projects configure a new minter. All live projects should be paused during the migration process. Switching to the new minter filter is simple, but after migrating to the new minter filter, the artist of every live project must configure their minter in the new minter suite. This is also only a few transactions, but it is fully reliant on coordinating with artists to be ready to re-configure minters of open projects after switching to the new minter filter. 52 | 53 | ### 3. Core contract admin sends migration transactions (testnet before mainnet) 54 | 55 | The Engine partner's core contract admin should send 2 transactions to the core contract: 56 | 57 | 1. Engine Admin calls `updateRandomizerAddress` on the core contract, passing in the address of the shared randomizer 58 | 59 | | Network | Shared Randomizer Contract Address | 60 | | ------------------------------- | -------------------------------------------- | 61 | | Mainnet (Ethereum) | `0x13178A7a8A1A9460dBE39f7eCcEbD91B31752b91` | 62 | | Artist Staging Sepolia | `0x28f2D3805652FB5d359486dFfb7D08320D403240` | 63 | | Artist Staging Goerli | `0xC91CFC2062D8B4Ff53A7c8836CAEf925a7C78c81` | 64 | | Arbitrum One | `0x6a5976391E708fBf918c3786cd1FcbB88732fbc1` | 65 | | Artist Staging Arbitrum-Sepolia | `0x28f2D3805652FB5d359486dFfb7D08320D403240` | 66 | 67 | 2. Engine Admin calls `updateMinterContract` on the core contract, passing in the address of the shared minter filter. 68 | 69 | | Network | Shared Minter Filter Contract Address | 70 | | ------------------------------- | -------------------------------------------- | 71 | | Mainnet (Ethereum) | `0xa2ccfE293bc2CDD78D8166a82D1e18cD2148122b` | 72 | | Artist Staging Sepolia | `0xa07f47c30C262adcC263A4D44595972c50e04db7` | 73 | | Artist Staging Goerli | `0xD1d9aD8B1B520F19DFE43Cc975b9470840e8b824` | 74 | | Arbitrum One | `0x94560abECb897f359ee1A6Ed0E922315Da11752d` | 75 | | Artist Staging Arbitrum-Sepolia | `0xa07f47c30C262adcC263A4D44595972c50e04db7` | 76 | 77 | You are now using the new shared minter suite! 78 | 79 | ### 4. Artists re-configure minters for ALL LIVE PROJECTS 80 | 81 | **AFTER** step 3, artists must re-configure their minters for **all live projects**. This is a quick process, but requires coordination with artists to ensure they are ready to re-configure their minters after the switch. 82 | 83 | Artists can re-configure their minters manually by following the instructions documented in the [engine project launch/assigning a minter section](./Engine-project-launch.md#assigning-a-minter-v3-only-new-shared-minter-suite). Additionally, soon, artists will be able to configure their project minters via the (new) Artist Dashboard. 84 | 85 | The process for _most_ open projects will likely be to switch to a fixed price minter. 86 | 87 | After configuring a minter, the project is now using the new shared minter suite and live for minting! 88 | 89 | ### 5. Engine partner monitors migration progress 90 | 91 | It is recommended that the Engine partner monitor the migration process to ensure that all artists have successfully re-configured their minters. Additionally, the Engine partner should use diligence to ensure that purchases and payment splits after the migration are working as expected. 92 | 93 | ### 6. Add any custom, one-off minters to the shared minter suite 94 | 95 | The new shared minter suite provides all Art Blocks Flagship minters to Engine projects. However, if the Engine partner has any custom, one-off minters that they would like to use for their core contract, they can be added for their specific contract. Please see please see the [Adding custom, one-off minters](./../../minter-suite/custom-minters.md) page for steps on how to do this. 96 | 97 | Note that at this time, custom, one-off minters will not be indexed in the Art Blocks Subgraph or API. This is likely not a change for custom minters being used prior to migration. 98 | 99 | ### 7. Explore new minter suite features 100 | 101 | The new shared minter suite provides all Art Blocks Flagship minters to Engine projects. Feel free to explore integrating new minters into your product! 102 | 103 | ## Migration FAQ 104 | 105 | ### What happens if an artist does not re-configure their minter? 106 | 107 | If an artist does not re-configure their minter, their project will not be able to mint tokens. The artist will need to re-configure their minter before their project can mint tokens. 108 | 109 | ### What happens if an artist re-configures their minter incorrectly? 110 | 111 | If an artist re-configures their minter incorrectly, best case scenario is that their project will not be able to mint tokens, and troubleshooting can identify the issue. Worst case scenario is that their project will be able to mint tokens, but the price per token will be incorrect (e.g. incorrect price entered) or the maximum invocations will be too high (e.g. forgot to set minter-max-invocations to a lower value than set on the core contract, if desired). For these reasons, artists should use diligence when re-configuring their minters. 112 | 113 | ### What happens if I migrate to the new shared minter suite? 114 | 115 | If you migrate to the new shared minter suite, you will be able to use any new minters developed for Art Blocks Flagship. Additionally, you will be able to use the Artist Dashboard to configure your minters, because your minter suite will be indexed. You will also be able to use the new minting SDK to simplify your minting process. 116 | 117 | ### What happens if I do not migrate to the new shared minter suite? 118 | 119 | If you do not migrate to the new shared minter suite, nothing will change, but you will miss out on new developments. You will not be able to use any new minters developed for Art Blocks Flagship. Additionally, you will not be able to use the Artist Dashboard to configure your minters, because your minter suite will not be indexed. You will need to continue to use the legacy non-shared minter suite. 120 | 121 | ### What happens if I migrate to the new shared minter suite, but I do not want to use the (coming soon) Artist Dashboard to configure my minters? 122 | 123 | There are many reasons why a partner might want to do this! 124 | 125 | If you migrate to the new shared minter suite, but you do not want to use the Artist Dashboard to configure your minters, you can continue to configure your minters via your frontend, etherscan, etc., but your process will be slightly updated to support the new shared minter suite. Comparing the new minter contracts and the legacy minter contracts will help you understand the changes. 126 | 127 | ### What happens if I migrate to the new shared minter suite, but I do not want to use the new (coming soon) minting SDK? 128 | 129 | No problem! 130 | 131 | If you migrate to the new shared minter suite, but you do not want to use the new minting SDK, you can continue to use your existing minting process, but your process will be slightly updated to support the new shared minter suite. 132 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/art-blocks-engine-101/what is Art Blocks Engine.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 1000 3 | --- 4 | 5 | # What is Art Blocks Engine and Engine Flex? 6 | 7 | Art Blocks Engine and Engine Flex are custom branded solutions from Art Blocks. Our offerings allow the generative NFT minting technology used by artists at Art Blocks to be integrated with third-party sites. 8 | 9 | Engine allows partners to release generative outputs using our existing smart contracts and rendering infrastructure resulting in turnkey and branded generative projects. Engine partners own their smart contracts and can use them to release as many projects as they like as often as they like. 10 | 11 | We currently partner with organizations from every sector that are interested in launching generative collections, but are particularly interested in the fashion, sports, media, manufacturing, and fine art industries. 12 | 13 | For more information on Art Blocks Engine partnerships please contact: info@artblocks.io 14 | 15 | ## What is the difference between Art Blocks Engine and Engine Flex? 16 | 17 | Art Blocks Engine is our offering that aligns most closely with the Art Blocks flagship product (https://artblocks.io), and has the same technical approach to on-chain art where artists store the entirety of their generative algorithms on-chain within the Engine smart contract and are limited to a single, widely-distributed, off-chain dependency (e.g. p5js). 18 | 19 | With Art Blocks Engine Flex artists are able to include off-chain assets, stored on the decentralized storage solutions of IPFS or Arweave, as additional inputs into their creative coding practice. This allows, for example, a project that takes an image as an input and creates 1of1ofX outputs applying a generative practice to this input image. This final output combines a generative script, a token hash, and additional off-chain assets. 20 | 21 | ## How does Art Blocks Engine Flex work? 22 | 23 | With Art Blocks Engine Flex contracts, a per-project (as opposed to per-contract) field is available on all projects that allow an artist to set a single off-chain dependency or set of multiple off-chain dependencies based on the content ID locations where these dependencies are stored on IPFS or Arweave. 24 | 25 | Currently, we do not yet support the turnkey ability to programmatically upload/pin these dependencies to IPFS/Arweave within the Engine experience directly; however, our team is more than happy to assist partners in the process of uploading/pinning assets on IPFS/Arweave using existing third party solutions for doing so (e.g. Pinata in the case of IPFS). 26 | 27 | Note that for a single project, it is possible to have a single off-chain dependency (e.g. a single image file) or a set of off-chain dependencies (e.g. a series of images from a set). This means that is possible, for example, to have a project that creates 1of1ofX generative variants of a single base image asset, or one in which for a given token a random image is selected from the base image asset set, and then a generative process is applied to it. 28 | 29 | It is also important to note that images are not the only supported external asset dependency type. It is possible to reference any file type that can be pinned/uploaded to IPFS or Arweave and intelligibly incorporated into a generative algorithm to create interesting artistic outputs. For example, a project could use `tensorflow.js` as its single-dependency, have its generative script be a tensorflow based creative coding algorithm, and store the model file for the machine learning model on IPFS or Arweave to support a ML/AI based project. 30 | 31 | ## What is the smart contract architecture for Art Blocks Engine? 32 | 33 | The Art Blocks Engine offers two core contract options: the V3 Engine core contract and the V3 Engine Flex core contract. These contracts are mutually exclusive, and partners should select the appropriate core contract based on their needs and whether they require the flex capabilities. 34 | 35 | The V3 Engine core contract is an ERC-721 NFT contract that manages metadata for all Art Blocks NFTs, including artist scripts, token hashes, and token royalty data. 36 | 37 | The V3 Engine Flex core contract includes everything in the V3 Engine contract, but also allows artists to use external assets in their Engine tokens. These external assets can be images, videos, audio, or other data and may be stored on decentralized storage systems such as IPFS, Arweave, or on the Ethereum blockchain 38 | 39 | Both core contracts integrate with various peripheral contracts to provide flexible, customizable, and extensible functionality. These peripheral contracts are: 40 | 41 | - Admin Access Control List (ACL) contract: Manages granting admin access to the core contract and related contracts. It is designed to be highly flexible, extensible, and upgradable. 42 | - Randomizer contract: Generates pseudo-random numbers for the core contract when new tokens are minted. This architecture is designed to be highly flexible, enabling designs that may desire asynchronous random number generation or other hash generation methods. 43 | - Core Registry contract: Notifies the subgraph indexing service of new Art Blocks Engine tokens. When the Core Registry emits an event, the subgraph indexing service is notified, and the Engine contract is indexed and made available for querying on the Art Blocks subgraph. It also notifies a shared minter suite to allow the new Engine contract to be used by minters. 44 | - Minter Suite contracts: A collection of contracts used to mint Art Blocks Engine tokens. The Minter Suite is designed to be highly flexible and can be used to mint tokens in various ways. 45 | 46 | Partners should choose between the V3 Engine core contract and the V3 Engine Flex core contract based on their project's goals and technical capabilities. The smart contract architecture for Art Blocks Engine provides a robust and flexible system for managing and creating generative NFTs while integrating with various peripheral contracts to extend its capabilities. 47 | 48 | For additional context, please check out [this architecture overview (with accompanying diagrams)](https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/V3_ARCHITECTURE.md). 49 | 50 | ## What is the "minter suite"? 51 | 52 | The Art Blocks minter suite is a collection of smart contracts that facilitate the secure and efficient minting of generative art tokens for all Art Blocks contracts in the V3 architecture. Originally, each contract had its own minter suite. The new shared minter suite enables Engine contracts use the same minting contracts as Art Blocks Flagship, which enables a seamless experience for collectors and artists. 53 | 54 | **Shared Minter Suite** 55 | 56 | A summary of the division of responsibilities between the MinterFilter and individual Minters can be summarized as: 57 | 58 | - MinterFilter: 59 | 60 | - Maintains a list of approved minters that can mint tokens for projects on the platform. 61 | - Assigns a specific minter to each project, which can be updated by the project's artist or the platform's Admin ACL. 62 | - Checks if the minter is the assigned minter for a project before allowing the token to be minted. 63 | - Checks that a project is on a registered Art Blocks Engine contract before allowing a minter to be assigned. 64 | 65 | - Minters: 66 | - Handles the token purchase process through the "purchase" and "purchaseTo" functions for specific projects. 67 | - Managed the maximum number of invocations (for the given minter) for each project. 68 | - Defines price information for tokens in a project, including token price in wei, currency symbol, and currency address. 69 | - Provides information about the minter type and associated core contract and MinterFilter addresses. 70 | 71 | tl;dr: The MinterFilter serves as a control layer that ensures the correct minter is used for each project, while Minters handle token purchase processes and project-specific settings. This division of responsibilities enables a secure, efficient, and flexible set of contracts that we call the "minter suite". 72 | 73 | For additional context, please check out [this architecture overview (with accompanying diagrams)](https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/MINTER_SUITE.md). 74 | 75 | **Legacy Minter Suite** 76 | 77 | The legacy minter suite is very similar to the new, shared minter suite, except that each minter filter and minter contract is connected to a single core contract. The general roles and responsibilities of the Minter Filter and Minter contracts are the same, except that they limit minting to a single core contract instead of a set of allowlisted core contracts. 78 | 79 | ## What is generative art? 80 | 81 | Generative art is about developing systems that define rules for creating art. By introducing randomness to those systems, core concepts are expressed through unique outputs. In a contemporary sense, this means writing computer algorithms to define the system and introduce randomness, which allows for conceptual exploration and rapid iteration. 82 | 83 | Creative coders write scripts with specific parameters that introduce and explore features, which generate the final outputs in a collection. With Art Blocks’ generative minting technology, collectors participate in the creation of the art. No one knows exactly what a piece will look like before it's minted, not even the artist. Each NFT is generated at the time of purchase using the buyer’s unique transaction hash to create a ‘1 of 1 of X’, which adds an extra layer of magic as the creator and collector watch a project come alive. 84 | 85 | The interesting part of modern generative art is that it involves working in series - often a large series. So instead of pursuing a single compelling work of art, a generative artist creates an algorithm capable of tens, hundreds, or thousands of compelling works of art. Which, when taken as a whole, expresses the range of possibilities contained in a single algorithm. 86 | 87 | ## What are NFTs? 88 | 89 | Nonfungible tokens (NFT) are unique digital assets stored on blockchain technology that can represent any digital or physical asset. 90 | 91 | ## On-chain vs. off-chain 92 | 93 | Art Blocks Engine enables creators to immutably store their generative NFT directly on the Ethereum blockchain (on-chain) or reference an external library or asset (off-chain). For an off-chain implementation, partners can reference external off-chain assets using decentralized storage solutions like IPFS. 94 | 95 | Decentralized and fully on-chain content is the most durable digital asset available. Typically, a creative coder writes a generative script in JavaScript and stores it directly on the blockchain. As long as you have access to a computer, a web browser, and Ethereum’s public ledger, you’ll always be able to reproduce the NFT in its original form and track ownership since creation. An on-chain NFT inherits the provenance, security, and durability of Ethereum itself, making them the highest quality digital asset available. 96 | 97 | So, if Art Blocks ever shut down, all on-chain work would still be accessible since it's stored on the decentralized Ethereum blockchain and able to be viewed, bought, sold, and transferred without involving Art Blocks at all. 98 | 99 | In contrast, if we store generative algorithms on an Art Blocks-owned database, the NFTs would rely on Art Blocks to return the assets - and if we go offline, the assets would not be retrievable. Similarly, if a script is stored on-chain but uses data from off-chain sources, it's vulnerable to the host of that off-chain data going offline. 100 | 101 | Off-chain NFTs rely on assets stored on external servers. There are many reasons to reference off-chain assets - data storage is expensive on Ethereum, and using external assets can reduce the cost of putting data on-chain. It also allows for interesting applications of generative art using external assets. However, if your NFT references external sources and those sources go offline, the NFT will only track ownership of unretrievable data. 102 | 103 | For this reason, we only allow certain external libraries to be used in project scripts given their general recognition as extremely reliable file storage sources. 104 | 105 | Art Blocks Engine offers on-chain and off-chain solutions with our generative NFT minting technology. Which one is right for you depends on your project’s goals and technical capabilities. 106 | 107 | ## Creating durable digital assets 108 | 109 | Creating on-chain generative NFTs ensures your collectors can expect their digital assets to stay the same forever. But if you choose to launch a generative project with off-chain assets, there are ways to mitigate the risk of going off-line using technology like IPFS or Arweave. We’re happy to chat about the right Art Blocks Engine implementation for your next project. 110 | 111 | ## Potential use-cases 112 | 113 | The landscape of on-demand generative content has plenty of room to experiment. Some of our current partners include artists, galleries, art houses, online publications, and game developers. If you’re exploring an interesting project, get in touch, and let’s build together. 114 | 115 | Current and upcoming use cases: 116 | 117 | - Fashion 118 | - Premier Artists 119 | - Media / Tech / Consumer brands 120 | - Gaming 121 | - Sports 122 | - BYOP - build your own platform 123 | -------------------------------------------------------------------------------- /art-blocks-engine-onboarding/index.yml: -------------------------------------------------------------------------------- 1 | icon: plug 2 | label: Art Blocks Engine Onboarding 3 | expanded: true 4 | route: /creator-docs/art-blocks-engine-onboarding/ -------------------------------------------------------------------------------- /core-contract-v3/dashboard.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 900 3 | --- 4 | 5 | # Creator Dashboard 6 | 7 | V3 core contracts may be managed by partners, artists and creators using the Art Blocks Creator Dashboard. The dashboard provides a user-friendly interface for managing projects, tokens, and other contract settings. The dashboard is accessible at [https://create.artblocks.io](https://create.artblocks.io). 8 | 9 | Various features are available to creators, including: 10 | 11 | - **Project Management**: Create, edit, and manage projects. 12 | - **Project Creation**: Add new projects to your contract. 13 | - **Payment Management**: Manage payment addresses, view current royalty splitter address, etc. 14 | -------------------------------------------------------------------------------- /core-contract-v3/erc2981-royalties.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 900 3 | --- 4 | 5 | # ERC-2981 Royalties 6 | 7 | For v3.2+ contracts (all Studio contracts, Engine contracts deployed after May 2024), Art Blocks contracts conform to the ERC-2981 standard for royalties. 8 | 9 | > Note: All versions of Art Blocks core contracts integrate seamlessly with the Royalty Registry, which is supported by all major secondary marketplaces. 10 | 11 | The ERC-2981 standard requires that royalty payments be made to a single address. Art Blocks contracts support this standard by integrating with 0xSplits to facilitate multi-party royalty payments to multiple addresses, all funneled through a single, permissionless, immutable "splitter contract" address. 12 | 13 | Artists may view their current royalty splitter address in the Art Blocks Creator Dashboard. The royalty splitter address is deployed and set automatically by the v3.2+ Art Blocks core contract when payment information is configured. A link to the current splitter is available in the dashboard, and distribution of funds in the splitter may be viewed and executed via the 0xSplits website. Note that 0xSplits provides a user-friendly interface for viewing splitter balances and executing distributions, as well as robust report generation tooling. 14 | 15 | > Note: 0xSplits is a third-party service and is not affiliated with Art Blocks. 16 | -------------------------------------------------------------------------------- /core-contract-v3/index.yml: -------------------------------------------------------------------------------- 1 | icon: coins 2 | label: Core Contract (V3) 3 | expanded: true 4 | route: /creator-docs/core-contract-v3/ 5 | -------------------------------------------------------------------------------- /core-contract-v3/manual-admin-operations.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 900 3 | --- 4 | 5 | # Manual Admin Operations 6 | 7 | Some rarely used admin operations are not available in the Art Blocks Creator Dashboard. These operations are available via direct interaction with the contract via a service such as Etherscan or Gnosis Safe's Transaction Builder. 8 | 9 | A few manual admin operations are detailed below. 10 | 11 | ## Update provider secondary royalties payment addresses or basis points 12 | 13 | > Note: this describes the process for updating provider secondary royalty information - artist updates are handled within the [Art Blocks Creator Dashboard](./dashboard.md). 14 | 15 | For all V3 contracts, the contract admin can update the provider secondary royalties payment addresses or basis points by calling any of the following functions on the contract: 16 | 17 | - `function updateProviderSalesAddresses` 18 | - `function updateProviderPrimarySalesPercentages` 19 | - `function updateProviderSecondarySalesBPS` or `function updateProviderDefaultSecondarySalesBPS` (depending on minor version) 20 | 21 | For v3.2+ contracts (deployed after May 2024), the contract admin must also propagate the contract-level changes to every project in the contract by calling the following function on the contract for each project: 22 | 23 | - `syncProviderSecondaryForProjectToDefaults(uint256 projectId)` 24 | 25 | > Note: The additional step of syncing provider secondary royalties to defaults was added in v3.2 to enable conformance to the ERC-2981 royalty info standard while remaining scalable within ethereum's block gas limit. 26 | -------------------------------------------------------------------------------- /core-contract-v3/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 1000 3 | --- 4 | 5 | # Overview of V3 Core Contract 6 | 7 | The Art Blocks V3 Core Contract allows Art Blocks Curated artists, Studio artists, and Engine partners to create generative art projects on the blockchain. The contract is a shared contract that allows for multiple projects to be created and managed by different artists and creators. The V3 Core Contract is designed to be flexible and extensible, allowing for a wide range of generative art projects to be created. 8 | 9 | ## Variants 10 | 11 | The V3 Core Contract comes in two variants: 12 | 13 | - V3 Engine 14 | - V3 Engine Flex 15 | 16 | Both of these implementations are available for use by Art Blocks Studio artists and Engine partners. 17 | 18 | The V3 Engine contract offers the same functionality as the original Art Blocks contract, with an artist's script being fully defined only on the blockchain. The V3 Engine Flex extends the ways artists may store additional metadata, with options of using reusable on-chain assets, using decentralized storage networks such as IPFS or Arweave, or pointing to assets defined on the Art Blocks Dependency Registry (some of which are fully defined on-chain, some of which are defined on preferred CDN services). 19 | 20 | For more discussion about different NFT metadata storage mechanisms, see the [NFT Metadata Storage at Art Blocks](/art-blocks-101/on-chain.md) page. 21 | -------------------------------------------------------------------------------- /creator-onboarding/creators.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: -200 3 | description: Updated location of Creator Onboarding documentation. 4 | --- 5 | 6 | # Moved! - Creator Onboarding Documentation 7 | 8 | !!! 9 | To keep things more up to date, we have moved the [Creator Onboarding documentation](https://help.artblocks.io/) to a new location. Navigate [there](https://help.artblocks.io/) for the most recent information! 10 | !!! 11 | -------------------------------------------------------------------------------- /creator-onboarding/index.yml: -------------------------------------------------------------------------------- 1 | icon: book 2 | label: Creator Onboarding 3 | route: /creator-docs/creator-onboarding/ -------------------------------------------------------------------------------- /favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/favicon.ico -------------------------------------------------------------------------------- /legacy.md: -------------------------------------------------------------------------------- 1 | --- 2 | route: /creator-docs/ 3 | redirect: /readme.md 4 | visibility: hidden 5 | --- -------------------------------------------------------------------------------- /minter-suite/custom-minters.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 850 3 | --- 4 | 5 | # Custom, One-Off Minters 6 | 7 | Some Engine partners may wish to add custom, one-off minters to the shared minter suite. This is able to be done by the admin of an Engine partner's core contract. 8 | 9 | !!!info 10 | Due to the high flexibility available to custom minters, they are not indexed by the Art Blocks subgraph, and therefore are not able to be configured by artists via the Art Blocks frontend. Instead, the custom minter will need to be configured via the Engine partner's frontend, etherscan, etc. 11 | !!! 12 | 13 | The steps to add a custom, one-off minter to the shared minter suite are as follows: 14 | 15 | ## 1. Write the custom minter contract 16 | 17 | The Engine partner will need to write the custom minter contract. The Art Blocks team can assist with providing guidance on how to translate a previously written, non-shared custom minter contract to be compatible with the new shared minter suite, if needed. 18 | 19 | At a minimum, the custom minter contract will need to implement the `ISharedMinterRequired` interface, which is available in the [Art Blocks smart contracts monrorepo](https://github.com/ArtBlocks/artblocks-contracts/blob/main/packages/contracts/contracts/interfaces/v0.8.x/ISharedMinterRequired.sol). This interface requires the custom minter contract to implement the following functions: 20 | 21 | ```js 22 | interface ISharedMinterRequired { 23 | // Function returns the minter type, and is called by the MinterFilter for 24 | // metadata purposes. 25 | function minterType() external view returns (string memory); 26 | 27 | // Function returns the minter's associated shared minter filter address, 28 | // and is called by subgraph indexing service for entity relation purposes. 29 | function minterFilterAddress() external returns (address); 30 | } 31 | ``` 32 | 33 | Additionally, the custom minter contract will need to call the `mint_joo` function on the shared minter filter contract to mint tokens. This function is included in the `IMinterFilterV1` interface in the [Art Blocks smart contracts monrorepo](https://github.com/ArtBlocks/artblocks-contracts/blob/7f0af6773fdd2c85ee33bfa5c3eeb39b57839131/packages/contracts/contracts/interfaces/v0.8.x/IMinterFilterV1.sol#L107). 34 | 35 | ```js 36 | interface IMinterFilterV1 { 37 | ... 38 | // @dev function name is optimized for gas 39 | function mint_joo( 40 | address to, 41 | uint256 projectId, 42 | address coreContract, 43 | address sender 44 | ) external returns (uint256); 45 | .... 46 | } 47 | ``` 48 | 49 | ## 2. Deploy the custom minter contract 50 | 51 | The Engine partner will need to deploy the custom minter contract to the desired network. 52 | 53 | ## 3. Allowlist the minter for the core contract on the shared minter filter contract 54 | 55 | The Engine partner will need to allowlist the custom minter contract for their contract, on the shared minter filter contract. This is done by doing the following: 56 | 57 | - Engine Admin calls `approveMinterForContract` on the shared minter filter contract, passing in the address of their core contract, and the custom minter contract 58 | 59 | The custom minter is now ready to be used by projects on the Engine partner's core contract! 60 | 61 | ## 4. Artist configures the custom minter for their project 62 | 63 | The artist will need to configure the custom minter for their project. Custom, one-off minters are not indexed by the Art Blocks subgraph (due to the minter being arbitrary and open-ended), so the artist will need to configure the custom minter via the Engine partner's frontend, etherscan, etc. Note that the typical minter filter function for setting a minter for a project, `setMinterForProject` should be used by the artist or admin to assign the custom minter for the project. 64 | -------------------------------------------------------------------------------- /minter-suite/index.yml: -------------------------------------------------------------------------------- 1 | icon: coins 2 | label: Minter Suite 3 | expanded: true 4 | route: /creator-docs/minter-suite/ 5 | -------------------------------------------------------------------------------- /minter-suite/minter-suite-supplemental.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: -10 3 | --- 4 | 5 | # Minter Suite Supplemental Information 6 | 7 | This page provides supplemental information for the Art Blocks Shared Minter Suite. 8 | 9 | The information below is generally most relevant for Engine core contract admins. 10 | 11 | --- 12 | 13 | ## Auction Reset Process 14 | 15 | A subset of minters utilizes automated, scheduled auctions to distribute artwork to collectors. The auction reset process is a mechanism that allows artists to pause and reschedule their auction, within certain limitations, if an issue arises during a live project release. Example situations may be: 16 | 17 | - Unexpected website downtime 18 | - Artist unintentionally left project in a paused state 19 | - Auction parameters were not set as intended 20 | 21 | Some of the possible failure modes above can result in a state where: 22 | 23 | - Collectors are not able to purchase tokens from the website 24 | - Bots are still able to purchase tokens by submitting transactions directly to the blockchain 25 | 26 | If in a state where bots can purchase but humans can not, the situation requires immediate action to prevent or minimize damage. 27 | 28 | ### 1. [URGENT] Pause the Auction 29 | 30 | The most important step in the auction reset process is for the Artist pause the auction. This prevents any further purchases from being made. 31 | 32 | Tips: 33 | 34 | - Ensure that the project is not already paused (i.e. this step is already complete), and do not toggle the pause button more than once (i.e. pause then unpause) 35 | - Artist should use a very high gas price to ensure that the pause transaction is mined quickly 36 | - Artist should use a tool like [Etherscan](https://etherscan.io/) to monitor the status of the pause transaction 37 | - Verify the paused state of the contract by checking the project's core contract on a tool like [Etherscan](https://etherscan.io/) 38 | 39 | !!!danger 40 | **DA with Settlement:** This step is especially urgent! Settlement minters require that every new purchase price is less than or equal to the previous purchase price (even after an auction is reset). If a bot purchases a token prior to a project being paused, that project’s reconfigured auction (even after reset) is constrained to only be able to start at the bot’s purchase price. 41 | !!! 42 | 43 | ### 2. Reset auction 44 | 45 | When using a Dutch auction, the auction will need to be reset and reconfigured. 46 | 47 | This is a 2-step process, and requires admin-intervention for security: 48 | 49 | 1. ADMIN - Call `resetAuctionDetails` on the minter contract 50 | 2. ARTIST - Configure the auction parameters via your typical process (e.g. artist dashboard) 51 | 52 | ### 3. Communicate and enjoy! 53 | 54 | Ensure your collectors are aware of the new auction parameters, and enjoy the new auction! 55 | 56 | --- 57 | 58 | ## Allowlist Minter Details (non-shared minter suite only) 59 | 60 | The Allowlist Minter uses a Merkle tree to gas-efficiently allow a set of addresses to mint tokens from a project. 61 | 62 | Merkle trees are a data structure that allows for efficient verification of whether a given element is contained in a set. In the case of the Allowlist Minter, the Merkle root is stored on-chain, and Merkle proofs are included with every purchase transaction to verify that a given address is allowed to mint a token. 63 | 64 | !!!info 65 | The information below is included to assist Engine partners in using the Allowlist minter with their projects. However, if using the shared minter suite, the Art Blocks subgraph and api are available to index Engine minter suite data, and this information is not required. 66 | !!! 67 | 68 | **Fundamentals** 69 | 70 | The Merkle allowlist minter follows the following basic process: 71 | 72 | - An allowlist of wallet addresses is stored off-chain (e.g. in a csv file) 73 | - The artist uploads the Merkle root of the list of addresses to the Minter contract via function `updateMerkleRoot` 74 | - Collectors calculate and include a Merkle proof with their purchase transaction to verify that their address is included in the allowlist 75 | 76 | **Example Usage** 77 | 78 | The following typescript code demonstrates how a Merkle root and proof may be calculated for a given allowlist: 79 | 80 | ```typescript 81 | // npm install merkletreejs 82 | import { MerkleTree } from "merkletreejs"; 83 | // npm install ethers 84 | import { keccak256, solidityKeccak256 } from "ethers/lib/utils"; 85 | 86 | const hashAddress = (address: string) => { 87 | return Buffer.from(solidityKeccak256(["address"], [address]).slice(2), "hex"); 88 | }; 89 | 90 | export const getMerkleRoot = (addresses: string[]): string => { 91 | const merkleTree = new MerkleTree( 92 | addresses.map((addr: string) => hashAddress(addr)), 93 | keccak256, 94 | { sortPairs: true } 95 | ); 96 | const root = merkleTree.getHexRoot(); 97 | return root; 98 | }; 99 | 100 | export const generateUserMerkleProof = ( 101 | addresses: string[], 102 | userAddress: string 103 | ): string[] => { 104 | const merkleTree = new MerkleTree( 105 | addresses.map((addr) => hashAddress(addr)), 106 | keccak256, 107 | { 108 | sortPairs: true, 109 | } 110 | ); 111 | return merkleTree.getHexProof(hashAddress(userAddress)); 112 | }; 113 | 114 | /////////////////////////////////////////////////////////////////////////////// 115 | // EXAMPLE USAGE 116 | /////////////////////////////////////////////////////////////////////////////// 117 | 118 | // allowlist could be fetched from a database or a file 119 | // example allowlist addresses 120 | const allowlistAddresses = [ 121 | "0xaE839a65A8AA0E54323d7Eda4c5d77562fCBCBC0", 122 | "0x9d688d290d9CdD2a8f8040B48C6d40d039B2b8ba", 123 | "0x4CFA1e7a4cF5Eb5a0Dd0460F431d8e96155d8611", 124 | "0x09e2978EF8638CBc564D2E34325734B42F654DBe", // ... and so on 125 | ]; 126 | console.log("Allowlist addresses: ", allowlistAddresses); 127 | 128 | // Generate the Merkle root for artist to upload to the minter contract 129 | const merkleRoot = getMerkleRoot(allowlistAddresses); 130 | console.log("Merkle root: ", merkleRoot); 131 | // Generate the bytes32[] Merkle proof for a user to be included in the purchase transaction 132 | // example user address: 0xaE839a65A8AA0E54323d7Eda4c5d77562fCBCBC0 133 | const merkleProof = generateUserMerkleProof( 134 | allowlistAddresses, 135 | "0xaE839a65A8AA0E54323d7Eda4c5d77562fCBCBC0" 136 | ); 137 | console.log( 138 | "Merkle proof for 0xaE839a65A8AA0E54323d7Eda4c5d77562fCBCBC0: ", 139 | merkleProof 140 | ); 141 | ``` 142 | 143 | --- 144 | 145 | ## Pre-Assigning Token Hash Seeds 146 | 147 | !!!info 148 | The shared randomizer `SharedRandomizerV0` enables an artist to pre-assign token hash seeds for tokens on a project. This allows an artist to assign a specific hash seed to a token before it is minted, and then mint the token with that hash seed at a later time. 149 | !!! 150 | 151 | The process for pre-assigning token hash seeds is as follows: 152 | 153 | 1. Identify and confirm that your contract is using a `SharedRandomizerV0` contract. Visit your core contract on etherscan (or appropriate L2 explorer, e.g. basescan) and inspect the read-only function `randomizerContract()` to confirm that the randomizer contract is a `SharedRandomizerV0`. 154 | 155 | 1. Navigate to the `SharedRandomizerV0` contract on etherscan (or appropriate L2 explorer, e.g. basescan), and connect your artist wallet. Alternatively, if your artist wallet is a multisig, interact with the `sharedRandomizerV0` in something like Gnosis Safe's Transaction Builder (this is more efficient and convenient when assigning hash seeds for many tokens). 156 | 157 | 1. On `SharedRandomizerV0`, call the `toggleProjectUseAssignedHashSeed()` function with the artist wallet the following parameters: 158 | 159 | - `coreContract`: The address of the core contract for the project 160 | - `ProjectId`: The ID of the project to toggle the use of assigned hash seeds for 161 | 162 | 1. Confirm on `SharedRandomizerV0`'s read function `projectUsesHashSeedSetter()` that the project is now configured to use pre-assigned hash seeds (should return `true`). 163 | 164 | 1. On `SharedRandomizerV0`, from the artist wallet, call to the `setHashSeedSetterContract` function with the following parameters: 165 | 166 | - `coreContract`: The address of the core contract for the project 167 | - `ProjectId`: The ID of the project to toggle the use of assigned hash seeds for 168 | - `hashSeedSetterContract`: The address that will assign hash seeds to tokens - recommend in this use-case to set this to the artist wallet 169 | 170 | 1. Confirm on `SharedRandomizerV0`'s read function `hashSeedSetterContracts()` that the hash seed setter contract is now set to the artist wallet for the project. 171 | 172 | 1. On `SharedRandomizerV0`, from the artist wallet, call `preSetHashSeed()` for each token that you want to assign a hash seed to (Multicall using something like a gnosis safe is very helpful if assigning many tokens here). This function takes the following parameters: 173 | 174 | - `coreContract`: The address of the core contract for the project 175 | - `tokenId`: The token ID to assign the hash seed for 176 | - `hashSeed`: The hash seed to assign to the token 177 | 178 | 1. You may confirm that token hash seeds have been properly assigned by calling the `preAssignedHashSeed()` read-only function on `SharedRandomizerV0` with the following parameters: 179 | 180 | - `coreContract`: The address of the core contract for the project 181 | - `tokenId`: The token ID to check the hash seed for 182 | 183 | 1. MINT! Ordering may be critical if minting specific tokens to specific addresses, so the artist may need to keep the project paused and call purchaseTo in a specific order. No other changes to the minting process are required. Confirming token hashes are as expected along the way is highly recommended. 184 | 185 | 1. After minting is complete, the artist should call `toggleProjectUseAssignedHashSeed()` to disable the use of assigned hash seeds for the project, and allow the randomizer to pseudorandomly assign hash seeds to tokens as normal. 186 | 187 | 1. Set the hash seed setter contract back to the zero address by calling `setHashSeedSetterContract` from the artist wallet. 188 | 189 | !!!info 190 | The steps above follow the pattern implemented in the following test case: [shared-randomizer-v0/configure.test.ts:assigns_expected_token_when_polyptych"](https://github.com/ArtBlocks/artblocks-contracts/blob/1d2a6ad5915cb225c6b0d31710568a439b0e212b/packages/contracts/test/randomizer/shared-randomizer-v0/configure.test.ts#L269) 191 | !!! 192 | -------------------------------------------------------------------------------- /minter-suite/minting-philosophy.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 1000 3 | description: An overview of minting philosophy at Art Blocks. 4 | --- 5 | 6 | # Minting Philosophy 7 | 8 | An overview of the generative art minting philosophy at Art Blocks. 9 | 10 | ## Introduction 11 | 12 | At Art Blocks, minting is a particularly special occasion where a new generative art piece is created. It is the final step in the generative art creation process, and enables collectors to partner with artists to create a unique, one-of-a-kind piece of generative art! 13 | 14 | On a blockchain, "minting" is the process of creating new tokens. So not only is minting the process of creating new generative art pieces, it is also the process of creating new tokens on a blockchain. Typically, minting is also the point where a collector will pay for the generative art piece. 15 | 16 | A few key points about minting at Art Blocks: 17 | 18 | - Minting is the process of creating new generative art pieces. 19 | - Minting is the process of creating new tokens on a blockchain. 20 | - Minting generally involves a collector paying for the right to create a generative art piece. 21 | 22 | ## Core Principles 23 | 24 | At Art Blocks, we are committed to providing a transparent minting toolkit for artists, and a transparent minting experience for collectors. 25 | 26 | The following principles, when used together, are important ideals that we believe enable artists to achieve some sort of ["fairness"](#fairness) during their drop. They also are key to collector safety when interacting on a blockchain. 27 | 28 | #### 1. Transparency 29 | 30 | We believe that minting should be transparent and easy to understand for collectors. Verified source code is provided for all minter smart contracts, and we develop our minters publicly in our open source [GitHub repository](https://github.com/ArtBlocks/artblocks-contracts). 31 | 32 | #### 2. Decentralized & Trust-Minimized 33 | 34 | We believe that minting should rely heavily on immutable smart contract code deployed to decentralized networks, and should be as trustless as possible. We aim to minimize the amount of trust in any centralized party when minting. This is important because collectors must feel safe when purchasing high-value generative art pieces, and trusting a centralized party to mint a generative art piece is often not an acceptable option. 35 | 36 | Of course Artists and Art Blocks will have some elevated privileges, such as configuring auctions, but we aim to minimize those privileges and implement only when necessary. Those privileges will be documented and transparent, and should align incentives. 37 | 38 | #### 3. Non-Custodial 39 | 40 | Minting should be a transaction between the collector and the minter smart contract, and the contract should handle logic related to settlements, price changes over time, etc. 41 | 42 | The minter smart contract should empower the collector to make their own decisions, and should not be custodial in nature. 43 | 44 | #### 4. Honest 45 | 46 | Blockchains have a unique set of technical quirks that can be exploited by opportunistic or malicious actors. These result in frequent discussions about bots, "flipping", and front-running. 47 | 48 | We are committed to providing solutions to help alleviate these issues, but we are also committed to being honest about their limitations. Solutions must have sound fundamentals, and ones that only hide or obfuscate minting bots or other issues are not real solutions, and therefore should not be implemented. See the [Lessons Learned](#lessons-learned) section for more examples of this. 49 | 50 | #### 5. Flexible 51 | 52 | In some situations, a project may desire to mint in a way that is highly centralized or in some other non-traditional manner. An example of this would be a project that utilizes in-person minting at an event. In this case, the project may choose to mint from a single, centralized mobile device, but should be transparent about that decision. 53 | 54 | ## "Fairness" Ideals 55 | 56 | Fairness is a concept that is often discussed in the context of minting, and is worth investigating in some amount of nuance. 57 | 58 | In an abstract sense, fairness is easy to define. Merriam-Webster defines fairness as: 59 | 60 | > "marked by impartiality and honesty: free from self-interest, prejudice, or favoritism". 61 | 62 | In practice, however, fairness of a project's mint is much more difficult to define. In one sense, Art Blocks drops are _entirely fair_: 63 | 64 | - Open sale at a defined price or auction 65 | - Mint success is determined by transaction time/order 66 | - Transaction confirmation time is determined by the network's gas price auction 67 | 68 | In another sense, there are many different ways to define fairness, and each definition has its own set of tradeoffs. In general, we believe there are a few types of fairness that are important to consider when an artist is considering how to distribute their project to collectors: 69 | 70 | #### 1. Capitalist Fairness 71 | 72 | Capitalist fairness suggests that those who are willing to pay the most for a given drop should be the ones who are able to participate. 73 | 74 | An example of a drop paradigm that is capitalist fair is a Dutch auction. In a Dutch auction, the price of a generative art piece starts high, and decreases over time until a collector is willing to pay the price. This ensures that the collector who is willing to pay the most for a generative art piece is the one who is able to mint it. 75 | 76 | #### 2. Insider Fairness 77 | 78 | Insider fairness suggests that those within an existing community should be the ones who are able to participate. 79 | 80 | An example of a drop paradigm that is insider fair is an allowlist. In that paradigm, a collector must have reached out to an artist before the project was released to be allowed to mint. This ensures that the collector who is most involved and interested in a community is the one who is able to mint a generative art piece. 81 | 82 | #### 3. Communist Fairness 83 | 84 | Communist fairness suggests that all collectors should have an equal chance to participate, regardless of their technical skills or willingness to pay. 85 | 86 | An example of a drop paradigm that optimizes for communist fairness would be a pure lottery, where all collectors have an equal chance to mint a generative art piece. This ensures that all collectors have an equal chance to mint a generative art piece. 87 | 88 | ## Fairness in Practice 89 | 90 | In practice, it is difficult to achieve any of the above definitions of fairness in a pure sense. For example, a pure lottery is not possible on Ethereum, because the network is not able to discern humans from bots, and therefore a pure lottery would be susceptible to bots spamming entries and disproportionately winning the lottery. 91 | 92 | Art Blocks aims to provide a variety of minting options for artists to choose from, each with their own set of tradeoffs. We believe that artists should be able to choose the minting paradigm that best fits their project's goals. 93 | 94 | The minters provided by Art Blocks are intended to follow our design principles while also achieving some kind of fairness. However, each minter's amount of fairness and susceptibility to bots will vary based on: 95 | 96 | - project demand/hype 97 | - project price 98 | - market conditions 99 | - gas prices 100 | - etc. 101 | 102 | For example, if a highly-anticipated project is sold at a low fixed-price, it is likely that bots will be able to mint a large number of generative art pieces. However, if a less-anticipated project is sold at a fixed-price, it is likely that bots will not mint a large number of generative art pieces because the speculative value of the generative art piece is not high enough to flip for a short-term profit. 103 | 104 | The minters provided by Art Blocks are not inherently fair or unfair in nature, but when used carefully, they can provide a minting experience that stays true to our principles while also providing some amount of fairness. We believe that it is important for artists to understand the tradeoffs of each minter, and to choose the minter(s) that best fits their project's goals. 105 | 106 | ## Minter Suite 107 | 108 | The minter suite is a collection of smart contracts that aim to provide different options for artists to distribute their project's tokens to collectors. A variety of minters are available for artists to choose from that can be used to create a variety of different minting experiences. The minters are designed to be flexible and extensible, but also to provide a consistent and familiar minting experience for collectors. 109 | 110 | The shared minter suite is used by Art Blocks, and is also available for use with Art Blocks Engine contracts (V3 only). 111 | 112 | More details will be added regarding the shared minter suite in the future, but for now, please see the [Shared Minter Suite](./shared-minter-suite) page for an overview of all available flagship minters at this time. 113 | 114 | ## Lessons Learned 115 | 116 | Below is a collection of lessons that we have learned from our experience with minting generative art pieces on Ethereum. 117 | 118 | ### One mint per wallet does not prevent bots (without an allowlist) 119 | 120 | In the past, we have implemented a "1 mint per wallet" rule, which was intended to prevent bots from minting a large number of generative art pieces. However, this rule was not effective, and actually gave an advantage to bots. 121 | 122 | For a botter, minting from 1 or 100 wallets is nearly the same difficulty. However, for a typical collector not using bots, minting from multiple wallets adds a lot of difficulty. Ultimately, the "1-per" restriction puts the average collector at a huge disadvantage relative to a botter. 123 | 124 | The "1 mint per wallet" rule is also somewhat misleading because it may lead collectors to believe that a project's distribution is well-diversified, when in reality, it might only be owned by a network of bots operating at many addresses. 125 | 126 | In the end, this rule was not effective, harmed less-technical collectors, and was therefore abandoned. 127 | 128 | > Note: Limiting the number of mints per wallet on an allowlist is a different paradigm, and is a valid way to limit the number of mints per wallet. 129 | 130 | ### Disabling minting from smart contracts does not prevent bots 131 | 132 | In the past, we have implemented a rule that prevented minting from smart contracts. This was intended to prevent bots from minting a large number of generative art pieces. However, this rule was not effective, because bots are able to mint from EOAs (externally owned accounts), and therefore are still able to mint a large number of generative art pieces. 133 | 134 | The "no minting from smart contracts" rule is also somewhat misleading because it may cause collectors to believe that a project's was bot-resistant, when in reality, it is not an effective way to prevent bots from minting. 135 | 136 | In the end, this rule was not effective, harmed collectors that wanted to mint from a smart contract (including from security-forward multi-sig wallets such as Gnosis Safe), and was therefore abandoned. 137 | 138 | ### One mint per transaction does not prevent bots 139 | 140 | This is a rule that is implemented by some NFT projects, and is intended to prevent bots from minting a large number of generative art pieces. However, this rule is not effective, because bots are able to mint a large number of generative art pieces by submitting multiple transactions to the network's pending transaction pool. 141 | 142 | Additionally, most implementations of this rule prevent minting from smart contracts, which is harmful to collectors that want to mint from multi-sig wallets. Other solutions require collectors to pay for additional gas fees for on-chain storage to support the rule's logic, which is also harmful to collectors. 143 | 144 | In the end, this rule is not effective, harms less-technical and/or security-conscious collectors, and was therefore abandoned. 145 | 146 | ### Low, fixed prices favor bots 147 | 148 | In general, low, fixed prices favor bots because they are able to mint a large number of generative art pieces and flip them for a short-term profit. This is especially true when the project is highly-anticipated, and when the project's generative art pieces are expected to have a high speculative value. 149 | 150 | Bots have a large advantage over humans when it comes to minting at low, fixed prices, because they are able to submit transactions to the network's pending transaction pool at a high rate, and are able to pay high gas prices to ensure that their transactions are confirmed quickly. 151 | 152 | In general, we recommend that artists consider using a Dutch auction or an allowlist to mitigate the effects of bots when minting at low, fixed prices. 153 | -------------------------------------------------------------------------------- /minter-suite/seadrop-integration.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: -20 3 | --- 4 | 5 | # SeaDrop Integration 6 | 7 | This page provides an overview of an integration solution for the Art Blocks Shared Minter Suite with OpenSea's SeaDrop system. This is a special integration that allows Art Blocks projects to be minted and sold on OpenSea via SeaDrop, and is not a standard integration with the Shared Minter Suite. 8 | 9 | The integration requires a few non-standard steps to ensure that the SeaDrop contract can interact with the minter suite. The steps below outline the process for integrating SeaDrop with the Art Blocks Shared Minter Suite. 10 | 11 | --- 12 | 13 | ## Integration Process 14 | 15 | The integration process follows the custom, one-off minter steps, and supports minting on any project that uses the Shared Minter Suite. 16 | 17 | ### 1. Artist configures their project 18 | 19 | The artist configures their project as they normally would, using the [Art Blocks Creator Dashboard](https://create.artblocks.io). 20 | 21 | The only exception is that the artist does not need to configure the minter for their project, as the minter will be configured separately as described in the following steps. 22 | 23 | ### 2. Deploy `SeaDropXArtBlocksShim` Contract 24 | 25 | The `SeaDropXArtBlocksShim` contract is a custom contract that allows the SeaDrop contract to interact with the Shared Minter Suite. This contract must be deployed for each project that will be integrated with SeaDrop, in order to satisfy a 1:1 mapping between the shim contract and the project. 26 | 27 | Deployment of the `SeaDropXArtBlocksShim` contract is a one-time process for each project, and may be deployed by anyone. Deployment of the shim contract requires the following parameters: 28 | 29 | ```solidity 30 | constructor( 31 | IMinterFilterV1 minterFilter_, 32 | ISeaDrop allowedSeaDrop_, 33 | IGenArt721CoreContractV3_Base genArt721Core_, 34 | uint256 projectId_ 35 | ) 36 | ``` 37 | 38 | > Note: The `allowedSeaDrop_` parameter should be set to the address of the SeaDrop contract that will be used for the project, defined by OpenSea here: https://github.com/ProjectOpenSea/seadrop/blob/main/README.md#deployments 39 | 40 | ### 3. Admin approve minter for contract 41 | 42 | Following the custom, one-off minter steps, the admin must approve the minter for the project's core contract. 43 | 44 | Engine Admin calls `approveMinterForContract` on the shared minter filter contract (via e.g. etherscan or gnosis safe tx builder), passing in the address of their core contract, and the `SeaDropXArtBlocksShim` custom minter contract 45 | 46 | ### 3. Artist configures the custom minter for their project 47 | 48 | Following the custom, one-off minter steps, the artist will need to configure the custom minter for their project. The artist will need to configure the custom minter via etherscan, etc. Note that the typical minter filter function for setting a minter for a project, `setMinterForProject` should be used by the artist or admin to assign the custom minter for the project. 49 | 50 | ### 4. Artist configures their drop on OpenSea's Studio 51 | 52 | The artist will need to configure their drop on OpenSea's Studio. 53 | 54 | A general guide for configuring a drop on OpenSea Studio is published by OpenSea here: https://docs.opensea.io/docs/part-2-edit-collection-settings 55 | 56 | In OpenSea Studio, the artist should see a new contract available to edit, which will be the `SeaDropXArtBlocksShim` contract. The artist should configure the drop as they normally would, using the OpenSea Studio interface. 57 | 58 | A few options that don't make sense for Art Blocks projects, such as IPFS metadata (Art Blocks projects are on-chain), should be left blank. 59 | 60 | If SeaDrop is configured to sell less tokens than the project's max invocations, minting on OpenSea will be limited to whatever is configured in SeaDrop. 61 | 62 | !!!warning 63 | Important: The artist must set their primary sales payment address on OpenSea Studio in a manner that properly splits the payment between the artist and the platform and/or render provider. A manually created splitter contract (e.g. using 0xSplits) may be an appropriate solution. Secondary sales will be handled automatically by the Art Blocks Core contract, but primary sales **must** be configured correctly in SeaDrop by the artist. 64 | !!! 65 | 66 | ### 5. Notify OpenSea of the integration 67 | 68 | The artist should notify Art Blocks and OpenSea of the integration, so that the OpenSea team can ensure that the integration is properly displayed on their website. The shim contract must be properly configured to point to the correct project ID for items to intuitively show up in the OpenSea UI. 69 | 70 | ### 6. Enjoy! 71 | 72 | Your Art Blocks tokens are now available for sale on OpenSea via SeaDrop! 73 | 74 | --- 75 | 76 | ## Shim Contract Details 77 | 78 | The diagram below illustrates the relationship between different entities and the `SeaDropXArtBlocksShim` contract, the Shared Minter Suite, and the SeaDrop contract. 79 | 80 | ```mermaid 81 | --- 82 | title: Art Blocks x Sea Drop Integration Solution 83 | --- 84 | flowchart LR 85 | SeaDrop --mint--> SeaDropXArtBlocksShim 86 | id2((admin)) --approve-minter-for-contract--> SharedMinterFilter 87 | SeaDropXArtBlocksShim --mint--> SharedMinterFilter 88 | SharedMinterFilter --mint--> GenArt721 89 | SeaDropXArtBlocksShim --read--> GenArt721 90 | id1((artist)) --configures drop (OpenSea-UI)--> SeaDropXArtBlocksShim 91 | id1 --configures project--> GenArt721 92 | id1 --set-project-minter--> SharedMinterFilter 93 | id3((collector)) --purchase--> SeaDrop 94 | ``` 95 | -------------------------------------------------------------------------------- /minter-suite/shared-minter-suite.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 851 3 | --- 4 | 5 | # Shared Minter Suite 6 | 7 | This page provides an overview of the Art Blocks Shared Minter Suite, which enables artists to choose how they distribute their artwork to collectors. 8 | 9 | The Shared Minter Suite is available for all projects, including Art Blocks Engine projects. 10 | 11 | !!!info 12 | For legacy contracts, core contract admins can view the [Minter Migration Runbok](./../art-blocks-engine-onboarding/art-blocks-engine-101/minter-suite-migration-runbook.md) for details about how to migrate to the shared minter suite. 13 | !!! 14 | 15 | ## Mix-and-Match 16 | 17 | Artists can mix-and-match minter options to create a custom minter configuration for their project. For example, an artist could initially use the allowlist minter to allow a specific set of collectors to mint one token per allowlisted wallet, and then could open up minting to the public via a switch to a Dutch auction with settlement minter. 18 | 19 | Each minter supports limiting to a certain number of project invocations. For example, an artist could allow Minter A to be used for the first 1000 project invocations, and then switch to Minter B for the remaining project invocations. 20 | 21 | ## Globally Available Minter Options 22 | 23 | The current available Minter options are discussed below. We are continually expanding our shared minter suite over time. 24 | 25 | ### `Set price - ETH` 26 | 27 | The set price minter is used for fixed price releases. It is the simplest minter and prices all tokens at the same price, in ETH. 28 | 29 | ### `Set price - ETH, allowlisted users only` 30 | 31 | Extends the functionality of the `Set price, ETH` minter to allow only wallets on an allowlist to mint. The allowlist can be configured to limit minting to a predetermined list of wallet addresses, and artists can specify the number of mints allowed per wallet. 32 | 33 | ### `Set price - ETH, token holders only` 34 | 35 | Extends the functionality of the `Set price, ETH` minter to allow only holders of a specific ERC-721 token to mint. 36 | 37 | ### `Set Price - custom ERC20` 38 | 39 | Set price in ERC20 is a fixed price minter that allows accepting any ERC20 token as payment for your sale of tokens. 40 | 41 | Custom ERC20 tokens can be used for a variety of purposes, including for a "mint pass" style experience. 42 | 43 | ### `Dutch auction (w/settlement) - exponential price decrease` 44 | 45 | When this minter is used, all collectors will pay the same net-price as the final purchaser. This is typically the most fair and equitable Dutch auction type for buyers because all buyers pay the same price, making it a great auction type for many projects. 46 | 47 | Collectors who purchase above the lowest price will be able to claim a settlement after the auction. The settlement will be the difference between the price they purchased at and the final purchase price. All funds are held non-custodially by the smart contract until the auction ends and revenues are collected by the artist or admin. 48 | 49 | Exponential price curves approximate a constant percent decrease over time, making them a popular choice for Dutch auctions. 50 | 51 | !!!info 52 | If an artist reduces the max supply of their project mid-auction, and the project sells out above auction base price, revenues must be withdrawn by core contract admin. This was implemented to protect collectors from an artist unilaterally potentially inflating sellout price during an action, and immediately withdrawing revenues. Admin concurrence is required to withdraw revenues in this case. 53 | !!! 54 | 55 | !!!info 56 | For supplemental information about the auction reset process, please see the [Auction Reset Process](./minter-suite-supplemental.md#auction-reset-process) section. 57 | !!! 58 | 59 | ### `Dutch auction - exponential price decrease` 60 | 61 | For Dutch auctions without settlement, artists specify the starting price, ending price, and the half-life for price drops. Collectors will pay more for tokens purchased earlier in the auction, and less for tokens purchased later in the auction. 62 | 63 | Exponential price curves approximate a constant percent decrease over time, making them a popular choice for Dutch auctions. 64 | 65 | !!!info 66 | For supplemental information about the auction reset process, please see the [Auction Reset Process](./minter-suite-supplemental.md#auction-reset-process) section. 67 | !!! 68 | 69 | ### `Dutch auction - linear price decrease` 70 | 71 | For Dutch auctions without settlement, artists specify the starting price, ending price, and the duration of the auction. Collectors will pay more for tokens purchased earlier in the auction, and less for tokens purchased later in the auction. 72 | 73 | Linear price curves provide a constant price decrease over time. 74 | 75 | Two price curves are available for Dutch auctions without settlement: exponential and linear. Exponential price curves approximate a constant percent decrease over time, while linear price curves provide a constant price decrease over time. 76 | 77 | !!!info 78 | For supplemental information about the auction reset process, please see the [Auction Reset Process](./minter-suite-supplemental.md#auction-reset-process) section. 79 | !!! 80 | 81 | ### `Dutch auction - exponential price decrease, token holders only` 82 | 83 | This minter extends the functionality of the Dutch auction minter to allow only holders of a specific ERC-721 token to mint. 84 | 85 | ### `Dutch auction - linear price decrease, token holders only` 86 | 87 | This minter extends the functionality of the Dutch auction minter to allow only holders of a specific ERC-721 token to mint. 88 | 89 | ### `Ranked auction` 90 | 91 | The Ranked Auction minter allows for a ranked auction process where collectors can submit bids for a limited number of tokens. The highest bidders will receive tokens, while losing bidders will receive a refund. 92 | 93 | All winning bids pay the same price, which is the lowest winning bid. 94 | 95 | The ranked auction process happens non-custodially on-chain, and is scalable to arbitrarily large projects. Artists may incur gas costs associated with minting tokens for winning bidders. 96 | 97 | ### `Serial English auction` 98 | 99 | The Serial English Auction (SEA) minter allows for a series of English auctions for individual tokens to be run in sequence. The minter was originally inspired by the popular [nouns.wtf](https://nouns.wtf/) project, and was implemented with minor adjustments to provide a seamless experience for Art Blocks artists and collectors. 100 | 101 | Artists may configure future token auction parameters, such as starting auction price and minimum auction length. Collectors may then kick off token auctions by submitting a bid for a pre-minted token. Once an auction begins, any wallet may submit a higher bid for the token up for sale. Losing bids are refunded automatically when outbid. If a bid is submitted near the end of an auction, the auction is extended such that a human is able to submit a higher bid, ensuring a human can fairly compete against a bot. 102 | 103 | Once an auction is complete, another token auction may be started by any collector submitting a bid for the next token, while also sending the previous auction winner their token. 104 | 105 | The minter pre-mints tokens before their auction, so bids are placed on an already-existing token, not on hypothetical tokens. 106 | 107 | The minter may be used for any project, and is certainly ideal for projects that have a series of tokens that are released in a sequence. It may also be used to auction off a 1:1 token. The minter is also ideal for projects that have a strong community, as it allows for community members to participate in the auction process over a long period of time, carefully considering each generative output. 108 | 109 | Bids and auction parameters are stored on-chain, and the Art Blocks subgraph and API index all historical bids in [`bids_metadata`](https://docs.artblocks.io/public-api-docs/#definition-bids_metadata) as well as auction parameters in [`project_minter_configurations`](https://docs.artblocks.io/public-api-docs/#definition-project_minter_configurations). 110 | 111 | ### `Minimum price minter` 112 | 113 | This minter enables artists to distribute tokens at a minimal price to collectors. 114 | 115 | A small mint fee is sent to the render provider to help with the costs of rendering and indexing tokens. 116 | 117 | ## `Minimum price minter, allowlisted users only` 118 | 119 | This minter enables artists to distribute tokens at a minimal price to an allowlisted set of collectors. The allowlist can be configured to limit minting to a predetermined list of wallet addresses, and artists can specify the number of mints allowed per wallet. 120 | 121 | A small mint fee is sent to the render provider to help with the costs of rendering and indexing tokens. 122 | 123 | ### `Polyptych (copy-hash) minter` 124 | 125 | This minter enables the artist to mint tokens with identical token hashes. This is useful for projects that are intended to be displayed as a polyptych. 126 | 127 | This minter allows either artists to mint child tokens to a parent token holder's wallet, or allows the parent token holder to mint child tokens. 128 | 129 | An artist's script must work closely with the minter to ensure that the correct frame is used for each token number. For example, if a project has 3 frames, the artist's script must ensure that e.g. tokens 0-99 are minted with frame 1, tokens 100-199 are minted with frame 2, and tokens 200-299 are minted with frame 3. The artist is able to increment the frame number for their project on the minter. 130 | 131 | This minter is technically complex, and artists must also configure the shared randomizer when using this minter. 132 | 133 | Limited creator dashboard support is available for this minter at this time, so some interactions with the minter must be done via a service such as [Etherscan]](https://etherscan.io/). 134 | 135 | Despite the complexity of this minter, the resulting outputs can be very powerful and rewarding for artists and collectors! 136 | 137 | ### `Polyptych (copy-hash) minter, custom ERC20` 138 | 139 | This minter extends the functionality of the polyptych minter to allow accepting any ERC20 token as payment for your sale of tokens. 140 | 141 | ## Custom, One-Off Minters 142 | 143 | Engine partners can also create custom, one-off minters for their projects. These minters are only available to projects on the Engine contract that approves them, extending the globally set of available minters for their contract. 144 | 145 | For more information about adding custom minters to your Engine contract, please see the [custom minters page](./custom-minters). 146 | -------------------------------------------------------------------------------- /retype.yml: -------------------------------------------------------------------------------- 1 | input: . 2 | output: .retype 3 | url: docs.artblocks.io 4 | 5 | branding: 6 | title: Art Blocks 7 | label: Docs 8 | logo: static/squigLogo.png 9 | 10 | integrations: 11 | googleAnalytics: 12 | id: G-NGMHL6GNM0 13 | 14 | edit: 15 | repo: https://github.com/ArtBlocks/artblocks-docs 16 | 17 | links: 18 | - text: Art Blocks 19 | link: https://artblocks.io/ 20 | icon: home 21 | 22 | - text: Docs 23 | link: /readme.md 24 | icon: file 25 | 26 | - text: Wiki 27 | link: https://artblocks.wiki/ 28 | icon: book 29 | 30 | footer: 31 | copyright: "© Copyright {{ year }}. All rights reserved." 32 | 33 | poweredByRetype: false 34 | -------------------------------------------------------------------------------- /static/Filebase_setup1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Filebase_setup1.png -------------------------------------------------------------------------------- /static/Filebase_setup2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Filebase_setup2.png -------------------------------------------------------------------------------- /static/Filebase_setup3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Filebase_setup3.png -------------------------------------------------------------------------------- /static/Filebase_setup4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Filebase_setup4.png -------------------------------------------------------------------------------- /static/Filebase_setup5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Filebase_setup5.png -------------------------------------------------------------------------------- /static/Filebase_setup6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Filebase_setup6.png -------------------------------------------------------------------------------- /static/Pinata_setup_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Pinata_setup_1.png -------------------------------------------------------------------------------- /static/Pinata_setup_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Pinata_setup_2.png -------------------------------------------------------------------------------- /static/Pinata_setup_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Pinata_setup_3.png -------------------------------------------------------------------------------- /static/Pinata_setup_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Pinata_setup_4.png -------------------------------------------------------------------------------- /static/Pinata_setup_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/Pinata_setup_5.png -------------------------------------------------------------------------------- /static/getDependencyDetails.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/getDependencyDetails.png -------------------------------------------------------------------------------- /static/getDependencyScript.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/getDependencyScript.png -------------------------------------------------------------------------------- /static/onChainHtml.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/onChainHtml.png -------------------------------------------------------------------------------- /static/onChainSquig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/onChainSquig.png -------------------------------------------------------------------------------- /static/projectDetails.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/projectDetails.png -------------------------------------------------------------------------------- /static/projectScriptByIndex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/projectScriptByIndex.png -------------------------------------------------------------------------------- /static/projectScriptInfo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/projectScriptInfo.png -------------------------------------------------------------------------------- /static/screenshot1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/screenshot1.png -------------------------------------------------------------------------------- /static/screenshot2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/screenshot2.png -------------------------------------------------------------------------------- /static/screenshot3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/screenshot3.png -------------------------------------------------------------------------------- /static/screenshot4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/screenshot4.png -------------------------------------------------------------------------------- /static/squigLogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/squigLogo.png -------------------------------------------------------------------------------- /static/tokenHash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ArtBlocks/artblocks-docs/2b7e786f44312e9b1e63f885fd6742baed6ccce1/static/tokenHash.png --------------------------------------------------------------------------------