;; Simple SIP-013 Semi-Fungible Token Implementation
;; Clarity Version 3
(impl-trait 'ST1ZK4MRVTQQJMVAAJQWBV2WPQ87QV2851YCTHD7X.sip-013-trait-sft-standard.sip-013-trait)
;; Define native token for post condition support
(define-fungible-token sft-token)
(define-non-fungible-token sft-token-id {token-id: uint, owner: principal})
;; Constants
(define-constant CONTRACT-OWNER tx-sender)
(define-constant ERR-OWNER-ONLY (err u100))
(define-constant ERR-INSUFFICIENT-BALANCE (err u1))
(define-constant ERR-SAME-SENDER-RECIPIENT (err u2))
(define-constant ERR-ZERO-AMOUNT (err u3))
(define-constant ERR-NOT-AUTHORIZED (err u4))
(define-constant ERR-TOKEN-NOT-FOUND (err u404))
;; Storage
(define-map token-balances {token-id: uint, owner: principal} uint)
(define-map token-supplies uint uint)
(define-map token-decimals uint uint)
(define-map token-uris uint (string-ascii 256))
;; Read-only functions
;; Get balance of a specific token for a principal
(define-read-only (get-balance (token-id uint) (who principal))
(ok (default-to u0 (map-get? token-balances {token-id: token-id, owner: who})))
)
;; Get overall balance across all tokens for a principal
(define-read-only (get-overall-balance (who principal))
(ok (ft-get-balance sft-token who))
)
;; Get total supply of a specific token
(define-read-only (get-total-supply (token-id uint))
(ok (default-to u0 (map-get? token-supplies token-id)))
)
;; Get overall supply across all tokens
(define-read-only (get-overall-supply)
(ok (ft-get-supply sft-token))
)
;; Get decimals for a token
(define-read-only (get-decimals (token-id uint))
(ok (default-to u0 (map-get? token-decimals token-id)))
)
;; Get token URI
(define-read-only (get-token-uri (token-id uint))
(ok (map-get? token-uris token-id))
)
;; Private helper functions
;; Tag NFT for post condition support
(define-private (tag-nft-token-id (nft-token-id {token-id: uint, owner: principal}))
(begin
(and
(is-some (nft-get-owner? sft-token-id nft-token-id))
(try! (nft-burn? sft-token-id nft-token-id (get owner nft-token-id)))
)
(nft-mint? sft-token-id nft-token-id (get owner nft-token-id))
)
)
;; Update token balance
(define-private (set-balance (token-id uint) (owner principal) (new-balance uint))
(if (> new-balance u0)
(map-set token-balances {token-id: token-id, owner: owner} new-balance)
(map-delete token-balances {token-id: token-id, owner: owner})
)
)
;; Public functions
;; Transfer tokens
(define-public (transfer (token-id uint) (amount uint) (sender principal) (recipient principal))
(let
(
(sender-balance (unwrap-panic (get-balance token-id sender)))
)
;; Validate inputs
(asserts! (> amount u0) ERR-ZERO-AMOUNT)
(asserts! (not (is-eq sender recipient)) ERR-SAME-SENDER-RECIPIENT)
(asserts! (>= sender-balance amount) ERR-INSUFFICIENT-BALANCE)
(asserts! (or (is-eq sender tx-sender) (is-eq sender contract-caller)) ERR-NOT-AUTHORIZED)
;; Update balances
(set-balance token-id sender (- sender-balance amount))
(set-balance token-id recipient (+ (unwrap-panic (get-balance token-id recipient)) amount))
;; Transfer fungible tokens for post conditions
(try! (ft-transfer? sft-token amount sender recipient))
;; Tag NFTs for post conditions
(try! (tag-nft-token-id {token-id: token-id, owner: sender}))
(try! (tag-nft-token-id {token-id: token-id, owner: recipient}))
;; Emit transfer event
(print {type: "sft_transfer", token-id: token-id, amount: amount, sender: sender, recipient: recipient})
(ok true)
)
)
;; Transfer with memo
(define-public (transfer-memo (token-id uint) (amount uint) (sender principal) (recipient principal) (memo (buff 34)))
(begin
(try! (transfer token-id amount sender recipient))
(print memo)
(ok true)
)
)
;; Admin functions
;; Mint new tokens (only owner)
(define-public (mint (token-id uint) (amount uint) (recipient principal))
(begin
(asserts! (is-eq tx-sender CONTRACT-OWNER) ERR-OWNER-ONLY)
(asserts! (> amount u0) ERR-ZERO-AMOUNT)
;; Update balance and supply
(set-balance token-id recipient (+ (unwrap-panic (get-balance token-id recipient)) amount))
(map-set token-supplies token-id (+ (unwrap-panic (get-total-supply token-id)) amount))
;; Mint fungible tokens for post conditions
(try! (ft-mint? sft-token amount recipient))
;; Tag NFT for post conditions
(try! (tag-nft-token-id {token-id: token-id, owner: recipient}))
;; Emit mint event
(print {type: "sft_mint", token-id: token-id, amount: amount, recipient: recipient})
(ok true)
)
)
;; Burn tokens
(define-public (burn (token-id uint) (amount uint) (sender principal))
(let
(
(sender-balance (unwrap-panic (get-balance token-id sender)))
)
(asserts! (> amount u0) ERR-ZERO-AMOUNT)
(asserts! (>= sender-balance amount) ERR-INSUFFICIENT-BALANCE)
(asserts! (or (is-eq sender tx-sender) (is-eq sender contract-caller)) ERR-NOT-AUTHORIZED)
;; Update balance and supply
(set-balance token-id sender (- sender-balance amount))
(map-set token-supplies token-id (- (unwrap-panic (get-total-supply token-id)) amount))
;; Burn fungible tokens for post conditions
(try! (ft-burn? sft-token amount sender))
;; Tag NFT for post conditions
(try! (tag-nft-token-id {token-id: token-id, owner: sender}))
;; Emit burn event
(print {type: "sft_burn", token-id: token-id, amount: amount, sender: sender})
(ok true)
)
)
;; Set token metadata (only owner)
(define-public (set-token-uri (token-id uint) (uri (string-ascii 256)))
(begin
(asserts! (is-eq tx-sender CONTRACT-OWNER) ERR-OWNER-ONLY)
(map-set token-uris token-id uri)
(ok true)
)
)
;; Set token decimals (only owner)
(define-public (set-decimals (token-id uint) (decimals uint))
(begin
(asserts! (is-eq tx-sender CONTRACT-OWNER) ERR-OWNER-ONLY)
(map-set token-decimals token-id decimals)
(ok true)
)
)
(impl-trait ...)
(impl-trait 'ST1ZK4MRVTQQJMVAAJQWBV2WPQ87QV2851YCTHD7X.sip-013-trait-sft-standard.sip-013-trait)
Implements a trait (interface/standard) defined elsewhere. This ensures this contract complies with SIP-013, Stacksโ SFT standard.
define-fungible-token and define-non-fungible-token
(define-fungible-token sft-token)
(define-non-fungible-token sft-token-id {token-id: uint, owner: principal})
sft-token: A fungible token for total supply/balance tracking.sft-token-id: An NFT used for tagging balances for post-conditions.Structure: Each has a token-id and owner.
(define-constant CONTRACT-OWNER tx-sender)
Set the deployer as the contract owner.
Other constants are error codes:
(define-constant ERR-OWNER-ONLY (err u100))
(define-constant ERR-INSUFFICIENT-BALANCE (err u1))
...
(define-constant ERR-TOKEN-NOT-FOUND (err u404))
Used with asserts! to enforce logic rules.
(define-map token-balances {token-id: uint, owner: principal} uint)
Tracks how many units of a token a user owns.
(define-map token-supplies uint uint)
Total supply for each token ID.
(define-map token-decimals uint uint)
Number of decimal places for each token ID.
(define-map token-uris uint (string-ascii 256))
Metadata URI (e.g., image or metadata file) for each token.
These functions donโt modify blockchain state and can be called without paying fees.
get-balance
(get-balance (token-id uint) (who principal))
Returns how much of token-id a user owns.
get-overall-balance
(get-overall-balance (who principal))
Returns balance of sft-token (total fungible tokens held by user).
get-total-supply / get-overall-supply
(get-total-supply (token-id uint))
(get-overall-supply)
Total minted tokens per ID or across all.
get-decimals, get-token-uri
(get-decimals (token-id uint))
(get-token-uri (token-id uint))
Get token metadata (decimals/URI).
tag-nft-token-id
(tag-nft-token-id {token-id: uint, owner: principal})
Used for post-condition support:
- Burn existing NFT if it exists.
- Mint new one with the same data.
This enables tracking ownership changes on-chain.
set-balance
(set-balance token-id owner new-balance)
Updates balance map:
- If balance > 0 โ store it.
- If balance = 0 โ delete it.
transfer
(transfer token-id amount sender recipient)
Transfers amount of a token ID:
- Validates input:
- Amount must be > 0.
- Sender โ recipient.
- Sender has enough tokens.
- Sender is authorized (must be
tx-senderorcontract-caller).- Updates balances.
- Transfers associated fungible tokens.
- Tags NFTs.
- Logs event.
transfer-memo
(transfer-memo token-id amount sender recipient memo)
Same as transfer but logs a memo (buffer of 34 bytes).
Only the contract owner (deployer) can use these.
mint
(mint token-id amount recipient)
Mints new SFT units:
- Only owner can mint.
- Increases balance and supply.
- Mints corresponding fungible tokens.
- Tags NFT.
- Logs event.
burn
(burn token-id amount sender)
Burns tokens:
- Validates ownership and amount.
- Decreases balance and supply.
- Burns corresponding fungible tokens.
- Tags NFT.
- Logs event.
set-token-uri
(set-token-uri token-id uri)
Set metadata URI (only by owner).
set-decimals
(set-decimals token-id decimals)
Set number of decimal places (only by owner).
A standard for Semi-Fungible Tokens (SFTs) that act like fungible tokens with distinct IDs.
NFTsโshort for non-fungible tokensโare digital assets with unique identifiers. Non-fungible means that the tokens are not equivalent to one another. NFTs are created using Clarity smart contracts, a secure and predictable language designed for high-stakes blockchain applications. The most widely used NFT standard on Stacks is the SIP-009 (Stacks Improvement Proposal 009), which defines the basic functionality and metadata structure required for NFTs on the network.
An NFT marketplace is a digital platform where users can mint, buy, sell, and trade NFTs. These marketplaces serve as hubs for creators and collectors to exchange unique digital assets.
Familiar with Clarity
Clarity Book or Clarity Docs
Familiar with Stacks
Stacks Docs or Stacks.js Docs
Familiar with NFTs and SIP-009
SIP-009 NFT Standard
To implement the NFT marketplace, I wrote two smart contracts. One is for minting and transfer NFTs using the NFT trait, and the other is for the marketplace, where users can list, unlist, buy, and transfer NFTs between accounts. I will explain all the code in detail and provide the contract address link so you can review it.
;; SimpleNFT - A basic NF contract for stacks blockchain
;; implements sip-009 nft standard
;; clarity version- 3
๐ Trait Implementation
(impl-trait 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.nft-trait.nft-trait)
The SIP009 NFT trait on testnet
(define-trait sip009-nft-trait (
;; Last token ID, limited to uint range
(get-last-token-id () (response uint uint))
;; URI for metadata associated with the token
(get-token-uri (uint) (response (optional (string-ascii 256)) uint))
;; Owner of a given token identifier
(get-owner (uint) (response (optional principal) uint))
;; Transfer from the sender to a new principal
(transfer (uint principal principal) (response bool uint))
)
)
โ Error Constants
;; errors
(define-constant ERR-NOT-AUTHORIZED (err u100))
(define-constant ERR-NOT-FOUND (err u101))
(define-constant ERR-METADATA-FROZEN (err u102))
๐ฆ State Variables
;; Data variables
(define-data-var contract-owner principal tx-sender)
(define-data-var last-token-id uint u0)
(define-data-var metadata-frozen bool false)
contract-owner: Stores the address of the contract owner.last-token-id: Keeps track of the latest minted token ID.metadata-frozen: Prevents changes to metadata after itโs locked.๐บ๏ธ Data Maps
;; nft metadata mapping
(define-map token-uris uint (string-ascii 256))
;;token ownership
(define-map token-owners uint principal)
token-uris: Maps token ID to its metadata URI .token-owners: Maps token ID to the wallet address (principal) that owns it.These functions donโt modify blockchain state, only return data.
get-last-token-id;;get the last token id
(define-read-only (get-last-token-id)
(ok (var-get last-token-id))
)
get-token-uri;;get token uri
(define-read-only (get-token-uri (token-id uint))
(ok (map-get? token-uris token-id))
get-owner;; get the owner of the specified token
(define-read-only (get-owner (token-id uint))
(ok (map-get? token-owners token-id))
)
get-total-supply;get total supply
(define-read-only (get-total-supply)
(ok (var-get last-token-id))
)
These change state on the blockchain.
mint;; mint nft
(define-public (mint (metadata-uri (string-ascii 256)))
(let (
(token-id (+ (var-get last-token-id) u1))
(owner tx-sender)
)
(var-set last-token-id token-id)
(map-set token-owners token-id owner)
(map-set token-uris token-id metadata-uri)
;; (try! (nft-mint? asset-name asset-identifier recipient))
(ok token-id)
)
)
transfer(define-public (transfer (token-id uint) (sender principal) (recipient principal))
(begin
(asserts! (is-eq sender tx-sender) ERR-NOT-AUTHORIZED)
(asserts! (is-some (map-get? token-owners token-id)) ERR-NOT-FOUND)
(asserts! (is-eq (some sender) (map-get? token-owners token-id)) ERR-NOT-AUTHORIZED)
(ok (map-set token-owners token-id recipient))
)
)
sender.sender is actually the owner.set-token-uri;; Metadata Management Functions
(define-public (set-token-uri (token-id uint) (new-uri (string-ascii 256)))
(begin
(asserts! (not (var-get metadata-frozen)) ERR-METADATA-FROZEN)
(asserts! (is-some (map-get? token-owners token-id)) ERR-NOT-FOUND)
(asserts! (is-eq (some tx-sender) (map-get? token-owners token-id)) ERR-NOT-AUTHORIZED)
(map-set token-uris token-id new-uri)
(ok true)
)
)
freeze-metadata(define-public (freeze-metadata)
(begin
(asserts! (is-eq tx-sender (var-get contract-owner tx-sender)) ERR-NOT-AUTHORIZED) ;;
(var-set metadata-frozen true)
(ok true)
)
)
set-token-uri calls.;; SimpleNFT - A basic NF contract for stacks blockchain
;; implements sip-009 nft standard
;; clarity version- 3
(impl-trait 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.nft-trait.nft-trait)
;; errors
(define-constant ERR-NOT-AUTHORIZED (err u100))
(define-constant ERR-NOT-FOUND (err u101))
(define-constant ERR-METADATA-FROZEN (err u102))
;; Data variables
(define-data-var last-token-id uint u0)
(define-data-var metadata-frozen bool false)
;; nft metadata mapping
(define-map token-uris uint (string-ascii 256))
;;token ownership
(define-map token-owners uint principal)
;;SIP-009 functions
;; read only functions
;;get the last token id
(define-read-only (get-last-token-id)
(ok (var-get last-token-id))
)
;;get token uri
(define-read-only (get-token-uri (token-id uint))
(ok (map-get? token-uris token-id))
)
;; get the owner of the specified token
(define-read-only (get-owner (token-id uint))
(ok (map-get? token-owners token-id))
)
;;get total supply
(define-read-only (get-total-supply)
(ok (var-get last-token-id))
)
;;public functions
;; mint nft
(define-public (mint (metadata-uri (string-ascii 256)))
(let (
(token-id (+ (var-get last-token-id) u1))
(owner tx-sender)
)
(var-set last-token-id token-id)
(map-set token-owners token-id owner)
(map-set token-uris token-id metadata-uri)
;; (try! (nft-mint? asset-name asset-identifier recipient))
(ok token-id)
)
)
(define-public (transfer (token-id uint) (sender principal) (recipient principal))
(begin
(asserts! (is-eq sender tx-sender) ERR-NOT-AUTHORIZED)
(asserts! (is-some (map-get? token-owners token-id)) ERR-NOT-FOUND)
(asserts! (is-eq (some sender) (map-get? token-owners token-id)) ERR-NOT-AUTHORIZED)
(ok (map-set token-owners token-id recipient))
)
)
;; Metadata Management Functions
(define-public (set-token-uri (token-id uint) (new-uri (string-ascii 256)))
(begin
(asserts! (not (var-get metadata-frozen)) ERR-METADATA-FROZEN)
(asserts! (is-some (map-get? token-owners token-id)) ERR-NOT-FOUND)
(asserts! (is-eq (some tx-sender) (map-get? token-owners token-id)) ERR-NOT-AUTHORIZED)
(map-set token-uris token-id new-uri)
(ok true)
)
)
(define-public (freeze-metadata)
(begin
(asserts! (is-eq tx-sender tx-sender) ERR-NOT-AUTHORIZED) ;; Replace with your owner check if needed
(var-set metadata-frozen true)
(ok true)
)
)
(define-constant contract-owner tx-sender)
(define-constant PLATFORM-FEE-BPS u250) ;;2.5% basic fee for now
These are predefined error codes for common issues:
;;ERROR
(define-constant ERR-NOT-AUTHORIZED (err u401))
(define-constant ERR-LISTING-EXPIRED (err u402))
(define-constant ERR-PRICE-MISMATCHED (err u403))
(define-constant ERR-ALREADY-LISTED (err u404))
(define-constant ERR-NFT-TRANSFER-FAILED (err u405))
(define-constant ERR-NOT-FOUND (err u406))
(define-constant ERR-OWNER-CANNOT-BUY (err u407))
(define-constant ERR-INSUFFICIENT-FUNDS (err u408))
;;Data structures
(define-map listings {token-id: uint}
{seller: principal, price: uint, expiry: uint, is-active: bool}
)
token-id, Values: seller info, price, expiry block, and listing status.;;Track paltform fee
(define-data-var total-platform-fees uint u0)
is-listed;check if token is listed
(define-read-only (is-listed (token-id uint))
(match (map-get? listings { token-id: token-id})
listing (and (get is-active listing)
(< stacks-block-height (get expiry listing)))
false
)
)
Checks if a token is currently listed and hasnโt expired.
Returns true if:
is-active is true,expiry is greater than current block height.get-listing;;get listing details if active
(define-read-only (get-listing (token-id uint))
(map-get? listings {token-id: token-id})
)
Fetches full listing info for a token if it exists.
Returns:
none otherwise.calculate-platform-fee;;calculate fees for the given amount
(define-read-only (calculate-platform-fee (amount uint))
(/ (* amount PLATFORM-FEE-BPS) u10000)
)
amount = 1000, fee = 2.5% = 25.get-total-platform-fees;;get total platform fee of the platform
(define-read-only (get-total-platform-fees)
(var-get total-platform-fees)
)
list-nft;; list nft for sale
(define-public (list-nft (token-id uint) (price uint) (expiry uint))
(let (
(nft-owner-opt (unwrap! (contract-call? .SimpleNFT get-owner token-id) (err u0)))
)
;; Check if the owner is none
(asserts! (is-some nft-owner-opt) ERR-NOT-AUTHORIZED)
(let (
(nft-owner (unwrap! nft-owner-opt (err u0)))
)
;; Validations
(asserts! (is-eq tx-sender nft-owner) ERR-NOT-AUTHORIZED)
(asserts! (> expiry stacks-block-height) ERR-LISTING-EXPIRED)
(asserts! (> price u0) ERR-PRICE-MISMATCHED)
(asserts! (not (is-listed token-id)) ERR-ALREADY-LISTED)
;; Transfer NFT to this contract (escrow)
(unwrap! (contract-call? .SimpleNFT transfer token-id tx-sender (as-contract tx-sender)) ERR-NFT-TRANSFER-FAILED)
;; Create the listing
(map-set listings
{ token-id: token-id }
{
seller: tx-sender,
price: price,
expiry: expiry,
is-active: true
}
)
(ok true)
)
)
)
Lists a token for sale and transfers NFT to escrow (Marketplace contract).
Includes checks to ensure:
SimpleNFT.get-owner).SimpleNFT.transfer.Stores listing in the listings map as active.
cancel-listing;;cancel a listings
(define-public (cancel-listing (token-id uint))
(let (
(listing (unwrap! (map-get? listings { token-id: token-id}) ERR-NOT-FOUND))
)
;;only seller can cancel
(asserts! (is-eq tx-sender (get seller listing)) ERR-NOT-AUTHORIZED)
;;ensure listing is active
(asserts! (get is-active listing) ERR-NOT-FOUND)
;;Mark lisitng is inactive
(map-set listings {token-id: token-id} (merge listing {is-active: false}))
;;Return nft to seller from escrow
(as-contract (contract-call? .SimpleNFT transfer token-id tx-sender (get seller listing))))
)
Cancels an active listing and returns NFT to seller.
Includes:
SimpleNFT.transfer.buy-nft;; buy listed nft
(define-public (buy-nft (token-id uint))
(let (
(listing (unwrap! (map-get? listings { token-id: token-id }) ERR-NOT-FOUND))
(price (get price listing))
(seller (get seller listing))
(platform-fee (calculate-platform-fee price))
(seller-amount (- price platform-fee))
)
;; Check conditions
(asserts! (get is-active listing) ERR-NOT-FOUND)
(asserts! (< stacks-block-height (get expiry listing)) ERR-LISTING-EXPIRED)
(asserts! (not (is-eq tx-sender seller)) ERR-OWNER-CANNOT-BUY)
;; Update platform fees
(var-set total-platform-fees (+ (var-get total-platform-fees) platform-fee))
;; Mark listing as inactive
(map-set listings
{ token-id: token-id }
(merge listing { is-active: false })
)
;; Pay seller
(unwrap! (stx-transfer? seller-amount tx-sender seller) ERR-INSUFFICIENT-FUNDS)
;; Pay platform fee
(unwrap! (stx-transfer? platform-fee tx-sender contract-owner) ERR-INSUFFICIENT-FUNDS)
;; Transfer NFT to buyer from escrow
(as-contract
(contract-call? .SimpleNFT transfer token-id tx-sender tx-sender)
)
)
)
Allows a buyer to purchase a listed NFT.
Includes:
total-platform-fees.SimpleNFT.transfer.update-listing-price;; Update a listing's price
(define-public (update-listing-price (token-id uint) (new-price uint))
(let (
(listing (unwrap! (map-get? listings { token-id: token-id }) ERR-NOT-FOUND))
)
;; Validations
(asserts! (is-eq tx-sender (get seller listing)) ERR-NOT-AUTHORIZED)
(asserts! (get is-active listing) ERR-NOT-FOUND)
(asserts! (< stacks-block-height (get expiry listing)) ERR-LISTING-EXPIRED)
(asserts! (> new-price u0) ERR-PRICE-MISMATCHED)
;; Update the listing price
(map-set listings
{ token-id: token-id }
(merge listing { price: new-price })
)
(ok true)
)
)
Updates the price of an active, unexpired listing.
Validates:
Then updates listing with the new price.
withdraw-platform-fee;; Administration function to withdraw paltform fee
(define-public (withdraw-platform-fee)
(let (
(fee-amount (var-get total-platform-fees))
)
(asserts! (is-eq tx-sender contract-owner) ERR-NOT-AUTHORIZED)
(asserts! (> fee-amount u0) ERR-INSUFFICIENT-FUNDS)
;;Reset counter
(var-set total-platform-fees u0)
;; transfer funds to contract owner
(as-contract (stx-transfer? fee-amount tx-sender contract-owner))
)
)
Allows the contract owner to withdraw collected platform fees.
Includes:
;; Makrketplace contract where users can list, unlist and can sell their nfts
;; clarity version 3
(define-constant contract-owner tx-sender)
(define-constant PLATFORM-FEE-BPS u250) ;;2.5% basic fee for now
;;eRROR
(define-constant ERR-NOT-AUTHORIZED (err u401))
(define-constant ERR-LISTING-EXPIRED (err u402))
(define-constant ERR-PRICE-MISMATCHED (err u403))
(define-constant ERR-ALREADY-LISTED (err u404))
(define-constant ERR-NFT-TRANSFER-FAILED (err u405))
(define-constant ERR-NOT-FOUND (err u406))
(define-constant ERR-OWNER-CANNOT-BUY (err u407))
(define-constant ERR-INSUFFICIENT-FUNDS (err u408))
;;Data structures
(define-map listings {token-id: uint}
{seller: principal, price: uint, expiry: uint, is-active: bool}
)
;;Track paltform fee
(define-data-var total-platform-fees uint u0)
;;check if token is listed
(define-read-only (is-listed (token-id uint))
(match (map-get? listings { token-id: token-id})
listing (and (get is-active listing)
(< stacks-block-height (get expiry listing)))
false
)
)
;;get listing details if active
(define-read-only (get-listing (token-id uint))
(map-get? listings {token-id: token-id})
)
;;calculate fees for the given amount
(define-read-only (calculate-platform-fee (amount uint))
(/ (* amount PLATFORM-FEE-BPS) u10000)
)
;;get total platform fee of the platform
(define-read-only (get-total-platform-fees)
(var-get total-platform-fees)
)
;;listing functions
;; list nft for sale
(define-public (list-nft (token-id uint) (price uint) (expiry uint))
(let (
(nft-owner-opt (unwrap! (contract-call? .SimpleNFT get-owner token-id) (err u0)))
)
;; Check if the owner is none
(asserts! (is-some nft-owner-opt) ERR-NOT-AUTHORIZED)
(let (
(nft-owner (unwrap! nft-owner-opt (err u0)))
)
;; Validations
(asserts! (is-eq tx-sender nft-owner) ERR-NOT-AUTHORIZED)
(asserts! (> expiry stacks-block-height) ERR-LISTING-EXPIRED)
(asserts! (> price u0) ERR-PRICE-MISMATCHED)
(asserts! (not (is-listed token-id)) ERR-ALREADY-LISTED)
;; Transfer NFT to this contract (escrow)
(unwrap! (contract-call? .SimpleNFT transfer token-id tx-sender (as-contract tx-sender)) ERR-NFT-TRANSFER-FAILED)
;; Create the listing
(map-set listings
{ token-id: token-id }
{
seller: tx-sender,
price: price,
expiry: expiry,
is-active: true
}
)
(ok true)
)
)
)
;;cancel a listings
(define-public (cancel-listing (token-id uint))
(let (
(listing (unwrap! (map-get? listings { token-id: token-id}) ERR-NOT-FOUND))
)
;;only seller can cancel
(asserts! (is-eq tx-sender (get seller listing)) ERR-NOT-AUTHORIZED)
;;ensure listing is active
(asserts! (get is-active listing) ERR-NOT-FOUND)
;;Mark lisitng is inactive
(map-set listings {token-id: token-id} (merge listing {is-active: false}))
;;Return nft to seller from escrow
(as-contract (contract-call? .SimpleNFT transfer token-id tx-sender (get seller listing))))
)
;; Purchase functions
;; buy listed nft
(define-public (buy-nft (token-id uint))
(let (
(listing (unwrap! (map-get? listings { token-id: token-id }) ERR-NOT-FOUND))
(price (get price listing))
(seller (get seller listing))
(platform-fee (calculate-platform-fee price))
(seller-amount (- price platform-fee))
)
;; Check conditions
(asserts! (get is-active listing) ERR-NOT-FOUND)
(asserts! (< stacks-block-height (get expiry listing)) ERR-LISTING-EXPIRED)
(asserts! (not (is-eq tx-sender seller)) ERR-OWNER-CANNOT-BUY)
;; Update platform fees
(var-set total-platform-fees (+ (var-get total-platform-fees) platform-fee))
;; Mark listing as inactive
(map-set listings
{ token-id: token-id }
(merge listing { is-active: false })
)
;; Pay seller
(unwrap! (stx-transfer? seller-amount tx-sender seller) ERR-INSUFFICIENT-FUNDS)
;; Pay platform fee
(unwrap! (stx-transfer? platform-fee tx-sender contract-owner) ERR-INSUFFICIENT-FUNDS)
;; Transfer NFT to buyer from escrow
(as-contract
(contract-call? .SimpleNFT transfer token-id tx-sender tx-sender)
)
)
)
;; Update a listing's price
(define-public (update-listing-price (token-id uint) (new-price uint))
(let (
(listing (unwrap! (map-get? listings { token-id: token-id }) ERR-NOT-FOUND))
)
;; Validations
(asserts! (is-eq tx-sender (get seller listing)) ERR-NOT-AUTHORIZED)
(asserts! (get is-active listing) ERR-NOT-FOUND)
(asserts! (< stacks-block-height (get expiry listing)) ERR-LISTING-EXPIRED)
(asserts! (> new-price u0) ERR-PRICE-MISMATCHED)
;; Update the listing price
(map-set listings
{ token-id: token-id }
(merge listing { price: new-price })
)
(ok true)
)
)
;; Administration function to withdraw paltform fee
(define-public (withdraw-platform-fee)
(let (
(fee-amount (var-get total-platform-fees))
)
(asserts! (is-eq tx-sender contract-owner) ERR-NOT-AUTHORIZED)
(asserts! (> fee-amount u0) ERR-INSUFFICIENT-FUNDS)
;;Reset counter
(var-set total-platform-fees u0)
;; transfer funds to contract owner
(as-contract (stx-transfer? fee-amount tx-sender contract-owner))
)
)
Digital assets commonly fall in one of two categories; namely, they are either fungible or non-fungible. Fungible tokens are assets like the native Stacks Token (STX), stablecoins, and so on. Non-Fungible Tokens (NFTs) are tokens expressed as digital artwork and other use-cases that demand them to be globally unique. However, not all asset classes can be represented as either exclusively fungible or non-fungible tokens. This is where semi-fungible tokens come in.
Semi-fungible tokens are a combination of the aforementioned digital asset types in that they have both an identifier and an amount. A single semi-fungible token class can therefore represent a multitude of digital assets within a single contract. A user may own ten tokens of ID 1 and twenty tokens of ID 2, for example. It effectively means that one contract can represent any combination of fungible and non-fungible tokens.
Some real-world examples can highlight the value and use-cases of semi-fungible tokens. People who collect trading cards or postage stamps will know that not all of them are of equal value, although there may be more than one of a specific kind. Video games can feature in-game items that have different economic values compared to others. There are many more such parallels to be found.
Semi-fungible tokens give operators the ability to create new token classes at will. They no longer need to deploy a new contract every time new token type is introduced. It greatly simplifies the flow for applications that require many new tokens and token types to come into existence.
Benefits of using semi-fungible tokens:
The Semi-Fungible Token trait, sip013-semi-fungible-token-trait, has 8
functions:
(get-balance ((token-id uint) (who principal)) (response uint uint))
Returns the token type balance token-id of a specific principal who as an
unsigned integer wrapped in an ok response. It has to respond with u0 if the
principal does not have a balance of the specified token or if no token with
token-id exists. The function should never return an err response and is
recommended to be defined as read-only.
(get-overall-balance ((who principal)) (response uint uint))
Returns the overall SFT balance of a specific principal who. This is the sum
of all the token type balances of that principal. The function has to respond
with a zero value of u0 if the principal does not have any balance. It should
never return an err response and is recommended to be defined as read-only.
(get-total-supply ((token-id uint)) (response uint uint))
Returns the total supply of a token type. If the token type has no supply or
does not exist, the function should respond with u0. It should never return an
err response and is recommended to be defined as read-only.
(get-overall-supply () (response uint uint))
Returns the overall supply of the SFT. This is the sum of all token type
supplies. The function should never return an err response and is recommended
to be defined as read-only.
(get-decimals ((token-id uint)) (response uint uint))
Returns the decimal places of a token type. This is purely for display reasons, where external applications may read this value to provide a better user experience. The ability to specify decimals for a token type can be useful for applications that represent different kinds of assets using one SFT. For example, a game may have an in-game currency with two decimals and a fuel commodity expressed in litres with four decimals.
(get-token-uri ((token-id uint)) (response (optional (string-ascii 256)) uint))
Returns an optional ASCII string that is a valid URI which resolves to this
token typeโs metadata. These files can provide off-chain metadata about that
particular token type, like descriptions, imagery, or any other information. The
exact structure of the metadata is out of scope for this SIP. However, the
metadata file should be in JSON format and should include a sip property
containing a number:
{
"sip": 16
// ... any other properties
}
Applications consuming these metadata files can base display capabilities on the
sip value. It should refer to a SIP number describing a JSON metadata
standard.
(transfer ((token-id uint) (amount uint) (sender principal) (recipient principal)) (response bool uint))
Transfer a token from the sender to the recipient. It is recommended to leverage
Clarity primitives like ft-transfer? to help safeguard users. The function
should return (ok true) on success or an err response containing an unsigned
integer on failure. The failure codes follow the existing conventions of
stx-transfer? and ft-transfer?.
| Error code | Description |
|---|---|
u1 |
The sender has insufficient balance. |
u2 |
The sender and recipient are the same principal. |
u3 |
Amount is u0. |
u4 |
The sender is not authorised to transfer tokens. |
Error code u4 is broad and may be returned under different cirumstances. For
example, a token contract with an allowance mechanism can return (err u4)
when the sender parameter has no allowance for the specified token amount or
if the sender is not equal to tx-sender or contract-owner. A token contract
without an allowance mechanism can return (err u4) simply when the sender is
not what is expected.
Since it is possible for smart contracts to own tokens, it is recommended to
check for both tx-sender and contract-caller as it allows smart contracts to
transfer tokens it owns without having to resort to using as-contract. Such a
guard can be constructed as follows:
(asserts! (or (is-eq sender tx-sender) (is-eq sender contract-caller)) (err u4))
The transfer function should emit a special transfer event, as detailed in the
Events section of this document.
(transfer-memo ((token-id uint) (amount uint) (sender principal) (recipient principal) (memo (buff 34))) (response bool uint))
Transfer a token from the sender to the recipient and emit a memo. This function
follows the exact same procedure as transfer but emits the provided memo via
(print memo). The memo event should be the final event emitted by the
contract. (See also the events section of this document below.)
A definition of the trait is provided below.
(define-trait sip013-semi-fungible-token-trait
(
;; Get a token type balance of the passed principal.
(get-balance (uint principal) (response uint uint))
;; Get the total SFT balance of the passed principal.
(get-overall-balance (principal) (response uint uint))
;; Get the current total supply of a token type.
(get-total-supply (uint) (response uint uint))
;; Get the overall SFT supply.
(get-overall-supply () (response uint uint))
;; Get the number of decimal places of a token type.
(get-decimals (uint) (response uint uint))
;; Get an optional token URI that represents metadata for a specific token.
(get-token-uri (uint) (response (optional (string-ascii 256)) uint))
;; Transfer from one principal to another.
(transfer (uint uint principal principal) (response bool uint))
;; Transfer from one principal to another with a memo.
(transfer-memo (uint uint principal principal (buff 34)) (response bool uint))
)
)
Semi-fungible token contracts should emit custom events in certain situations
via print. These events should be emitted after any built-in token events
(such as those emitted by ft-transfer?) and before the memo in the case of
transfer-memo and transfer-many-memo.
| Event name | Tuple structure | Description |
|---|---|---|
sft_transfer |
{type: "sft_transfer", token-id: uint, amount: uint, sender: principal, recipient: principal} |
Emitted when tokens are transferred. |
sft_mint |
{type: "sft_mint", token-id: uint, amount: uint, recipient: principal} |
Emitted when new tokens are minted. |
sft_burn |
{type: "sft_burn", token-id: uint, amount: uint, sender: principal} |
Emitted when tokens are burned. |
Contract implementers should always use the built-in native assets that are provided as Clarity primitives whenever possible. This allows clients to use Post Conditions (explained below) and takes advantage of other benefits like native events and asset balances. However, there are no language primitives specific to semi-fungible tokens. The reference implementation included in this SIP therefore leverages the primitives to the extent that Clarity allows for.
The recommended native asset primitives to use:
define-fungible-tokenft-burn?ft-get-balanceft-get-supplyft-mint?ft-transfer?define-non-fungible-tokennft-burn?nft-mint?nft-transfer?Applications that interact with semi-fungible token contracts should validate if those contracts implement the SFT trait. If they do, then the application can use the interface described in this SIP for making transfers and getting other token information.
All of the functions in this trait return the response type, which is a
requirement of trait definitions in Clarity. However, some of these functions
should be โfail-proofโ, in the sense that they should never return an error. The
โfail-proofโ functions are those that have been recommended as read-only. If a
contract that implements this trait returns an error for these functions, it may
be an indication of a faulty contract, and consumers of those contracts should
proceed with caution.
The Stacks blockchain includes a feature known as Post Conditions. By defining post conditions, users can create transactions that include pre-defined guarantees about what might happen in a contract. These post conditions can also be used to provide guarantees for custom fungible and non-fungible tokens that were defined using built-in Clarity primitives.
There are no Clarity primitive counterparts for semi-fungible tokens, but contract developers can leverage a combination of post conditions to achieve the same result.
There are two factors that should be checked by post conditions:
To that end, it is recommended that developers use both Clarity primitives in
their design. Semi-fungible token contracts can achieve complete post condition
coverage by using both define-fungible-token and define-non-fungible-token.
A minimal and sufficient strategy that provides full post condition coverage is
to create a โburn-and-mintโ mechanism for token creation and transfers. Such an
SFT contract tracks quantities using an internal fungible token and token IDs
using an internal non-fungible token. Since token identifiers for assets defined
by define-non-fungible-token need to be unique, an additional component is
added to ensure token IDs can be expressed per owner. (As SFTs may have a
quantity of a certain token ID that is larger than one.) The token ID type
identifier thus becomes {token-id: uint, owner: principal}. Wallet software
can then easily determine the post conditions for the amount as well as the
token ID.
An example of a burn-and-mint mechanism is provided below. The reference implementation at the end of the document features a full SFT contract that includes burn-and-mint.
(define-fungible-token semi-fungible-token)
(define-non-fungible-token semi-fungible-token-id {token-id: uint, owner: principal})
(define-public (transfer (token-id uint) (amount uint) (sender principal) (recipient principal))
(begin
;; <guards>
;; <token transfer logic>
(try! (tag-nft-token-id {token-id: token-id, owner: sender}))
(try! (tag-nft-token-id {token-id: token-id, owner: recipient}))
;; <balance updates>
(print {type: "sft_transfer", token-id: token-id, amount: amount, sender: sender, recipient: recipient})
(ok true)
)
)
(define-private (tag-nft-token-id (nft-token-id {token-id: uint, owner: principal}))
(begin
(and
(is-some (nft-get-owner? semi-fungible-token-id nft-token-id))
(try! (nft-burn? semi-fungible-token-id nft-token-id (get owner nft-token-id)))
)
(nft-mint? semi-fungible-token-id nft-token-id (get owner nft-token-id))
)
)
For strategies on how to best guard a semi-fungible token contract with post conditions, see the reference implementation included with SIP (contained in SIP-013-001.tar.gz), or by following the link at the end of this document.
SIP013 Semi-fungible tokens can also optionally implement the trait
sip013-send-many-trait to offer a built-in โsend-manyโ features for bulk token
transfers. Adding this to the token contract itself may have runtime cost
benefits as of Stacks 2.0. The send-many trait contains 2 additional functions.
(transfer-many ((transfers (list 200 {token-id: uint, amount: uint, sender: principal, recipient: principal}))) (response bool uint))
Transfer many tokens in one contract call. Each transfer should follow the exact
same procedure as if it were an individual transfer call. The whole function
call should fail with an err response if one of the transfers fails.
(transfer-many-memo ((transfers (list 200 {token-id: uint, amount: uint, sender: principal, recipient: principal, memo: (buff 34)}))) (response bool uint))
Transfer many tokens in one contract call and emit a memo for each. This
function follows the same procedure as transfer-many but will emit the memo
contained in the tuple after each transfer. The whole function call should fail
with an err response if one of the transfers fails.
A definition of the optional send-many trait is provided below.
(define-trait sip013-transfer-many-trait
(
;; Transfer many tokens at once.
(transfer-many ((list 200 {token-id: uint, amount: uint, sender: principal, recipient: principal})) (response bool uint))
;; Transfer many tokens at once with memos.
(transfer-many-memo ((list 200 {token-id: uint, amount: uint, sender: principal, recipient: principal, memo: (buff 34)})) (response bool uint))
)
)
This Semi-Fungible Token standard is similar to the EIP-1155 standard found in the Ethereum/EVM space. An ERC1155 token is a semi-fungible token that admits both a token ID as well as a supply per token ID, just like SIP013. They differ in that the ERC1155 standard describes an approval mechanism as well as โsafe transferโ functions that are specific to Ethereum/EVM. Although the biggest difference is the requirement of post condition support, a mechanism that does not exist in Ethereum.
These traits will be considered activated when they are deployed to mainnet and 3 different implementations of the main trait have been deployed to mainnet, no later than Bitcoin block 769,950. Additionally, no revisions to the traits were made after Bitcoin block 756,810.
Tokens are digital assets registered on blockchain through a smart contract. A non-fungible token (NFT) is a token that is globally unique and can be identified through its unique identifier.
In blockchains with smart contracts, including the Stacks blockchain, developers and users can use smart contracts to register and interact with non-fungible tokens.
The Stacks blockchainโs programming language for developing smart contracts, Clarity, has built-in language primitives to define and use non-fungible tokens. Although those primitives exists, there is value in defining a common interface (known in Clarity as a โtraitโ) that allows different smart contracts to interoperate with non-fungible token contracts in a reusable way. This SIP defines that trait.
Each NFT always belong to one smart contract. NFTs of a smart contract are enumerated starting at 1. The current last ID is provided by a smart contract function. The asset ID together with the contract ID defines a globally unique NFT.
Every SIP-009 compliant smart contract in Stacks blockchain must implement the trait, nft-trait, defined in the Trait section and must meet the requirements for the following functions:
(get-last-token-id () (response uint uint))
Takes no arguments and returns the identifier for the last NFT registered using the contract. The returned ID can be used as the upper limit when iterating through all NFTs.
This function must never return an error response. It can be defined as read-only, i.e. define-read-only.
(get-token-uri (uint) (response (optional (string-ascii 256)) uint))
Takes an NFT identifier and returns a response containing a valid URI which resolves to the NFTโs metadata. The URI string must be wrapped in an optional. If the corresponding NFT doesnโt exist or the contract doesnโt maintain metadata, the response must be (ok none). If a valid URI exists for the NFT, the response must be (ok (some "<URI>")). The length of the returned URI is limited to 256 characters. The specification of the metadata should be covered in a separate SIP.
This function must never return an error response. It can be defined as read-only, i.e. define-read-only.
(get-owner (uint) (response (optional principal) uint))
Takes an NFT identifier and returns a response containing the principal owning the NFT with the given identifier. The principal must be wrapped in an optional. If the corresponding NFT doesnโt exist, the response must be (ok none). The owner can be a contract principal.
If a call to function get-owner returns some principal A, then it must return the same value until the transfer function is called with principal A as the sender.
For any call to get-owner with an ID greater than the last token ID returned by the get-last-token-id function, the call must return a response (ok none).
This function must never return an error response. It can be defined as read-only, i.e. define-read-only.
(transfer (uint principal principal) (response bool uint))
The function changes the ownership of the NFT for the given identifier from the sender principal to the recipient principal.
This function must be defined with define-public, as it alters state, and must be externally callable.
After a successful call to transfer, the function get-owner must return the recipient of the transfer call as the new owner.
For any call to transfer with an ID greater than the last token ID returned by the get-last-token-id function, the call must return an error response.
It is recommended to use error codes from standardized list of codes and implement the function for converting the error codes to messages function that are defined in a separate SIP.
(define-trait nft-trait
(
;; Last token ID, limited to uint range
(get-last-token-id () (response uint uint))
;; URI for metadata associated with the token
(get-token-uri (uint) (response (optional (string-ascii 256)) uint))
;; Owner of a given token identifier
(get-owner (uint) (response (optional principal) uint))
;; Transfer from the sender to a new principal
(transfer (uint principal principal) (response bool uint))
)
)
Although it is not possible to mandate in a Clarity trait, contract implementers must define at least one built-in native non-fungible asset class that are provided as Clarity primitives. This allows clients to use Post Conditions (explained below), and takes advantages of other benefits, like native support for these asset balances and transfers through stacks-blockchain-api. The reference implementations included in this SIP use the native asset primitives, and provide a good boilerplate for their usage.
The native asset functions include:
define-non-fungible-tokennft-burn?nft-get-owner?nft-mint?nft-transfer?The following requirements for using native asset functions are defined:
If the transfer function is called from a client without a post-condition in deny mode or without any NFT condition about a changed owner, then the function call must fail with abort_by_post_condition.
Developers who wish to use a non-fungible token contract in an application should first be provided, or keep track of, various different non-fungible token implementations. When validating a non-fungible token contract, they should fetch the interface and/or source code for that contract. If the contract implements the trait, then the application can use this standardโs contract interface for making transfers and getting other details defined in this standard.
All of the functions in this trait return the response type, which is a requirement of trait definitions in Clarity. However, some of these functions should be โfail-proofโ, in the sense that they should never return an error. These โfail-proofโ functions are those that have been recommended as read-only. If a contract that implements this trait returns an error for these functions, it may be an indication of a non-compliant contract, and consumers of those contracts should proceed with caution.
The Stacks blockchain includes a feature known as โPost-Conditionsโ or โConstraintsโ. By defining post-conditions, users can create transactions that include pre-defined guarantees about what might happen in that contract.
For example, when applications call the transfer function, they should always use post conditions to specify that the new owner of the NFT is the recipient principal in the transfer function call.
Ethereum has EIP 721 that defined non-fungible tokens on the Ethereum blockchain. Notable differences are that the transfer function in EIP 721 uses a different ordering of the arguments ending with the token id. The transfer function in this SIP uses the token ID as the first argument which is in line with the other native functions in Clarity. Furthermore, this SIP only defines a function for getting the URI pointing to the metadata of an NFT. The specifications for schema and other properties of the token metadata should be defined in a separate SIP.
This SIP is activated if 5 contracts are deployed that use the same trait that follows this specification. This must happen before Bitcoin tip #700,000.
A trait that follows this specification is available on mainnet as SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait.nft-trait.
https://github.com/friedger/clarity-smart-contracts/blob/master/contracts/sips/nft-trait.clar
;; Multiplayer Counter contract
(define-map counters principal uint)
(define-read-only (get-count (who principal))
(default-to u0 (map-get? counters who))
)
(define-public (count-up)
(ok (map-set counters tx-sender (+ (get-count tx-sender) u1)))
)
get-count: Read-only function to check a userโs count.count-up: Public function to increase the senderโs count by 1
;; Multiplayer Counter contract
(define-map counters principal uint)
counters.principal (the userโs blockchain address).uint (unsigned integer โ the counter value).
(define-read-only (get-count (who principal))
(default-to u0 (map-get? counters who))
)
who โ a user address.u0 (default value 0).
(define-public (count-up)
(ok (map-set counters tx-sender (+ (get-count tx-sender) u1)))
)
tx-sender: The address of the user calling this function.get-count.counters map with the new value.ok response.Letโs walk through an example interaction:
(get-count tx-sender)
0 because thereโs no entry yet.count-up
(count-up)
0).1.counters map: counters[User A] = 1.count-up again1, adds 1 โ value becomes 2, and updates the map.get-count will return 0.| Function | Type | Description |
|---|---|---|
counters |
Map | Stores each userโs counter. |
get-count |
Read-only | Returns current count or 0 if not found. |
count-up |
Public | Increments the callerโs counter by 1. |
Imagine a scoreboard where every player has their own slot. When a player hits a button, only their score increases. No one can touch your slot but you.
]]>(define-map balances { account: principal } uint)
;; #[allow(unchecked_data)]
(define-public (deposit (amount uint))
(let ((current (default-to u0 (map-get? balances { account: tx-sender }))))
(begin
(map-set balances { account: tx-sender } (+ current amount))
(ok true)
)
)
)
(define-public (withdraw (amount uint))
(let ((current (default-to u0 (map-get? balances { account: tx-sender }))))
(if (>= current amount)
(begin
(map-set balances { account: tx-sender } (- current amount))
(ok true)
)
(err u402) ;; insufficient funds
)
)
)
deposit: Add tokens to the senderโs balance.withdraw: Subtract tokens if the sender has enough.
(define-map balances { account: principal } uint)
balances stores user balances.{ account: principal } โ each userโs address.uint โ the unsigned integer balance.(define-public (deposit (amount uint))
(let ((current (default-to u0 (map-get? balances { account: tx-sender }))))
(begin
(map-set balances { account: tx-sender } (+ current amount))
(ok true)
)
)
)
amount to deposit.0.(ok true) to confirm success.(define-public (withdraw (amount uint))
(let ((current (default-to u0 (map-get? balances { account: tx-sender }))))
(if (>= current amount)
(begin
(map-set balances { account: tx-sender } (- current amount))
(ok true)
)
(err u402) ;; insufficient funds
)
)
)
(err u402) โ an error for insufficient funds.Letโs walk through a real-world scenario:
(deposit u100)
u0 if new).100.{ account: UserA } โ 100.(withdraw u30)
(err u402)
Which can be interpreted in your frontend as โInsufficient Fundsโ.
Think of it like a digital piggy bank for each user:
deposit).withdraw).| Component | Purpose |
|---|---|
balances |
Map storing user balances |
deposit |
Adds tokens to the userโs vault |
withdraw |
Removes tokens if user has enough |
err u402 |
Error code for โInsufficient Fundsโ |
(define-map messages { user: principal } {message: (string-utf8 100)})
(define-public (write-message (msg (string-utf8 100)))
(begin
(map-set messages { user: tx-sender } { message: msg })
(ok true)
)
)
(define-public (read-message (user principal))
(match (map-get? messages { user: user })
value (ok (get message value))
(err u404)
)
)
(define-public (read-message (user principal))
(match (map-get? messages { user: user })
value (ok (get message value))
(err u404)
)
)
This smart contract allows users to write a single message tied to their address (like a profile status), and allows others to read those messages. All data is stored on-chain, meaning itโs transparent and permanent until overwritten.
write-message: Save/update your message.read-message: Read another userโs message.see-message: Low-level view of a userโs message record (for dev/debug).
(define-map messages { user: principal } {message: (string-utf8 100)})
{ user: principal } โ userโs blockchain address.{ message: (string-utf8 100) } โ a UTF-8 string up to 100 characters.(define-public (write-message (msg (string-utf8 100)))
(begin
(map-set messages { user: tx-sender } { message: msg })
(ok true)
)
)
tx-sender to identify the writer.{ message: msg } in the messages map.(ok true) to confirm the update.(define-public (read-message (user principal))
(match (map-get? messages { user: user })
value (ok (get message value))
(err u404)
)
)
user (their address) as input.message and returns it with ok.(err u404) (message not found).(define-read-only (see-message (recipient principal))
(ok (map-get? messages recipient))
)
(write-message "Hello, Stacks!")
The contract saves:
{ user: UserA } โ { message: "Hello, Stacks!" }
(read-message UserA)
ok "Hello, Stacks!".err u404.(see-message UserA)
Output:
ok (some { message: "Hello, Stacks!" })
or ok none if thereโs no message.
| Component | Purpose |
|---|---|
messages map |
Stores one message per user |
write-message |
Lets users post or update their message |
read-message |
Lets anyone read another userโs message |
see-message |
Returns the full map entry (debug-style) |
err u404 |
Error if no message found for a user |
Imagine a global public board where:
(define-map votes { candidate: (string-utf8 20) } uint)
;; #[allow(unchecked_data)]
(define-public (vote (candidate (string-utf8 20)))
(let ((count (default-to u0 (map-get? votes { candidate: candidate }))))
(begin
(map-set votes { candidate: candidate } (+ count u1))
(ok true)
)
)
)
(define-public (get-votes (candidate (string-utf8 20)))
(ok (default-to u0 (map-get? votes { candidate: candidate })))
)
This contract allows users to vote for candidates, with votes stored on-chain. Anyone can cast a vote for a candidate by name, and anyone can check how many votes a candidate has received.
vote: Increases vote count for a candidate.get-votes: Returns the total votes for a candidate.(define-map votes { candidate: (string-utf8 20) } uint)
votes tracks vote totals.{ candidate: string-utf8(20) } โ candidate name (max 20 chars).uint โ the number of votes received.(define-public (vote (candidate (string-utf8 20)))
(let ((count (default-to u0 (map-get? votes { candidate: candidate }))))
(begin
(map-set votes { candidate: candidate } (+ count u1))
(ok true)
)
)
)
candidate โ the name of the candidate being voted for.map-get?.
0 using default-to.(ok true) as confirmation.(define-public (get-votes (candidate (string-utf8 20)))
(ok (default-to u0 (map-get? votes { candidate: candidate })))
)
candidate name as input.0.ok.Letโs walk through an example:
(vote "Alice")
0 (if first vote).1.{ candidate: "Alice" } โ 1.(vote "Bob")
{ candidate: "Bob" } โ 1.(vote "Alice")
1.2.(get-votes "Alice")
(ok u2)
| Function | Purpose |
|---|---|
votes map |
Stores each candidateโs vote count |
vote |
Increments a candidateโs vote count |
get-votes |
Retrieves vote count for any candidate |
default-to |
Ensures candidates with no votes return 0 |
Think of a public election box:
;; Time-Locked STX Vault - A contract that allows users to deposit STX and lock them for a specified period
;; Users can only withdraw once the specified block height is reached
;; Define storage for the vault deposits
;; Map: user-address -> (amount, unlock-height)
(define-map vaults
{ owner: principal }
{
amount: uint,
unlock-height: uint
}
)
;; Public function to deposit STX and set a lock time
(define-public (deposit (amount uint) (lock-blocks uint))
(let
(
(current-height stacks-block-height)
)
(asserts! (> amount u0) (err u1))
(asserts! (and (>= lock-blocks u1) (<= lock-blocks u52560)) (err u5))
(asserts! (is-none (map-get? vaults {owner: tx-sender})) (err u2))
(let
((unlock-at (+ current-height lock-blocks)))
(map-set vaults
{owner: tx-sender}
{
amount: amount,
unlock-height: unlock-at
}
)
(try! (stx-transfer? amount tx-sender (as-contract tx-sender)))
(ok unlock-at)
)
)
)
;; Public function to withdraw STX after lock period
(define-public (withdraw)
(let
(
(vault-data (unwrap! (map-get? vaults {owner: tx-sender}) (err u3)))
(amount (get amount vault-data))
(unlock-height (get unlock-height vault-data))
)
(asserts! (>= stacks-block-height unlock-height) (err u4))
(map-delete vaults {owner: tx-sender})
(try! (stx-transfer? amount (as-contract tx-sender) tx-sender))
(ok amount) ;; Return the amount withdrawn
)
)
;; Read-only function to get information about a user's vault
(define-read-only (get-vault-info (user principal))
(map-get? vaults {owner: user})
)
;; Read-only function to check if withdrawal is possible
(define-read-only (can-withdraw (user principal))
(match (map-get? vaults {owner: user})
vault (>= stacks-block-height (get unlock-height vault))
false
)
)
;; Read-only function to check how many blocks remain until withdrawal is possible
(define-read-only (blocks-until-unlock (user principal))
(match (map-get? vaults {owner: user})
vault (if (>= stacks-block-height (get unlock-height vault))
u0
(- (get unlock-height vault) stacks-block-height))
u0
)
)
This smart contract enables users to deposit STX tokens and lock them for a certain number of block heights. Once the time has passed, they can withdraw their tokens.
(define-map vaults
{ owner: principal }
{
amount: uint,
unlock-height: uint
}
)
vaults is a map that stores each userโs deposit and unlock time.{ owner: principal } โ userโs wallet address.{ amount, unlock-height } โ how much they deposited and when it unlocks.(define-public (deposit (amount uint) (lock-blocks uint))
(asserts! (> amount u0) (err u1)) ;; Must deposit more than 0
(asserts! (and (>= lock-blocks u1) (<= lock-blocks u52560)) (err u5)) ;; Lock duration between 1 and ~1 year
(asserts! (is-none (map-get? vaults {owner: tx-sender})) (err u2)) ;; User can only have one active vault
(let ((unlock-at (+ current-height lock-blocks)))
(map-set vaults {owner: tx-sender} { amount: amount, unlock-height: unlock-at })
(try! (stx-transfer? amount tx-sender (as-contract tx-sender)))
(ok unlock-at)
(define-public (withdraw)
(let ((vault-data (unwrap! (map-get? vaults {owner: tx-sender}) (err u3)))
(asserts! (>= stacks-block-height unlock-height) (err u4))
(map-delete vaults {owner: tx-sender})
(try! (stx-transfer? amount (as-contract tx-sender) tx-sender))
(ok amount)
These donโt modify state and are used to check vault info:
(define-read-only (get-vault-info (user principal))
(map-get? vaults {owner: user})
)
none.(define-read-only (can-withdraw (user principal))
(match (map-get? vaults {owner: user})
vault (>= stacks-block-height (get unlock-height vault))
false
)
)
true if userโs lock time has passed.(define-read-only (blocks-until-unlock (user principal))
(match (map-get? vaults {owner: user})
vault (if (>= stacks-block-height (get unlock-height vault))
u0
(- (get unlock-height vault) stacks-block-height))
u0
)
)
(deposit u100 u144)
(withdraw)
stacks-block-height < unlock-heighterr u4 (Too early)| Function | Purpose |
|---|---|
deposit |
Lock STX for a set number of blocks |
withdraw |
Retrieve STX after unlock height |
get-vault-info |
View stored amount and unlock time |
can-withdraw |
Check if user can withdraw yet |
blocks-until-unlock |
See how many blocks are left to wait |
vaults map |
Stores each userโs locked STX & unlock time |
Imagine putting money in a timed safe:
import { useState, useEffect } from 'react';
import { connect, disconnect, isConnected, getLocalStorage, request } from '@stacks/connect';
import { broadcastTransaction, Cl, fetchCallReadOnlyFunction, cvToValue } from '@stacks/transactions';
export default function App() {
const [walletAddress, setWalletAddress] = useState('');
const [amount, setAmount] = useState();
const [lockBlocks, setLockBlocks] = useState();
const [vaultInfo, setVaultInfo] = useState(null);
const [blocksUntilUnlock, setBlocksUntilUnlock] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState('');
const [success, setSuccess] = useState('');
const CONTRACT_ADDRESS = 'ST2WD8TKH9C3VKX4C355RGPPWFGYRAA9WT29SFQZY.time-vault3';
useEffect(() => {
const checkConnection = async () => {
try {
if (isConnected()) {
const data = getLocalStorage();
const stxAddress = data?.addresses?.stx?.[0]?.address;
setWalletAddress(stxAddress);
console.log('hello',typeof stxAddress)
console.log("address:", stxAddress);
if (stxAddress) {
try{
await fetchVaultInfo(stxAddress);
}catch (err) {
console.error("fetchVault failed", err)
}
}
}
} catch (err) {
console.error('Connection check failed:', err);
setError('Failed to check wallet connection');
}
};
checkConnection();
}, [walletAddress]);
const handleConnect = async () => {
try {
setLoading(true);
setError('');
await connect();
const data = getLocalStorage();
const stxAddress = data?.addresses?.stx?.[0]?.address || '';
setWalletAddress(stxAddress);
await fetchVaultInfo(stxAddress);
setSuccess('Wallet connected successfully');
setTimeout(() => setSuccess(''), 3000);
} catch (error) {
console.error('Connection failed:', error);
setError('Wallet connection failed');
} finally {
setLoading(false);
}
};
const handleDisconnect = () => {
try {
disconnect();
setWalletAddress('');
setVaultInfo(null);
setBlocksUntilUnlock(null);
setSuccess('Wallet disconnected');
setTimeout(() => setSuccess(''), 3000);
} catch (err) {
console.error('Disconnect failed:', err);
setError('Failed to disconnect wallet');
}
};
const depositSTX = async () => {
if (!amount || !lockBlocks || Number(amount) <= 0 || Number(lockBlocks) <= 0) {
setError('Please enter valid amount and lock period');
return;
}
try {
setLoading(true);
setError('');
const amountMicroSTX = (amount * 1000000);
const blocks = (lockBlocks);
console.log("Depositing:", {
amountSTX: amount,
amountMicroSTX,
lockBlocks: typeof blocks
});
const cvAmount = Cl.uint((amountMicroSTX)) // convert STX to micro-STX
const cvBlock = Cl.uint((blocks))
console.log("lala", {cvAmount, Block: cvBlock})
console.log("amount:", amount * 1000000);
const response = await request('stx_callContract', {
contract: CONTRACT_ADDRESS,
functionName: 'deposit',
functionArgs: [
cvAmount,
cvBlock
],
network: 'testnet',
postConditionMode: 'allow'
});
console.log("amount:", amount * 1000000);
console.log('Deposit success:', response);
setSuccess('Deposit transaction submitted');
setTimeout(() => setSuccess(''), 3000);
// Wait a few seconds then refresh vault info
setTimeout(() => fetchVaultInfo(walletAddress), 5000);
} catch (error) {
console.error('Deposit failed:', error);
setError('Deposit failed: ' + (error.message || 'Unknown error'));
} finally {
setLoading(false);
}
};
const withdrawSTX = async () => {
try {
setLoading(true);
setError('');
const response = await request('stx_callContract', {
contract: CONTRACT_ADDRESS,
functionName: 'withdraw',
functionArgs: [],
network: 'testnet'
});
console.log('Withdraw success:', response);
setSuccess('Withdrawal transaction submitted');
setTimeout(() => setSuccess(''), 3000);
// Wait a few seconds then refresh vault info
setTimeout(() => fetchVaultInfo(walletAddress), 5000);
} catch (error) {
console.error('Withdraw failed:', error);
setError('Withdrawal failed: ' + (error.message || 'Unknown error'));
} finally {
setLoading(false);
}
};
const fetchVaultInfo = async (address) => {
try {
setLoading(true);
setError('');
// Get vault inf0
const VaultTxOptions = {
contractName: 'time-vault3',
contractAddress: 'ST2WD8TKH9C3VKX4C355RGPPWFGYRAA9WT29SFQZY',
functionName: 'get-vault-info',
functionArgs: [Cl.standardPrincipal(address)],
senderAddress: address,
network: 'testnet'
}
const vaultTransaction = await fetchCallReadOnlyFunction(VaultTxOptions);
console.log(vaultTransaction);
const readable = cvToValue(vaultTransaction)
console.log(readable.value);
console.log(readable.value['unlock-height'].value);
// Get blocks until unlock
const BlockTxOptions = {
contractName: 'time-vault3',
contractAddress: 'ST2WD8TKH9C3VKX4C355RGPPWFGYRAA9WT29SFQZY',
functionName: 'blocks-until-unlock',
functionArgs: [Cl.standardPrincipal(address)],
senderAddress: address,
network: 'testnet'
}
const blockTransaction = await fetchCallReadOnlyFunction(BlockTxOptions);
console.log(blockTransaction);
const blockreadable = cvToValue(blockTransaction);
console.log(blockreadable);
// Check if vault exists (response will be null if no vault)
if (vaultTransaction === null) {
setVaultInfo(null);
setBlocksUntilUnlock(null);
} else {
setVaultInfo(readable);
setBlocksUntilUnlock();
}
} catch (error) {
console.error('Fetch Vault Info failed:', error);
setError('No Vault');
} finally {
setLoading(false);
}
};
const formatSTX = (microstx) => {
return (microstx / 1000000).toFixed(6);
};
return (
<div className="min-h-screen bg-gray-100 flex flex-col items-center justify-center p-4">
<div className="max-w-md w-full bg-white shadow-lg rounded-lg p-6 space-y-6">
<h1 className="text-2xl font-bold text-center text-indigo-600">STX Time Vault</h1>
{/* Status messages */}
{error && (
<div className="p-3 bg-red-100 text-red-700 rounded">
{error}
<button onClick={() => setError('')} className="float-right font-bold">
ร
</button>
</div>
)}
{success && (
<div className="p-3 bg-green-100 text-green-700 rounded">
{success}
<button onClick={() => setSuccess('')} className="float-right font-bold">
ร
</button>
</div>
)}
{loading && (
<div className="text-center py-4">
<div className="inline-block animate-spin rounded-full h-8 w-8 border-t-2 border-b-2 border-indigo-600"></div>
<p className="mt-2 text-gray-600">Processing...</p>
</div>
)}
{!walletAddress ? (
<button
onClick={handleConnect}
disabled={loading}
className="w-full bg-indigo-600 text-white py-2 rounded hover:bg-indigo-700 disabled:bg-indigo-300"
>
Connect Wallet
</button>
) : (
<>
<div className="space-y-2">
<p className="text-gray-700 text-sm break-words">Connected: {walletAddress}</p>
<button
onClick={handleDisconnect}
disabled={loading}
className="w-full bg-red-500 text-white py-2 rounded hover:bg-red-600 disabled:bg-red-300"
>
Disconnect
</button>
</div>
<div className="space-y-4">
<h2 className="text-lg font-semibold text-gray-800">Deposit STX</h2>
<input
type="number"
placeholder="Amount (STX)"
className="w-full p-2 border rounded"
value={amount}
onChange={(e) => setAmount(e.target.value)}
disabled={loading}
min="0.000001"
step="0.000001"
/>
<input
type="number"
placeholder="Lock Blocks (1 block โ 10 minutes)"
className="w-full p-2 border rounded"
value={lockBlocks}
onChange={(e) => setLockBlocks(e.target.value)}
disabled={loading}
min="1"
/>
<button
onClick={depositSTX}
disabled={loading || !amount || !lockBlocks}
className="w-full bg-green-500 text-white py-2 rounded hover:bg-green-600 disabled:bg-green-300"
>
Deposit
</button>
</div>
{vaultInfo ? (
<div className="space-y-2 p-4 bg-gray-50 rounded">
<h2 className="text-lg font-semibold text-gray-800">Vault Info</h2>
<p>Amount Locked: {formatSTX(vaultInfo.value.amount.value)} STX</p>
<p>Unlock Block Height: {vaultInfo.value['unlock-height'].value}</p>
{blocksUntilUnlock == 0 ?
<>
<p>Blocks Remaining: {blocksUntilUnlock} b</p>
<p className="text-sm text-gray-500">
Approx. {(blocksUntilUnlock * 10 / 60).toFixed(1)} hours remaining
</p>
</> : <><p>You can withdraw your stx</p></> }
</div>
) : (
<div className="p-4 bg-gray-50 rounded text-center">
<p className="text-gray-600">No active vault found for this address</p>
</div>
)}
<button
onClick={withdrawSTX}
disabled={loading || !vaultInfo}
className="w-full bg-blue-500 text-white py-2 rounded hover:bg-blue-600 disabled:bg-blue-300"
>
Withdraw
</button>
</>
)}
</div>
</div>
);
}
;; title: token
;; version:2
;; summary:This is the fungible token for the code4stx project
;; traits
(impl-trait 'ST1NXBK3K5YYMD6FD41MVNP3JS1GABZ8TRVX023PT.sip-010-trait-ft-standard.sip-010-trait)
;; Token definitions
(define-fungible-token BScoin u1000000000000)
;; constants
(define-constant err-not-token-owner (err u101))
(define-constant err-insufficient-amount (err u102))
(define-constant err-owner-only (err u103))
(define-constant err-not-whitelisted (err u104))
(define-constant err-kyc-not-found (err u105))
(define-constant err-kyc-already-approved (err u106))
(define-constant err-kyc-not-pending (err u107))
;; data variables
(define-data-var contract-owner principal tx-sender)
;; Maps
(define-map whitelist principal bool)
(define-map kyc-submissions principal {ipfs-hash: (string-utf8 100), status: (string-utf8 20)})
;; Read only functions
(define-read-only (get-name) (ok "BScoin"))
(define-read-only (get-symbol) (ok "BSC"))
(define-read-only (get-decimals) (ok u6))
(define-read-only (get-balance (who principal)) (ok (ft-get-balance BScoin who)))
(define-read-only (get-token-uri) (ok none))
(define-read-only (get-total-supply) (ok (ft-get-supply BScoin)))
(define-read-only (get-contract-owner) (ok (var-get contract-owner)))
(define-read-only (get-kyc-status (user principal)) (ok (map-get? kyc-submissions user)))
;; Public functions
;; Function to transfer the token
(define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34))))
(begin
(asserts! (is-eq tx-sender sender) err-not-token-owner)
(asserts! (default-to false (map-get? whitelist sender)) err-not-whitelisted)
(asserts! (default-to false (map-get? whitelist recipient)) err-not-whitelisted)
(asserts! (> amount u0) err-insufficient-amount)
(try! (ft-transfer? BScoin amount sender recipient))
(print { event-type: "Transfer", amount: amount, sender: sender, recipient: recipient })
(match memo to-print (print to-print) 0x)
(ok true)
)
)
;; Function to mint the tokens (only by owner)
(define-public (mint (amount uint) (recipient principal))
(begin
(asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
(asserts! (default-to false (map-get? whitelist recipient)) err-not-whitelisted)
(asserts! (> amount u0) err-insufficient-amount)
(try! (ft-mint? BScoin amount recipient))
(print { event-type: "Mint", amount: amount, recipient: recipient})
(ok true)
)
)
;; Function to burn the tokens
(define-public (burn (amount uint))
(begin
(asserts! (> amount u0) err-insufficient-amount)
(try! (ft-burn? BScoin amount tx-sender))
(print { event-type: "burn", amount: amount, recipient: tx-sender})
(ok true)
)
)
;; Transfer ownership
(define-public (transfer-ownership (new-owner principal))
(begin
(asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
(var-set contract-owner new-owner)
(ok true)
)
)
;; Function to submit KYC documents (CID from IPFS)
(define-public (submit-kyc (ipfs-hash (string-utf8 100)))
(begin
(let ((empty-kyc (tuple (ipfs-hash u"") (status u"none"))))
(asserts! (is-eq (get status (default-to empty-kyc (map-get? kyc-submissions tx-sender))) u"none") err-kyc-already-approved))
(map-set kyc-submissions tx-sender (tuple (ipfs-hash ipfs-hash) (status u"pending")))
(print (tuple (event-type u"KYCSubmitted") (user tx-sender) (ipfs-hash ipfs-hash)))
(ok true)
)
)
;; Function to approve KYC (admin only)
(define-public (approve-kyc (user principal))
(begin
(asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
(let ((kyc-data (unwrap! (map-get? kyc-submissions user) err-kyc-not-found)))
(asserts! (is-eq (get status kyc-data) u"pending") err-kyc-not-pending)
(map-set kyc-submissions user (tuple (ipfs-hash (get ipfs-hash kyc-data)) (status u"approved")))
(map-set whitelist user true)
(print {event-type: "KYCApproved", user: user, by: tx-sender})
(ok true)
)
)
)
;; Function to reject KYC (admin only)
(define-public (reject-kyc (user principal) (reason (string-utf8 1000)))
(begin
(asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
(let ((kyc-data (unwrap! (map-get? kyc-submissions user) err-kyc-not-found)))
(asserts! (is-eq (get status kyc-data) u"pending") err-kyc-not-pending)
(map-set kyc-submissions user (tuple (ipfs-hash (get ipfs-hash kyc-data)) (status u"rejected")))
(print {event-type: "KYCRejected", user: user, by: tx-sender, reason: reason})
(ok true)
)
)
)
;; Function to remove from whitelist (admin only)
(define-public (remove-from-whitelist (user principal))
(begin
(asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
(map-delete whitelist user)
(ok true)
)
)
;; ;; Function to add to whitelist (admin only)
;; (define-public (add-to-whitelist (user principal))
;; (begin
;; (asserts! (is-eq tx-sender (var-get admin)) err-not-admin)
;; (map-set whitelist user true)
;; (ok true)
;; )
;; )
;; ;; Function to add in the blacklist by the owner
;; (define-public (add-to-blacklist (user principal))
;; (begin
;; (asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
;; (map-set blacklist user true)
;; (ok true)
;; )
;; )
;; ;; Function to remove from blacklist by owner
;; (define-public (remove-from-blacklist (user principal))
;; (begin
;; (asserts! (is-eq tx-sender (var-get contract-owner)) err-owner-only)
;; (map-delete blacklist user)
;; (ok true)
;; )
;; )
This contract defines a SIP-010 compatible token (fungible token standard on Stacks), with the added layers of:
(impl-trait '...sip-010-trait)
This tells Clarity the contract follows the official fungible token standard (SIP-010), ensuring compatibility with wallets, DeFi protocols, and explorers.
(define-fungible-token BScoin u1000000000000)
Defines a new token named BScoin with a total supply of 1,000,000,000,000 units (1 trillion).
(define-constant err-not-token-owner (err u101))
These are custom error codes for better debugging and consistent responses. Errors include:
| Error Code | Meaning |
|---|---|
u101 |
Sender is not the token owner |
u102 |
Transfer amount is invalid (โค 0) |
u103 |
Only contract owner can perform |
u104 |
User is not whitelisted |
u105 |
KYC not submitted |
u106 |
KYC already submitted |
u107 |
KYC not in pending state |
(define-data-var contract-owner principal tx-sender)
(define-map whitelist principal bool)
(define-map kyc-submissions principal {
ipfs-hash: (string-utf8 100),
status: (string-utf8 20)
})
contract-owner: Controls privileged actions like minting, approving KYC, etc.whitelist: Tracks who can transfer or receive tokens.kyc-submissions: Stores IPFS hash + status (none, pending, approved, rejected).These functions return data without modifying state:
| Function | Description |
|---|---|
get-name |
Returns token name BScoin |
get-symbol |
Returns symbol BSC |
get-decimals |
Returns 6 decimals |
get-balance |
Returns token balance of a user |
get-total-supply |
Total token supply |
get-contract-owner |
Owner address |
get-token-uri |
Token URI (set to none) |
get-kyc-status |
Returns a userโs KYC submission & status |
transfer(define-public (transfer amount sender recipient memo))
ft-transfer?memo (e.g., transaction ID, reason)mint(define-public (mint amount recipient))
ft-mint?burn(define-public (burn amount))
ft-burn?transfer-ownership(define-public (transfer-ownership new-owner))
contract-ownersubmit-kyc(define-public (submit-kyc ipfs-hash))
(ipfs-hash, "pending")approve-kyc(define-public (approve-kyc user))
status = approved)reject-kyc(define-public (reject-kyc user reason))
"rejected"(define-public (remove-from-whitelist user))
๐ The add-to-whitelist function is commented out, and if restored, should include proper ownership checks.
The contract includes stubs for blacklist features, but they are commented out:
;; (define-public (add-to-blacklist user))
;; (define-public (remove-from-blacklist user))
If implemented, you can restrict transfers or minting to exclude blacklisted users โ useful for sanctions compliance.
| Feature | Included |
|---|---|
| SIP-010 Compliant | โ |
| Minting & Burning | โ |
| KYC System (IPFS) | โ |
| Whitelist Only Access | โ |
| Ownership Control | โ |
| Event Logging | โ |
| Blacklist Support | ๐ก (commented) |
| Token URI | ๐ซ (returns none) |