Skip to content

Latest commit

 

History

History
175 lines (99 loc) · 4.41 KB

sbtc-token.md

File metadata and controls

175 lines (99 loc) · 4.41 KB
Raw

sBTC Token Contract Documentation

Overview

The sBTC Token contract (sbtc-token.clar) implements the fungible token functionality for sBTC. It manages both unlocked and locked sBTC tokens and provides functions for minting, burning, transferring, and querying token information. sBTC is a SIP-010 standard fungible token.

Constants

  • ERR_NOT_OWNER (u4): Error when the sender tries to move a token they don't own.
  • ERR_NOT_AUTH (u5): Error when the caller is not an authorized protocol caller.
  • token-decimals (u8): The number of decimal places for the token.

Fungible Tokens

  • sbtc-token: The main sBTC fungible token.
  • sbtc-token-locked: Represents locked sBTC tokens.

Data Variables

  • token-name: The name of the token (default: "sBTC").
  • token-symbol: The symbol of the token (default: "sBTC").
  • token-uri: An optional URI for token metadata.

Protocol Functions

These functions can only be called by authorized protocol contracts:

protocol-transfer

Transfers tokens between principals.

  • Parameters: amount: uint, sender: principal, recipient: principal
  • Returns: (response bool uint)

protocol-lock

Locks a specified amount of tokens for a user.

  • Parameters: amount: uint, owner: principal
  • Returns: (response bool uint)

protocol-unlock

Unlocks a specified amount of tokens for a user.

  • Parameters: amount: uint, owner: principal
  • Returns: (response bool uint)

protocol-mint

Mints new tokens for a recipient.

  • Parameters: amount: uint, recipient: principal
  • Returns: (response bool uint)

protocol-burn

Burns tokens from an owner's balance.

  • Parameters: amount: uint, owner: principal
  • Returns: (response bool uint)

protocol-burn-locked

Burns locked tokens from an owner's balance.

  • Parameters: amount: uint, owner: principal
  • Returns: (response bool uint)

protocol-set-name

Sets a new name for the token.

  • Parameters: new-name: (string-ascii 32)
  • Returns: (response bool uint)

protocol-set-symbol

Sets a new symbol for the token.

  • Parameters: new-symbol: (string-ascii 10)
  • Returns: (response bool uint)

protocol-set-token-uri

Sets a new URI for the token metadata.

  • Parameters: new-uri: (optional (string-utf8 256))
  • Returns: (response bool uint)

protocol-mint-many

Mints tokens for multiple recipients in a single transaction.

  • Parameters: recipients: (list 200 {amount: uint, recipient: principal})
  • Returns: (response (list 200 (response bool uint)) uint)

Public Functions (SIP-010 Trait)

transfer

Transfers tokens between users.

  • Parameters: amount: uint, sender: principal, recipient: principal, memo: (optional (buff 34))
  • Returns: (response bool uint)

get-name

Returns the token name.

  • Returns: (response (string-ascii 32) uint)

get-symbol

Returns the token symbol.

  • Returns: (response (string-ascii 10) uint)

get-decimals

Returns the number of decimal places.

  • Returns: (response uint uint)

get-balance

Returns the total balance (locked + unlocked) for a principal.

  • Parameters: who: principal
  • Returns: (response uint uint)

get-balance-available

Returns the available (unlocked) balance for a principal.

  • Parameters: who: principal
  • Returns: (response uint uint)

get-balance-locked

Returns the locked balance for a principal.

  • Parameters: who: principal
  • Returns: (response uint uint)

get-total-supply

Returns the total supply of tokens (locked + unlocked).

  • Returns: (response uint uint)

get-token-uri

Returns the token metadata URI.

  • Returns: (response (optional (string-utf8 256)) uint)

Private Functions

protocol-mint-many-iter

Helper function for minting tokens to multiple recipients.

  • Parameters: item: {amount: uint, recipient: principal}
  • Returns: (response bool uint)

Security Considerations

  1. Access Control: Protocol functions can only be called by authorized contracts, enforced through the sbtc-registry contract.
  2. Ownership Verification: The transfer function checks that the sender owns the tokens being transferred.
  3. Separate Token Tracking: The contract maintains separate tracking for locked and unlocked tokens, ensuring proper accounting.

Interactions with Other Contracts

  • .sbtc-registry: Used to validate protocol callers for privileged operations.