{"id":13651312,"url":"https://github.com/friedger/clarity-stacking-pools","last_synced_at":"2026-02-14T17:04:06.626Z","repository":{"id":127351239,"uuid":"344062239","full_name":"friedger/clarity-stacking-pools","owner":"friedger","description":"Smart contracts for non-custodial stacking pools on the Stacks blockchain","archived":false,"fork":false,"pushed_at":"2025-04-23T09:21:54.000Z","size":647,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-05T17:03:54.726Z","etag":null,"topics":["blockchain","clarity","clarity-smart-contracts"],"latest_commit_sha":null,"homepage":"","language":"HTML","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/friedger.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-03T08:57:10.000Z","updated_at":"2025-06-04T09:40:40.000Z","dependencies_parsed_at":"2024-04-15T00:40:55.415Z","dependency_job_id":"c7af184a-e3c1-48c5-9656-1730d5fbc5ae","html_url":"https://github.com/friedger/clarity-stacking-pools","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/friedger/clarity-stacking-pools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-stacking-pools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-stacking-pools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-stacking-pools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-stacking-pools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friedger","download_url":"https://codeload.github.com/friedger/clarity-stacking-pools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-stacking-pools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29450610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["blockchain","clarity","clarity-smart-contracts"],"created_at":"2024-08-02T02:00:47.879Z","updated_at":"2026-02-14T17:04:06.593Z","avatar_url":"https://github.com/friedger.png","language":"HTML","funding_links":[],"categories":["Clarity Resources"],"sub_categories":["Stacking"],"readme":"# Wrapper Contracts for pox-4 contract\n\nThis repo contains smart contracts that are wrapping contract calls to the pox-4 contract of the Stacks blockchain. The pox-4 contract is the heart of [Proof of Transfer (PoX)](https://www.stacks.co/learn/stacking).\n\nThere are two different wrapper contracts:\n\n- `pox4-pools`: A generic contract for stacking pools that enables custom payout addresses for pool members. Deployed on mainnet at `SP001SFSMC2ZY76PD4M68P3WGX154XCH7NE3TYMX.pox4-pools`.\n- `pox4-self-service`: A self-service contract where the smart contract is the pool operator. Deployed on mainnet at `SP21YTSM60CAY6D011EZVEVNKXVW8FVZE198XEFFP.pox4-fast-pool-v3` and\n\nBoth contracts require one transaction to allow the contract to handle the user's stacking rights (call to `pox-4.allow-contract-caller`). Furthermore, both contracts implement the same stacking rights protection with `allow-contract-caller` and `disallow-contract-caller` functions.\n\nA web UI for these contracts exists on [lockstack.com](https://github.com/hirosystems/btcweb3).\n\nUsers trust the pool admin that they will receive their share of rewards.\n\n## pox4-pools (rewards in BTC)\n\nA wrapper contract that allows users to provide a btc address during delegation to a stacking pool.\nThe btc address should be used by the pool operator to distribute the stacking rewards.\n\nThis contract is a generic protocol and can be used by many pools.\n\nThis contract will lock STX for 1 cycle only. Users can revoke pool membership at any time and their STX will unlock automatically 1 day after the end of the current cycle.\n\nUsers can increase the delegated amount of STX for the next cycle at any time before the pool closes.\n\n### Function `delegate-stx`\n\nUsers call this function to delegate the stacking rights to a pool. Users can revoke delegation and stx tokens will unlock at the end of the next cycle. Locking period is fixed to one cycle.\n\nThis function revokes previous delegations to a pool (calls `pox-4.revoke-delegate-stx`) so that only one transaction is required to update stacking delegation.\n\nIn addition, the user has to provide a reward address that pool operators should use for reward distribution. All other arguments are passed to directly to the `pox-4.delegate-stx` function.\n\n### Pool operator functions `delegate-stack-stx` and `delegate-stack-stx-simple`\n\nCan be called by pool operator only.\n\nThese functions lock pool members' STX tokens in batches of 30.\n\nThe `-simple` version locks the maximum amount of STX minus 1 STX buffer. The normal function requires the pool operator to provide the locking amount for each user.\n\n## pox4-self-service\n\nA wrapper contract that allows user to delegate and stack their STX at the same time.\n\nThis contract can be used by one pool only because the smart contract address is the pool address.\n\nThis contract is not meant for smaller pools where the minimum requirement for 1 stacking slot might not be met because STX are locked immediately. If the pool does not hit the minimum, STX are locked without earning stacking rewards.\n\nThe pool operator is the contract itself; only reward distributions happens through the pool operator (=reward admin).\n\nThis contract will lock STX for 1 cycle only. Users can revoke pool membership at any time and their STX will unlock automatically 1 day after the end of the current cycle.\n\nThis contract can be adapted for users to provide a btc address similar to pox4-pools.\n\nUser calls delegate-stx once. For next cycles, users can call delegate-stx or ask automation, friends or family to extend stacking using delegate-stack-stx.\nUsers can increase the delegated amount of STX for the next cycle at any time before the start of the next cycle.\n\n### Function `delegate-stx`\n\nThe self-service function \"delegate-stx\" does the following:\n\n1. Revoke delegation if necessary.\n2. Delegates STX.\n3. For first time user, stacks the caller's stx tokens for 1 cycle.\n   For stackerd user, extends locking and if needed increases amount.\n   The amount is the minimum of the balance and the delegate amount\n   minus some STX as buffer.\n   The STX buffer is left unlocked for users to call revoke-delegate-stx.\n\nReturns the stacker details when the transaction was successful.\n\n### Function `delegate-stack-stx`\n\nPool operator function \"delegate-stack-stx\" does step 3. (for stacked users) as described for function \"delegate-stx\" for the following cycles.\n\nThis function can be called by anyone when less than 1050 blocks are left until the cycle start. This gives the stacker 1 week to unlock the STX - if wanted - before it can be locked again for friends and family (or enemies).\n\n### Reward admin functions\n\nThe reward admin is a contract or user that controls the PoX BTC reward address. The admin can\n\n- activate and deactivate the contract (`set-active`),\n- change the PoX BTC reward address (`set-pool-pox-address`),\n- change the stx buffer for the locked amount (usually 1 STX) (`set-stx-buffer`),\n- add and remove more reward admins (`set-reward-admin`).\n- aggregate commit the partially stacked STX and increase the committed amount (`maybe-stack-aggregation-commit`)\n\n## Security auditing\n\n### Unit tests\n\nThe repo contains a suite of unit tests. The coverage is limited to the functionality that does not require extensive use of pox locking and release handling. This pox feature is not supported by simnet.\n\nCoverage data for unit tests is available in the `coverage-web` folder.\n\n### Integration tests with vitest and stacks-devnet-js\n\nThe folder `integration` contains a setup of integration test with devnet that can be launched with `yarn test:dev`. This is work in progress.\n\n### Integration tests with clarinet integrate\n\nUsing `clarinet integrate` allows to work through all stages of the pool on devnet. The web UI supports these contracts. You can use the secret phrases in `settings/Devnet.toml`.\n\nThere is one set of deployment plans for each contract.\n\nDeployment plans starting with `0-`, `1-` etc are for `pox-pools-1-cycle`. Deployment plans starting with `fp-0-`, `fp-1-` etc is for `pox-pool-self-service`.\n\nThere is also a `helper.clar` contract that wraps read-only functions into public functions so that they can be called via deployment plans (`helper.yaml`).\n\nThe allow contract calls must be called once at the beginning. Then the delegate and delegate-stack plans can be used for each cycle.\n\nExample to use deployment plan:\n\n```\nclarinet deployment apply -p deployments/0-allow-contract-caller.devnet-plan.yaml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedger%2Fclarity-stacking-pools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriedger%2Fclarity-stacking-pools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedger%2Fclarity-stacking-pools/lists"}