define-fungible-token

Function Signature

(define-fungible-token token-name <total-supply>)

• Input:
  • token-name: The name of the fungible token
  • <total-supply>: (Optional) An unsigned integer representing the total supply of tokens
• Output: Not applicable (definition statement)

Why it matters

The define-fungible-token function is crucial for:

1. 1Creating new fungible tokens within a smart contract.
2. 2Establishing a token economy or system within your dApp.
3. 3Implementing custom tokens with specific supply constraints.
4. 4Enabling token-related operations like minting, transferring, and burning.

When to use it

Use define-fungible-token when you need to:

• Create a new fungible token for your smart contract or dApp.
• Implement a token with a fixed total supply.
• Establish a foundation for token-based features in your contract.
• Create utility tokens, governance tokens, or other custom fungible assets.

Best Practices

• Place define-fungible-token at the top level of your contract, as it's a definition statement.
• Consider carefully whether to specify a total supply or leave it unlimited.
• Use meaningful and descriptive names for your tokens.
• Implement proper access controls for minting and burning operations if required.

Practical Example: Simple Token Creation

Let's implement a basic fungible token with a fixed supply:

(define-fungible-token DOG-GO-TO-THE-MOON u1000000)

(define-data-var tokenAdmin principal tx-sender)

(define-public (transfer (amount uint) (sender principal) (recipient principal))
  (begin
    (asserts! (is-eq tx-sender sender) (err u1))
    (ft-transfer? DOG-GO-TO-THE-MOON amount sender recipient)
  )
)

(define-read-only (get-balance (account principal))
  (ok (ft-get-balance DOG-GO-TO-THE-MOON account))
)

(define-public (mint (amount uint) (recipient principal))
  (begin
    (asserts! (is-eq tx-sender (var-get tokenAdmin)) (err u3))
    (ft-mint? DOG-GO-TO-THE-MOON amount recipient)
  )
)

This example demonstrates:

1. 1Using define-fungible-token to create a new token with a fixed supply of 1,000,000.
2. 2Implementing basic token operations like transfer and balance checking.
3. 3Adding a mint function with admin-only access control.

Common Pitfalls

1. 1Forgetting that omitting the total supply parameter allows unlimited minting, if not handled manually.
2. 2Not implementing proper access controls for sensitive operations like minting.
3. 3Overlooking the need for additional functionality like burning or pausing.

Related Functions

• ft-transfer?: Used to transfer tokens between principals.
• ft-mint?: Used to create new tokens (if allowed by the token definition).
• ft-burn?: Used to destroy tokens, reducing the circulating supply.
• ft-get-balance: Used to check the token balance of a principal.
• ft-get-supply: Used to get the current total supply of tokens.

Conclusion

The define-fungible-token function is a fundamental building block for creating token-based systems in Clarity smart contracts. It allows developers to define custom fungible tokens with or without supply constraints. When combined with other token-related functions, it enables the implementation of sophisticated token economies and financial instruments on the Stacks blockchain.