{"id":31793101,"url":"https://github.com/friedger/clarity-trustless-pool","last_synced_at":"2026-02-17T15:35:16.683Z","repository":{"id":299901139,"uuid":"1004567492","full_name":"friedger/clarity-trustless-pool","owner":"friedger","description":"Trustless stacking pool on Bitcoin L2 Stacks","archived":false,"fork":false,"pushed_at":"2025-07-17T08:55:08.000Z","size":92,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-10T17:58:37.802Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clarity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","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":"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,"zenodo":null}},"created_at":"2025-06-18T20:44:09.000Z","updated_at":"2025-07-17T08:55:11.000Z","dependencies_parsed_at":"2025-06-18T22:31:13.034Z","dependency_job_id":"bd7d5a80-fae6-46c1-b576-16b7de4f7161","html_url":"https://github.com/friedger/clarity-trustless-pool","commit_stats":null,"previous_names":["friedger/clarity-trustless-pool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/friedger/clarity-trustless-pool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-trustless-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-trustless-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-trustless-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-trustless-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friedger","download_url":"https://codeload.github.com/friedger/clarity-trustless-pool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-trustless-pool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29548377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T14:33:00.708Z","status":"ssl_error","status_checked_at":"2026-02-17T14:32:58.657Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":[],"created_at":"2025-10-10T17:58:14.234Z","updated_at":"2026-02-17T15:35:11.674Z","avatar_url":"https://github.com/friedger.png","language":"Clarity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clarity-trustless-pool\n\nTrustless stacking pool on Bitcoin L2 Stacks\n\nThe Stacks blockchain's unique Proof of Transfer (PoX) consensus mechanism allows STX holders to earn Bitcoin rewards by participating in stacking already with small amount through stacking pools. However, users have to trust pool operators that they handle the stacking rewards correctly. With **trustless stacking pools** the handling of stacking rewards are now fully managed through smart contracts in a trustless way.\n\n## What is a Trustless Stacking Pool?\n\nA trustless stacking pool is a smart contract system that allows multiple STX holders to combine their tokens for stacking without the need of a pool operator. Trustless pools use sbtc deposits, a smart contract to manage stacking and two smart contracts to distribute rewards.\n\n### Key Benefits\n\n- **No custody risk**: Your STX never leaves your wallet\n- **Lower barriers**: Participate with smaller amounts\n- **Automated rewards**: Smart contracts handle distribution\n- **Transparency**: All operations are on-chain and verifiable\n\n### Risks\n\n- **Smart contract bugs**: Unintentded behaviour encoded in contracts\n\n## Business Rules\n\nThe trustless pool should workd according to following rules:\n\n1. Any user can join the pool with at a minimum of 0,0001 base points (~50 STX as of June 2025) of the total locked amount in the current cycle.\n2. The pox reward address is defined as the sbtc deposit address of a deposit vault contract.\n3. The signer node registers a generic signature for the pox reward address allowing to call commit without signature.\n4. Any user can extend the stacking period for pool members after half the cycle has passed (only 1 week to revoke delegation for users, can be done by bots)\n5. Any user can transfer the stacking rewards from deposit vault to the payout contract at any time if the balance is more than the minimum for intermediate payouts (tbd) or during the prepare phase (can be done by bots)\n6. Any user can transfer the portion of the rewards assigned to a user from the payout contract to the user. (can be done by bots)\n7. Failed sbtc deposits are send to a trusted rewards admin.\n\nOptional rules:\n\n1. Trusted rewards admin can black list payouts for certain users.\n2. Users can define a payout address to receive rewards different from the stacking address.\n3. Trusted rewards admin can change the minimum for intermediate payouts.\n4. Trusted rewards admin can manipulate payouts in emergency.\n5. Trusted rewards admin can withdraw assets other than sBTC from the contract (save wrongly directed assets).\n\n## Architecture Overview\n\n### Contracts\n\n1. **`pox4-self-service-multi.clar`** - Handles delegation and stacking operations\n1. **`deposit-vault.clar`** - Holds rewards until the end of the cycle\n1. **`payout-self-service-sbtc.clar`** - Manages reward distribution (using sBTC)\n\n```clarity\n;; Example stacking call for users\n(contract-call? .pox4-self-service-multi delegate-stx\n  u1000000000000  ;; amount in micro-STX\n  user-data       ;; metadata for rewards\n)\n```\n\n## Testing Strategy: Flow Tests\n\nFlow tests are crucial for testing complex multi-transaction scenarios that simulate real user interactions. They use special annotations to control transaction senders and test entire workflows.\n\n### Setting Up Flow Tests\n\nFlow tests use comment annotations to specify transaction details:\n\n```clarity\n;; @name test the delegation flow\n;; @format-ignore\n(define-public (test-delegation)\n  (begin\n    ;; @caller deployer\n    (unwrap! (contract-call? .pox4-self-service-multi set-pool-pox-address-active\n      {version: 0x00, hashbytes: 0x7321b74e2b6a7e949e6c4ad313035b1665095017})\n      (err u1000))\n    ;; @caller wallet_1\n    (unwrap! (contract-call? 'ST000000000000000000002AMW42H.pox-4\n      allow-contract-caller .pox4-self-service-multi none)\n      (err u2000))\n    ;; More test steps...\n    (ok true)\n  )\n)\n```\n\n### Key Testing Patterns\n\n1. **Authorization Flow**: Test that users can properly authorize the pool contract\n2. **Delegation Flow**: Verify STX delegation works correctly\n3. **Aggregation Flow**: Test that the pool can commit aggregated STX\n4. **Reward Distribution**: Ensure rewards are distributed fairly\n\n## Testing Strategy: Devnet\n\nThe project contains multiple YAML files for different steps in the stacking cycles:\n\n### 1. Initial Setup (`0-init.yaml`)\n\n```yaml\nplan:\n  batches:\n    - id: 0\n      transactions:\n        - contract-call:\n            contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.pox4-self-service-multi\n            method: set-pool-pox-address-active\n            parameters:\n              - \"{ hashbytes: 0x7321b74e2b6a7e949e6c4ad313035b1665095017, version: 0x00 }\"\n```\n\nThis deployment:\n\n- Sets up the pool's Bitcoin address for receiving rewards\n- Configures initial contract permissions\n- Prepares the system for user delegations\n\n### 2. User Delegation (`1-alice-delegate.devnet-plan.yaml`)\n\n```yaml\ntransactions:\n  - contract-call:\n      contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.pox4-self-service-multi\n      expected-sender: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG\n      method: delegate-stx\n      parameters:\n        - u250000000000000 # 250,000 STX\n        - 0x # User data\n```\n\n### 3. Aggregation (`2-aggregate-commit-2.yaml`)\n\nUser commits the aggregated STX for stacking:\n\n```yaml\ntransactions:\n  - contract-call:\n      method: stack-aggregation-commit\n      parameters:\n        - u2 # Cycle\n        - (some 0x18ce215d39a1d3daff...) # Signature\n        - 0x03cd2cfdbd2ad9332828a7a13ef... # Signer key\n        - u1000000000000000 # Amount\n        - u123 # Auth ID\n```\n\n### 4. Reward Distribution (`3-distribute-rewards.yaml`)\n\nFinally, rewards are distributed to participants:\n\n```yaml\ntransactions:\n  - contract-call:\n      contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.payout-self-service-sbtc\n      method: distribute-rewards\n      parameters:\n        - \"'ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG\" # Recipient\n        - u1 # Cycle\n```\n\n### Running Devnet Locally\n\nTo test the trustless pool on your local devnet:\n\n1. **Start the devnet**:\n\n```bash\nclarinet devnet start\n```\n\n2. **Deploy contracts**:\n\n```bash\nclarinet deployment apply deployments/default.devnet-plan.yaml\n```\n\n3. **Run initialization**:\n\n```bash\nclarinet deployment apply deployments/0-init.yaml\n```\n\n4. **Test user flows**:\n\n```bash\nclarinet deployment apply deployments/1-alice-delegate.devnet-plan.yaml\nclarinet deployment apply deployments/1-bob-delegate.devnet-plan.yaml\n```\n\n## Testing Strategy: Unit tests\n\nTo test the trustless pool on simnet with unit tests run the following commands:\n\n```bash\npnpm install\npnpm test\n```\n\n## Advanced Testing with Signatures\n\nThe pool uses cryptographic signatures to ensure only authorized operations can be performed. The flow tests include signature generation and validation:\n\n```clarity\n(define-constant signer-key 0x03cd2cfdbd2ad9332828a7a13ef62cb999e063421c708e863a7ffed71fb61c88c9)\n\n(define-private (aggregate-commit-internal)\n  (contract-call? .pox4-self-service-multi\n    stack-aggregation-commit\n    u0\n    (some 0xee088eb40553ca5cddcd7eb18a48f76b5047bfa3b0a3da60446d69226d345c0a49a5a709e74a7a21933fce837e5fee86caaca2dbc4f42391d7710380ad023caf00)\n    signer-key\n    u1000000000000000\n    u123))\n```\n\nThe signature can be created using script `src/signature.ts`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedger%2Fclarity-trustless-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriedger%2Fclarity-trustless-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedger%2Fclarity-trustless-pool/lists"}