Contract Architecture

Understanding Staxiq smart contract structure and design decisions

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

Code	Constant	Description
u404	ERR-NOT-FOUND	User profile or strategy does not exist
u400	ERR-INVALID-RISK	Invalid risk level provided (must be 1, 2, or 3)
u401	ERR-UNAUTHORIZED	Unauthorized access attempt

Risk Levels

Value	Constant	Description
u1	RISK-CONSERVATIVE	Low-risk, stable strategies
u2	RISK-BALANCED	Moderate risk/reward balance
u3	RISK-AGGRESSIVE	High-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

Show Profile Structure

risk-level · uint · required

Risk preference: 1 (Conservative), 2 (Balanced), or 3 (Aggressive)

created-at · uint · required

Block height when profile was first created

updated-at · uint · required

Block height of last profile update

strategy-count · uint · required

Total number of strategies saved for this user

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

Show Strategy Structure

risk-level · uint · required

Risk level at time of strategy generation

strategy-hash · string-ascii · required

Cryptographic hash of the strategy details

protocol · string · required

DeFi protocol name (e.g., “ALEX”, “Velar”, “StackSwap”)

timestamp · uint · required

Block height when strategy was saved

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