# sBTC Token

## Overview

The [sBTC Token contract](https://github.com/stacks-network/sbtc/blob/main/contracts/contracts/sbtc-token.clar) (`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

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

### protocol-lock

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

### protocol-unlock

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

### protocol-mint

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

### protocol-burn

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

### protocol-burn-locked

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

### protocol-set-name

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

### protocol-set-symbol

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

### protocol-set-token-uri

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

### protocol-mint-many

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

## Public Functions (SIP-010 Trait)

### transfer

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

### get-name

* Returns: `(response (string-ascii 32) uint)`

### get-symbol

* Returns: `(response (string-ascii 10) uint)`

### get-decimals

* 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: `(response uint uint)`

### get-token-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

{% stepper %}
{% step %}
**Access Control**

Protocol functions can only be called by authorized contracts, enforced through the `sbtc-registry` contract.
{% endstep %}

{% step %}
**Ownership Verification**

The `transfer` function checks that the sender owns the tokens being transferred.
{% endstep %}

{% step %}
**Separate Token Tracking**

The contract maintains separate tracking for locked and unlocked tokens, ensuring proper accounting.
{% endstep %}
{% endstepper %}

## Interactions with Other Contracts

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