Instructions Component

The Instructions component (dapp/app/mint/components/Instructions/Instructions.tsx) is a UI-only helper that explains how Colored Key NFTs behave and exposes the active smart contract address in a safe, copy-pastable way. It exists to make non-standard NFT rules explicit and to give users (and developers) a single place to grab the contract address for block explorers and integrations.

Screenshot of the Instructions component.

Why this component exists

Most ERC-721 collections let wallets hold many tokens at once, and ownership rarely forces you to burn just to participate again. Colored Keys work differently:

• Each wallet can hold only one key at a time.
• Each key can be used once to unlock the gate and send a message.
• After use, the key must be burned before the wallet can mint (or receive) another key.

Because that behavior is non-standard for NFTs, the mint page includes a dedicated Instructions panel instead of burying the rules in tooltips or external docs. This keeps the UX honest:

• Users see clear, up-front rules before minting or burning.
• The rules are kept in sync with the dApp in one place.
• The behavior is discoverable on-chain (via the contract) and in the UI (via the copyable address + written rules).

Mint & burn rules surfaced to users

The component renders a “Mint & Burn FAQ” with structured sections that match the actual behavior enforced by the contract and token gate:

• One key per wallet – If you already hold a key, additional mints or transfers will fail.
• Unused versus used – A newly minted key starts as “unused”. It can unlock the gate and send exactly one message.
• Single-use messaging – Each key lets you send one message through the token gate. After that, it’s marked “used” in the usage layer.
• Burn to reset – Used keys can’t unlock the gate again. To participate again, holders must burn the used key and mint or receive a new one.

The Instructions component communicates these rules in plain language so users understand why the mint UI sometimes shows “burn” instead of “mint,” and why they can’t stockpile multiple keys in the same wallet.

Dynamic smart contract address display

A key responsibility of this component is to surface the active Colored Key NFT contract address in a way that is:

• Environment-aware – It reflects the same multichain configuration as the rest of the dApp.
• Copy-pastable – Users can copy the exact address string to use in explorers or external tools.
• Layout-safe – The displayed text can be truncated on small screens without changing the value that gets copied.

Under the hood, the component imports the address from the shared contract configuration:

import { KEY_TOKEN_ADDRESS } from '@config/contracts'
 
const contractAddress = KEY_TOKEN_ADDRESS

KEY_TOKEN_ADDRESS is resolved at runtime based on the validated active chain (see Contract Configuration):

• RitoNet / local – Uses ContractAddresses/local_blockchain.json
• Sepolia – Uses ContractAddresses/sepolia.json
• Ethereum mainnet – Uses ContractAddresses/mainnet.json

Because the component never hardcodes an address, there is only one place to update when deployments change: the JSON files managed by the deployment pipeline and the contracts.ts configuration. The “Copy smart contract address” button always reflects the current deployment.

When the button is clicked, the component writes the full KEY_TOKEN_ADDRESS to the clipboard (or falls back to a <textarea>-based copy in non-secure contexts) and briefly shows a “Copied!” confirmation.

Truncation & mobile behavior

Long hexadecimal addresses don’t fit nicely in small buttons, especially on mobile. To handle this, the component:

1. Measures the available width inside the .addressWrapper element.
2. Computes a truncated version of the address, e.g. 0x1234…abcd, with the number of dots adjusted until the text fits.
3. Reacts to window resizes and wrapper resizes (via ResizeObserver) to recalculate as the layout changes.

Only the displayed string is truncated. The value that gets copied to the clipboard is always the full KEY_TOKEN_ADDRESS, so:

• Mobile users see a clean, readable address snippet.
• Developers and power users still get the exact address for Etherscan, Sepolia explorers, or direct API usage.

This behavior is covered by tests in Instructions.test.tsx, which seed different environments (RitoNet, Sepolia, Ethereum) and assert that clicking “Copy smart contract address” writes the correct underlying address to the clipboard.

How it fits into the smart contract UI

The Instructions component is designed to sit alongside mint/burn controls (e.g., ButtonSection) on the mint page:

• ButtonSection handles actions (minting and burning via useMintBurn).
• NFTScreen and the NFT store render state (ownership, colors, usage).
• Instructions explains rules and exposes the contract address.

Together, they give users:

• A clear understanding of what they can do (mint, burn, message).
• A clear understanding of the constraints (one key per wallet, one use per key).
• A trustworthy way to inspect and verify the underlying smart contract.

This keeps the UI aligned with the smart contract’s non-standard behavior and makes the mint screen self-documenting for both end users and developers.