# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacks.co/learn/sbtc/clarity-contracts/sbtc-token.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.