clarity-developer

name	clarity-developer
description	Creates Clarity smart contracts for Stacks blockchain. Use when writing Clarity contract code, implementing SIP009 NFTs, SIP010 fungible tokens, defining traits, or working with Clarinet for testing and deployment. Don't use for Solidity, Rust, or general blockchain development outside Stacks.

Clarity Smart Contract Development

Procedures

Step 1: Project Setup

1. Verify that Clarinet is installed by running clarinet --version. If not installed, direct the user to install from https://github.com/hirosystems/clarinet.
2. If starting a new project, run clarinet new <project-name> to initialize the project structure.
3. Navigate to the contracts directory to create or edit .clar files.
4. Read references/clarinet.md for detailed Clarinet commands and usage.

Step 2: Syntax & Structure

1. Write Clarity code using LISP-like S-expression syntax with parentheses.
2. Use the template in assets/contract-template.clar as a starting point for basic contracts.
3. Ensure all expressions follow the pattern: (function-name arg1 arg2 ...).
4. Use comments (;;) to document code, but remember: code is visible on-chain.

Step 3: Type System

1. Read references/types.md to understand primitive types (int, uint, bool, principal), sequence types (list, tuple, buffer, string), and composite types (response, optional, trait).
2. Clarity enforces strict type safety - do not mix types in expressions.
3. Use type signatures when defining variables and functions.

Step 4: Data Storage

1. Define constants using (define-constant NAME value).
2. Define variables using (define-data-var NAME TYPE initial-value).
3. Define maps using (define-map NAME KEY_TYPE VALUE_TYPE).
4. Reference references/keywords.md for full keyword syntax.

Step 5: Functions

1. Define public functions with (define-public (name (arg type)) ...) - must return a response type.
2. Define private functions with (define-private (name (arg type)) ...).
3. Define read-only functions with (define-read-only (name (arg type)) ...).
4. State changes (variable updates, token transfers) only persist if the public function returns ok. Returning err rolls back all changes.

Step 6: Control Flow & Error Handling

1. Use (asserts! condition (err code)) to validate conditions.
2. Use (try! expression) to handle response types.
3. Use unwrap functions: (unwrap! value default), (unwrap-panic value), (unwrap-err! ...).
4. Use (if condition true-expr false-expr) for conditional logic.
5. Read references/best-practices.md for coding style tips.

Step 7: Traits (Interfaces)

1. Read references/keywords.md to understand trait syntax.
2. Define traits with (define-trait NAME ((function-name (arg-types) (return-type)))).
3. Implement traits with (impltrait CONTRACT.TRAIT).
4. Use traits for inter-contract calls and dynamic dispatch.

Step 8: Token Standards

1. For NFTs, read references/sip009-nft.md and implement the SIP009 interface.
2. For fungible tokens, read references/sip010-ft.md and implement the SIP010 interface.
3. Ensure compliance with Stacks Improvement Proposals for interoperability.

Step 9: Practice Projects

1. Read references/practice-projects.md for detailed implementations of:
   • Time-locked wallet (block-height based unlocking)
   • Smart claimant (inter-contract calls)
   • Multi-signature vault (voting mechanism with fold)

Step 10: Building a Marketplace

1. Read references/marketplace.md for NFT marketplace implementation.
2. Implement listing creation, cancellation, and fulfillment.
3. Handle NFT escrow and payment processing.

Step 11: Runtime Cost Analysis

1. Read references/cost-analysis.md to understand execution costs.
2. Run clarinet check for cost analysis.
3. Run npm run test:report for detailed cost reports.
4. Optimize by reducing contract calls, inlining variables, and avoiding unnecessary complexity.

Step 12: Best Practices

1. Read references/best-practices.md for:
   • Coding style guidelines
   • What to store on-chain (use hashes for large data)
   • Contract upgradability patterns (modular design)
2. Avoid hardcoding principals - use trait references.
3. Separate storage and logic into different contracts.

Step 13: Working with sBTC

1. Read references/sbtc.md for sBTC integration.
2. sBTC uses SIP010 standard with 8 decimals.
3. Mainnet contract: SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token

Step 14: Testing & Validation

1. Run clarinet check to analyze contracts for type errors and runtime costs.
2. Run clarinet test to execute unit tests.
3. Use clarinet console for interactive debugging.
4. Use ::get_assets_maps to check balances.
5. Use ::advance_chain_tip to simulate block progression.

Error Handling

• If Clarinet is not found, instruct the user to install it from https://github.com/hirosystems/clarinet.
• If clarinet check fails with type errors, read references/types.md to verify type signatures.
• If public function does not return a response type, add (ok value) or (err value) wrapper.
• If contract call returns err unexpectedly, check that all state modifications are inside functions that return ok.
• For trait-related errors, verify the trait is defined and the implementation matches all function signatures.
• If runtime costs are too high, read references/cost-analysis.md for optimization techniques.
• For upgradability issues, read references/best-practices.md section on contract upgradability.

Resources

• Main Documentation: https://book.clarity-lang.org/
• Clarinet Repo: https://github.com/hirosystems/clarinet
• Stacks Docs: https://docs.stacks.co/
• Full link collection in references/links.md