Skip to main content

​
Overview

The Staxiq smart contract architecture is built on Clarity, a decidable smart contract language designed for security and predictability on the Stacks blockchain.

​
Contract Structure

The staxiq-user-profile contract is organized into distinct sections:
contracts/staxiq-user-profile.clar
;; Staxiq User Profile Contract
;; Stores user risk profiles and AI strategy history on-chain
;; Built on Stacks Bitcoin L2

;; CONSTANTS - Error codes and risk levels
;; DATA STORAGE - Maps for profiles and strategies
;; PRIVATE FUNCTIONS - Internal validation logic
;; PUBLIC FUNCTIONS - User-facing write operations
;; READ-ONLY FUNCTIONS - Gas-free data queries

​
Constants

The contract defines constants for error handling and risk level validation:
contracts/staxiq-user-profile.clar
(define-constant CONTRACT-OWNER tx-sender)
(define-constant ERR-NOT-FOUND (err u404))
(define-constant ERR-INVALID-RISK (err u400))
(define-constant ERR-UNAUTHORIZED (err u401))

;; Valid risk profiles
(define-constant RISK-CONSERVATIVE u1)
(define-constant RISK-BALANCED u2)
(define-constant RISK-AGGRESSIVE u3)

​
Error Codes

CodeConstantDescription
u404ERR-NOT-FOUNDUser profile or strategy does not exist
u400ERR-INVALID-RISKInvalid risk level provided (must be 1, 2, or 3)
u401ERR-UNAUTHORIZEDUnauthorized access attempt

​
Risk Levels

ValueConstantDescription
u1RISK-CONSERVATIVELow-risk, stable strategies
u2RISK-BALANCEDModerate risk/reward balance
u3RISK-AGGRESSIVEHigh-risk, high-reward strategies

​
Data Maps

The contract uses three primary data maps for storage:

​
1. User Profiles Map

Stores core user profile information:
contracts/staxiq-user-profile.clar
(define-map user-profiles
  principal
  {
    risk-level: uint,
    created-at: uint,
    updated-at: uint,
    strategy-count: uint
  }
)
​
user-profiles
map
Maps wallet address (principal) to user profile data

​
2. Strategy History Map

Stores AI-generated strategy recommendations:
contracts/staxiq-user-profile.clar
(define-map strategy-history
  { user: principal, strategy-id: uint }
  {
    risk-level: uint,
    strategy-hash: (string-ascii 64),
    protocol: (string-ascii 32),
    timestamp: uint
  }
)
​
strategy-history
map
Maps (user address, strategy ID) tuple to strategy details

​
3. User Strategy Count Map

Tracks the total number of strategies per user:
contracts/staxiq-user-profile.clar
(define-map user-strategy-count
  principal
  uint
)
This map provides O(1) lookup for strategy counts without iterating through all strategies.

​
Design Decisions

​
Clarity Language Benefits

Decidability

Clarity is decidable, meaning you can know precisely what a program will do before execution

No Reentrancy

Built-in protection against reentrancy attacks that plague Solidity contracts

Post-Conditions

Users can specify conditions that must be met for a transaction to succeed

Bitcoin Finality

Stacks settles to Bitcoin, inheriting Bitcoin’s security model

​
Architecture Principles

​
1. User Sovereignty

All data is keyed by wallet address (principal). Users have complete control over their profiles without admin intervention.
contracts/staxiq-user-profile.clar
;; No admin functions - users own their data
(define-public (set-risk-profile (risk-level uint))
  (begin
    ;; tx-sender is the authenticated user
    (map-set user-profiles tx-sender {
      risk-level: risk-level,
      ;; ...
    })
  )
)

​
2. Immutable History

Once a strategy is saved on-chain, it cannot be modified or deleted. This creates an audit trail.

​
3. Gas Optimization

Read-only functions are free to call, encouraging data transparency without cost barriers.

​
4. Validation First

All inputs are validated before state changes occur:
contracts/staxiq-user-profile.clar
(define-private (is-valid-risk-level (level uint))
  (or
    (is-eq level RISK-CONSERVATIVE)
    (is-eq level RISK-BALANCED)
    (is-eq level RISK-AGGRESSIVE)
  )
)

​
Data Flow

​
Setting Risk Profile

​
Saving Strategy

​
Block Heights as Timestamps

Clarity uses block heights instead of Unix timestamps: 
;; Current block height
burn-block-height

;; Example: profile created at block 150,000
{ created-at: u150000, updated-at: u150000 }
Stacks blocks are produced approximately every 10 minutes (tied to Bitcoin blocks). To convert to approximate time:Time = (block_height_diff × 10 minutes)

​
Security Considerations

​
Authentication

All public functions authenticate using tx-sender, which is automatically set to the transaction signer: 
;; tx-sender is cryptographically verified
(map-set user-profiles tx-sender { ... })

​
Input Validation

All inputs are validated before state changes:
  • Risk levels must be 1, 2, or 3
  • String lengths are constrained (64 chars for hash, 32 for protocol)
  • Profile existence is checked before saving strategies

​
No Privileged Functions

The contract has no admin functions that could modify or delete user data after deployment.

​
Upgradeability

Clarity contracts are immutable after deployment. There is no upgrade mechanism. This is a security feature that ensures users know exactly what code they’re interacting with.Any contract changes require deploying a new contract and migrating users.

​
Next Steps

User Profile Functions

Explore all available contract functions

Integration Guide

Learn how to call contracts from your app

Build docs developers (and LLMs) love

Get started for freeTalk to us