{"id":15010193,"url":"https://github.com/jbx-protocol/juice-721-delegate","last_synced_at":"2025-10-19T12:54:37.235Z","repository":{"id":41281997,"uuid":"508756877","full_name":"jbx-protocol/juice-721-delegate","owner":"jbx-protocol","description":"Juicebox pay delegate for tiered NFTs (ERC-721)","archived":false,"fork":false,"pushed_at":"2024-04-09T20:02:44.000Z","size":168103,"stargazers_count":24,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T10:45:21.151Z","etag":null,"topics":["ethereum","juicebox","juicebox-delegate","solidity"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@jbx-protocol/juice-721-delegate","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbx-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-29T15:55:55.000Z","updated_at":"2024-04-15T12:55:50.208Z","dependencies_parsed_at":"2024-04-15T12:55:37.923Z","dependency_job_id":"0a7a3ad4-437a-4c13-9047-b77a113cc834","html_url":"https://github.com/jbx-protocol/juice-721-delegate","commit_stats":{"total_commits":775,"total_committers":7,"mean_commits":"110.71428571428571","dds":"0.49677419354838714","last_synced_commit":"403545a0b63c5ffe4c86c09f51e97686f0b2913c"},"previous_names":["jbx-protocol/juice-nft-rewards"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbx-protocol%2Fjuice-721-delegate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbx-protocol%2Fjuice-721-delegate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbx-protocol%2Fjuice-721-delegate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbx-protocol%2Fjuice-721-delegate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbx-protocol","download_url":"https://codeload.github.com/jbx-protocol/juice-721-delegate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280190,"owners_count":20912966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum","juicebox","juicebox-delegate","solidity"],"created_at":"2024-09-24T19:31:59.923Z","updated_at":"2025-10-19T12:54:32.157Z","avatar_url":"https://github.com/jbx-protocol.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Juicebox Delegated 721 Distribution Mechanism\n\n## Motivation\n\nIf included in a project's funding cycle, a 721 Delegate can provide utility or incentive for contributors to participate.\n\n## Mechanic\n\nWithin one collection, NFTs can be minted within any number of pre-programmed tiers.\n\nEach tier has the following optional properties:\n\n- a price.\n- a max quantity.\n- optionally, a number of voting units to associate with each unit within the tier, with onchain historical records.\n- optionally, a reserved rate allowing a proportion of units within the tier to be minted to a pre-programmed beneficiary.\n- a token URI, overridable by a URI resolver that can return dynamic values for each unit with the tier.\n- a category, so tiers can be organized and accessed for different purposes.\n- optionally, the ability for the contract's owner to mint tokens from the tier on demand.\n- if the tokens within the tier can have transfers paused on a per-funding-cycle basis, or if they must always remain transferable.\n- a few additional flags that restrict future tier additions to the collection.\n\nNew tiers can be added, so long as they respect the contract's `flags` that specify if new tiers can influence voting units, reserved quantities, or be manually minted.\n\nTiers can also be removed, so long as they are not locked.\n\nAn incoming payment can specify any number of tiers to mint as part of the payment, so long as the sum of the tier's prices are contained within the paid amount. If specific tiers aren't specified, the best available tier will be minted based on the specified floor amount, unless a flag is specifically sent along with the payment telling the contract to not mint.\n\nIf a tier's price is specified in a currency different to the incoming payment, a `JBPrices` contract will by used for trying to normalize the values.\n\nIf a payment received does not meet a price threshold or is in excess of the minted tiers, the balance is stored as a credit which will be added to future payments and applied to mints at that time. A flag can also be passed to avoid accepting payments that aren't applied to mints in full.\n\nThe contract's owner can mint on demand from tier's that have been pre-programmed to allow manual token minting.\n\nThe NFTs from each tier can also be used for redemptions against the underlying Juicebox treasury. The rate of redemptions corresponds to the price floor of the tier being redeemed, compared to the total price floors of all minted NFTs. Fungible project tokens cannot be being redeemed at the same time. In order to activate NFT redemptions, turn on the `shouldUseDataSourceForRedeem` metadata flag of your next funding cycle.\n\nThe NFTs can serve as utilities for on-chain governance if specified during the collection's deployment.\n\n## Architecture\n\nAn understanding of how the Juicebox protocol's pay and redeem functionality works is an important prereq to understanding how this repo's contracts work and attach themselves to Juicebox's regular operating behavior. This contract specifically makes use of the DataSource+Delegate pattern. See https://info.juicebox.money/dev/.\n\nIn order to use a 721 delegate, a Juicebox project should be launched from `JBTiered721DelegateProjectDeployer` instead of a `JBController`. This Deployer will deploy a `JBTiered721Delegate` (through it's reference to a `JBTiered721DelegateDeployer`) and attach it to the first funding cycle of the newly launched project as a DataSource and Delegate. Funding cycle reconfigurations can also be done using the `JBTiered721DelegateProjectDeployer`, though it will need to have Operator permissions from the project's owner.\n\nThe abstract `JB721Delegate` implementation of the ERC721 Juicebox DataSource+Delegate extension can be used for any distribution mechanic. This repo includes one implementation – the `JBTiered721Delegate` – as well as an extensions that offer on-chain governance capabilities to the distributed tokens. \n\nAll `JBTiered721Delegate`'s use a generic `JBTiered721DelegateStore` to store it's data.\n\nThe pay metadata structure is as follows:\nbytes32: ignored\nbytes32: ignored\nbytes4: send 0xf8b169f8 if the behavior from this delegate is expected to be triggered.\nbool: A flag indicating if the transaction should be allowed to proceed even if more funds are being paid than the specified NFTs cost.\nuint16[]: A list of tier IDs to mint from.\n\n## Deploy\n\nThe deployer copies the data of a pre-existing cononical version of the 721 contracts, which can be either GlobalGovernance, TierGovernance, or no governance. This was done to keep the deployer contract size small enough to be deployable, without the extra cost of the delegatecalls associated with a proxy pattern. \n\n\n# Install\n\nQuick all-in-one command:\n\n```bash\nrm -Rf juice-721-delegate || true \u0026\u0026 git clone -n https://github.com/jbx-protocol/juice-721-delegate \u0026\u0026 cd juice-721-delegate \u0026\u0026 git pull origin f9893b1497098241dd3a664956d8016ff0d0efd0 \u0026\u0026 git checkout FETCH_HEAD \u0026\u0026 foundryup \u0026\u0026 git submodule update --init --recursive --force \u0026\u0026 yarn install \u0026\u0026 forge test --gas-report\n```\n\nTo get set up:\n\n1. Install [Foundry](https://github.com/gakonst/foundry).\n\n```bash\ncurl -L https://foundry.paradigm.xyz | sh\n```\n\n2. Install external lib(s)\n\n```bash\nyarn install\n```\n\nthen run\n\n```bash\nforge update\n```\n\n3. Run tests:\n\n```bash\nforge test\n```\n\n4. Update Foundry periodically:\n\n```bash\nfoundryup\n```\n\n#### Setup\n\nConfigure the .env variables, and add a mnemonic.txt file with the mnemonic of the deployer wallet. The sender address in the .env must correspond to the mnemonic account.\n\n## Goerli\n\n```bash\nyarn deploy-goerli\n```\n\n## Mainnet\n\n```bash\nyarn deploy-mainnet\n```\n\nThe deployments are stored in ./broadcast\n\nSee the [Foundry Book for available options](https://book.getfoundry.sh/reference/forge/forge-create.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbx-protocol%2Fjuice-721-delegate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbx-protocol%2Fjuice-721-delegate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbx-protocol%2Fjuice-721-delegate/lists"}