Introduction

The cryptocurrency space has evolved dramatically since Bitcoin's inception, but one core principle remains paramount; true decentralization. As a developer and DeFi purist, I believe in creating systems that don't rely on external dependencies or centralized components. This tutorial shares my journey creating sBurn, a 100% on-chain deflationary token on the Stacks blockchain, with particular focus on implementing robust on-chain metadata, a critical yet often overlooked component of truly decentralized token design.

Note: The contract is named "sBurn2" for testnet deployment purposes. It will be deployed as "sBurn" on mainnet. The complete contract code is available here for reference.

What I am building?

sBurn is part of a larger algorithmic ecosystem I'm developing with internally priced mechanics. This token implements automatic fee collection and burn mechanics completely on-chain, creating natural deflationary pressure that benefits long-term holders.

The token follows a simple yet powerful tokenomics model:

Each transfer incurs a 0.25% fee
Half of this fee (0.125%) is permanently burned
The other half goes to fee recipients
This creates continuous supply reduction

Importance of on-chain implementation

On-chain implementation means that every aspect of the contract's functionality, including:

Token transfers
Fee calculations
Metadata

exists fully on the blockchain without external dependencies.

Differences between on-chain and off-chain smart contracts

Many "smart contracts" in the crypto ecosystem are actually hybrid systems, with critical functionality relying on off-chain components:

Off-chain contracts:

Depend on external servers or oracles
Rely on centralized metadata servers
Often require admin interventions
Can have hidden backdoors
May have upgradeable components with centralized control

On-chain contracts (like sBurn):

Execute 100% on the blockchain
Store all data and metadata on-chain
Have fully transparent fee mechanisms
Can't be altered by developers after deployment
Have predictable, immutable behavior

Reasons for Developing a 100% On-Chain Clarity Smart Contract

Transparency and trust

The sBurn contract demonstrates complete transparency. Anyone can verify:

The exact fee percentage (0.25%)
The exact burn rate (0.125%)
How fees are distributed
Current supply and burn statistics

All functionality is visible in the contract's code with no hidden mechanisms.

Security benefits

By implementing everything on-chain:

No oracle or external API vulnerabilities
No centralized metadata servers that could go offline
No admin keys that could be compromised
No backdoors for fee changes or unexpected behaviors

Decentralization and immutability

Once deployed, sBurn will operate autonomously:

No ability for developers to change fee structures
No upgradeable components that could alter mechanics
Permanent burn address ensures tokens are truly removed from circulation
All rules are enforced by blockchain consensus

Simplification of contract execution

On-chain design simplifies interactions:

No need to check external resources
Predictable gas costs for all operations
Self-contained metadata
Consistent execution regardless of external conditions

How I implemented this into code

Let's break down the key components of the sBurn contract:

1. SIP-010 Compliance

The contract fully implements the SIP-010 fungible token standard by defining all required functions with proper signatures and behaviors, ensuring seamless compatibility with Stacks wallets, DEXes, and other ecosystem applications. Rather than importing an external trait definition, I've included the trait implementation directly in the contract for complete self-containment.

(impl-trait .trait-sip010.sip-010-trait)
(define-fungible-token sBurn2-coin)

2. On-Chain Metadata

One of the most innovative aspects is the fully on-chain metadata system:

(define-read-only (get-metadata)
    (ok {
        name: TOKEN_NAME,
        symbol: TOKEN_SYMBOL,
        decimals: TOKEN_DECIMALS,
        description: "sBurn2 is a 100% on-chain deflationary token...",
        properties: {
            burn-rate: "0.125%",  
            fee-rate: "0.25%",
            min-transfer: "1000000"
        },
        stats: {
            total-burned: (unwrap-panic (get-total-burned)),
            effective-supply: (unwrap-panic (get-effective-supply))
        }
    }))

On-Chain Metadata Explained

The get-metadata function is particularly notable as it showcases how a contract can maintain dynamic, real-time metadata without external dependencies.

How on-chain metadata works:

Dynamic Statistics: The metadata function calls other read-only functions to get current values:

total-burned: (unwrap-panic (get-total-burned)),
effective-supply: (unwrap-panic (get-effective-supply))

Self-Describing Properties: The metadata includes information about the contract's own mechanics:

properties: {
    burn-rate: "0.125%",  
    fee-rate: "0.25%",
    min-transfer: "1000000"
}

Complete Description: The metadata contains a comprehensive description of what the token does, helping wallets and block explorers display accurate information.

Empty Token URI and Its Significance

Looking at the SIP-010 implementation, you'll notice this function:

(define-read-only (get-token-uri)
    (ok (some u"")))

This function returns an empty string as the token URI. Traditionally, token URIs point to off-chain metadata (often hosted on IPFS or centralized servers), but for a truly on-chain implementation:

Why use an empty URI: By returning (some u"") rather than none, we're signaling that metadata exists but is not externally hosted.
Compliance with no dependencies: This approach maintains SIP-010 standard compliance while eliminating external dependencies.
Directing to on-chain data: Applications and wallets supporting this pattern should look for the get-metadata function when the URI is empty, rather than trying to fetch from an external source.

Conclusion

Building 100% on-chain contracts like sBurn represents DeFi in its purest form - truly decentralized, transparent, and trustless. While it requires more careful planning and often more gas for deployment, the security and reliability benefits are substantial.

The sBurn contract demonstrates that Clarity on Stacks provides powerful tools for creating self-contained, verifiable systems that don't need to rely on external components.

In my next tutorial, I'll dive into how the internally priced mechanism works within the sBurn contract, exploring the dynamic mint and burn functions that allow for algorithmic pricing and sustainable tokenomics. We'll examine how these mechanisms create market equilibrium without external price oracles while maintaining the 100% on-chain philosophy that's central to true DeFi.

How and Why I Created a 100% On-Chain Clarity Smart Contract