{"id":20310214,"url":"https://github.com/bloq/sol-mass-payouts","last_synced_at":"2025-06-23T18:38:31.413Z","repository":{"id":50921348,"uuid":"298395618","full_name":"bloq/sol-mass-payouts","owner":"bloq","description":"Merkle-based payout aggregation","archived":false,"fork":false,"pushed_at":"2024-10-22T20:03:16.000Z","size":579,"stargazers_count":25,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-14T00:02:34.921Z","etag":null,"topics":["defi","erc20","erc20-tokens","ethereum","ethereum-contract","ethereum-dapp","solidity","solidity-contracts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null}},"created_at":"2020-09-24T21:09:27.000Z","updated_at":"2025-01-03T00:26:00.000Z","dependencies_parsed_at":"2024-11-14T17:42:42.532Z","dependency_job_id":null,"html_url":"https://github.com/bloq/sol-mass-payouts","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bloq/sol-mass-payouts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloq%2Fsol-mass-payouts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloq%2Fsol-mass-payouts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloq%2Fsol-mass-payouts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloq%2Fsol-mass-payouts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloq","download_url":"https://codeload.github.com/bloq/sol-mass-payouts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloq%2Fsol-mass-payouts/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261534947,"owners_count":23173498,"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":["defi","erc20","erc20-tokens","ethereum","ethereum-contract","ethereum-dapp","solidity","solidity-contracts"],"created_at":"2024-11-14T17:30:29.826Z","updated_at":"2025-06-23T18:38:31.393Z","avatar_url":"https://github.com/bloq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sol-mass-payouts\n\nUtilities enabling the mass distribution of assets, with a single\nfunding transaction.\n\n## Summary example\n\nA funder, such as a yield farming distribution, wishes to distribute\n1,000,000 XYZ tokens to 50,000 addresses.\n\nOff-chain, the funder builds a merkle tree of (address,amount) pairs for XYZ\npayouts.\n\nThe funder sends 1,000,000 XYZ tokens, and the Merkle root hash, to this\nMerkleBox contract for secure storage.\n\nThen, at any time, users may claim their XYZ tokens by providing a\nMerkle proof of their (address,amount).\n\nThe end result is aggregating all the payouts into a single blockchain\ntransaction _from the funder_. (Users must still individually issue\nclaim transactions)\n\n## Public operations (APIs)\n\n### Anyone: Validate claim\n\nValidate a supplied merkle receipt is associated with a valid, unspent claim.\n\n### Anyone: Claim tokens\n\nPresent a valid merkle receipt with account associated with it and transfer the associated tokens to given account.\n\nProvided account address must be the address in the claim, and the claim must be unspent.\n\n### Funder: Create new claims group\n\nStore a merkle root, and associated ERC20 funds, on chain.\nMust provide withdraw unlock time and its value must be atleast 30 days higher than claim group create time.\n\nCan also provide a memo string for adding arbitrary notes to the group.\n\n**WARNING**: There is no on-chain validation that funds supplied equal the\nfunds required to fully satisfy all claims. The funder may under-fund.\n\n\u003e Funder can not claim tokens via `claim()`\n\n### Anyone: Add more funds to claims group.\n\nSupply additional quantity of asset to the claims group.\n\nUsually the funder calls this operation, but that is not a requirement.\nOnce a claims group is created, anyone may supply additional funds.\n\n### Funder: Withdraw funds from claims group.\n\nThe funder (owner) may withdraw funds from the claims group,\nif-and-only-if the Withdraw Unlock time is reached.\n\n### Anyone: On-chain ERC20 mass-send\n\nA separate MultiTransfer contract is provided, which provides the\nsimple utility of\n\n1. Receive N amount of an ERC20 token\n2. Send tokens to a list of (address,amount) pairs.\n\nThis contract and function is not tied in any way to the above\nmerkle-related operations, and is provided as an alternate mass-pay\noperation for ERC20 tokens.\n\n## Security notes\n\n### Under-funding\n\nIt appears prohibitively expensive to validate that a holding is fully\nfunded. (Solutions welcome)\n\nAs a consequence, it is possible to under-fund a claims group.\n\n### Withdraw locking\n\nThe withdraw lock feature permits disabling of withdrawals until\na specified time.\n\nThere will be atleast 30 days withdraw locking. To permanently lock the funds, set the lock time to a\nmaximum, or an arbitrary time millions of years in the future.\n\n## Setup.\nInstall packages\n\n   ```\n   $ npm i\n   ```\n\n### Compile Contracts\n```\n$ npm run compile\n```\n\n### Test\n```\n$ npm run test\n```\n\n### Coverage Report\n```\n$ npm run coverage\n```\n\n### Deploy\nSetup the env vars properly (See `.env.template` file) and run:\n\n```sh\n# deploy\n$ npm run deploy -- --gasprice \u003cgas price in wei\u003e --network \u003cnetwork\u003e\n\n# create release\n$ npx hardhat create-release --release \u003csemver\u003e --network \u003cnetwork\u003e\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloq%2Fsol-mass-payouts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloq%2Fsol-mass-payouts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloq%2Fsol-mass-payouts/lists"}