Contributor Smart Contract

General

This smart contract manages contributor delegation to the sBTC Incentive Program. It allows for the delegation and revocation of stacking rewards to the incentive program. The contract interacts with the PoX (Proof of Transfer) consensus contract to handle stack delegations. Additionally, it includes functions for the administrator to manage stack aggregation, such as committing, extending, and increasing stack amounts for contributors.


Overview

The Contributor smart contract enables delegation and administrative management of stake contributions for the Incentive Program. Key operations include:

  1. Contributor Delegation: Enables contributors to delegate Stacks to the Contributor contract address.

  2. Admin Functions: These functions enable the contract admin to manage delegated funds, including stacking, extending, and increasing stacks, as well as committing and increasing stack aggregation. The admin can also update the rewards address and assign a new contract admin.


Contract Operations

The contract operates through several functions, allowing contributors to manage their delegations and the admin to control the configuration of addresses and rewards. The workflow for each operation is as follows:

  1. Update Contributor Admin: Allows the contract admin to assign a new admin.

  2. Update Rewards Address: The admin can update the Bitcoin address for the stacking rewards.

  3. Delegate Stake: Contributors can delegate Stacks to the Contributor contract address.

  4. Revoke Delegation: Contributors can revoke their delegation at any time.

  5. Admin Stack Operations: The admin can perform various operations on the delegated funds, such as stacking, extending, and increasing, as well as managing aggregation values.

  6. Aggregation Commit: The admin can commit the stacked funds, thereby qualifying them for stacking rewards.


Public Functions

update-contributor-admin

Updates the admin of the contributor contract.

  • Parameters: new-admin (principal) — The new admin’s address.

  • Outputs: ok true if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Updates the contributor admin address to the new one.

update-rewards-address

Updates the rewards distribution address for the contract.

  • Parameters: new-rewards-address (tuple containing version and hashbytes fields representing a Bitcoin address).

  • Outputs: ok true if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Updates the rewards address to the provided one.

contributor-delegate

Allows contributors to delegate their funds to a specified contract.

  • Parameters: amount-ustx (uint) — The amount to delegate in micro Stacks.

  • Outputs: ok true if successful.

  • Constraints:

    • Ensures the contributor has allowance in the PoX contract.

  • Effect:

    • Delegates the specified amount of uSTX to the contributor's contract.

contributor-revoke-delegation

Allows contributors to revoke their delegation.

  • Outputs: ok true if successful.

  • Effect:

    • Calls the pox-4 contract to revoke delegation.

admin-stack

Allows the admin to stack the delegated funds.

  • Parameters:

    • stacker (principal) — The address of the stacker.

    • amount-ustx (uint) — The amount to stack in micro Stacks.

    • lock-period (uint) — The period to lock the stack.

  • Outputs: Returns stacker details if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Stacks the delegated funds in the PoX contract.

admin-stack-extend

Extends the lock period for a contributor’s stack.

  • Parameters:

    • stacker (principal) — The address of the stacker.

    • extend-count (uint) — The number of cycles to extend.

  • Outputs: Returns extension details if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Extends the lock period for the contributor.

admin-stack-increase

Increases the stacked amount of a contributor’s stack.

  • Parameters:

    • stacker (principal) — The address of the stacker.

    • increase-by (uint) — The amount to increase the stack in micro Stacks.

  • Outputs: Returns stacker details if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Increases the stacked amount for the contributor.

admin-aggregation-commit

Commits the stack aggregation for a given reward cycle.

  • Parameters:

    • reward-cycle (uint) — The reward cycle to commit.

    • signer-sig (optional buff 65) — Optional signature for validation.

    • signer-pubkey (buff 33) — Public key of the signer.

    • max-allowed-amount (uint) — Maximum allowed aggregation amount.

    • auth-id (uint) — Authorization ID for the aggregation.

  • Outputs: Returns aggregation index if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Commits the stack aggregation for the specified reward cycle.

admin-aggregation-increase

Increases the stack aggregation for a given reward cycle and index.

  • Parameters:

    • reward-cycle (uint) — The reward cycle.

    • index (uint) — The aggregation index.

    • signer-sig (optional buff 65) — Optional signature for validation.

    • signer-pubkey (buff 33) — Public key of the signer.

    • max-allowed-amount (uint) — Maximum allowed amount to increase by.

    • auth-id (uint) — Authorization ID.

  • Outputs: Returns ok true if successful.

  • Constraints:

    • Ensures the caller is the current admin.

  • Effect:

    • Increases the aggregation for the given cycle and index.


Private Functions

contributor-delegate-inner

Helper function that delegates the stake to a given address.

  • Parameters:

    • amount-ustx (uint) — The amount to delegate.

    • delegate-to (principal) — The address to delegate to.

    • until-burn-ht (optional uint) — Optional end burn height.

  • Outputs: Returns ok true if successful.

  • Effect:

    • Revokes any prior delegation and delegates the new amount to the specified contract.


Read-Only Functions

check-contributor-SC-pox-allowance

Checks if the contributor allowed the Contributor contract to call stacking methods on its behalf within the PoX contract.

  • Outputs: Returns a boolean indicating whether the contributor has issued the allowance in the PoX contract.

get-contributor-admin

Returns the address of the current contributor admin.

  • Outputs: Returns the principal address of the current admin.

get-rewards-address

Returns the rewards distribution address.

  • Outputs: Returns the Bitcoin address for rewards distribution.


Last updated