Hiro Docs

Function Signature

(ft-transfer? token-name amount sender recipient)

Input:
- token-name: The name of the fungible token
- amount: The amount of tokens to transfer (uint)
- sender: The principal sending the tokens
- recipient: The principal receiving the tokens
Output: (response bool uint)

Why it matters

The ft-transfer? function is crucial for:

Moving fungible tokens between different principals within a smart contract.
Implementing token transfer functionality in decentralized applications.
Enabling token-based transactions and interactions between users or contracts.
Facilitating token economy mechanisms within smart contracts.

When to use it

Use ft-transfer? when you need to:

Transfer tokens from one account to another.
Implement payment or reward systems using custom tokens.
Allow users to send tokens to each other within your dApp.
Move tokens as part of more complex contract operations.

Best Practices

Always check the return value to ensure the transfer was successful.
Implement proper access controls to prevent unauthorized transfers.
Consider using asserts! or try! to handle transfer failures gracefully.
Be aware that any principal can call this function, so add necessary guards.
Verify sender has sufficient balance before attempting a transfer.

Practical Example: Token Transfer Function

Let's implement a public function for transferring tokens with some basic checks:

(define-fungible-token cBtc)

(define-public (transfer-tokens (amount uint) (recipient principal))
  (let
    (
      (sender tx-sender)
    )
    (asserts! (not (is-eq sender recipient)) (err u2))
    (asserts! (> amount u0) (err u3))
    (match (ft-transfer? cBtc amount sender recipient)
      success (ok success)
      error (err error)
    )
  )
)

;; Usage
(ft-mint? cBtc u100 tx-sender)
(transfer-tokens u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)

This example demonstrates:

Using ft-transfer? within a public function to transfer tokens.
Implementing basic checks for valid transfer conditions.
Handling the response from ft-transfer? and propagating it to the caller.

Common Pitfalls

Forgetting that ft-transfer? can be called by any principal, potentially leading to unauthorized transfers.
Not handling all possible error cases returned by ft-transfer?.
Attempting to transfer more tokens than the sender's balance.
Using ft-transfer? with a token name that hasn't been defined in the contract.

ft-mint?: Used to create new tokens and assign them to a principal.
ft-burn?: Used to destroy tokens, reducing the balance of a principal.
ft-get-balance: Used to check the token balance of a principal.
ft-get-supply: Used to get the current total supply of tokens.

The ft-transfer? function is a fundamental component for implementing token transfers in Clarity smart contracts. It provides a straightforward way to move tokens between principals, enabling a wide range of token-based functionalities. When used with proper checks and balances, it allows for the creation of secure and efficient token economies within decentralized applications on the Stacks blockchain.

ft-transfer?