Contract Functions

Public Functions

Public functions modify blockchain state and require a signed transaction. Users must pay gas fees (STX) to execute these functions.

set-risk-profile

Save or update user’s risk tolerance level on-chain.

contracts/staxiq-user-profile.clar:70

(define-public (set-risk-profile (risk-level uint))
  (begin
    (asserts! (is-valid-risk-level risk-level) ERR-INVALID-RISK)
    ;; ...
    (ok risk-level)
  )
)

uint

required

User’s risk tolerance: u1 (Conservative), u2 (Balanced), or u3 (Aggressive)

response

Show Success

uint

Returns the risk level that was set

Show Errors

ERR-INVALID-RISK

Invalid risk level provided (must be 1, 2, or 3)

Behavior

If profile exists: Updates risk-level and updated-at, preserves created-at and strategy-count
If profile doesn’t exist: Creates new profile with created-at set to current block height
Validates risk level is 1, 2, or 3 before writing
Transaction must be signed by the user (tx-sender)

Example Usage

import { makeContractCall, uintCV, AnchorMode } from '@stacks/transactions';

const txOptions = {
  contractAddress: 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ',
  contractName: 'staxiq-user-profile',
  functionName: 'set-risk-profile',
  functionArgs: [uintCV(2)], // Set to Balanced
  network: STACKS_TESTNET,
  anchorMode: AnchorMode.Any,
};

const transaction = await makeContractCall(txOptions);
const result = await broadcastTransaction({ transaction, network });

import { saveRiskProfile } from './services/contractService';

// Save "Balanced" risk profile
const txId = await saveRiskProfile('Balanced');
console.log('Transaction ID:', txId);

(contract-call? .staxiq-user-profile set-risk-profile u2)
;; Returns: (ok u2)

save-strategy

Anchor an AI-generated strategy recommendation to the blockchain.

contracts/staxiq-user-profile.clar:99

(define-public (save-strategy
  (strategy-hash (string-ascii 64))
  (protocol (string-ascii 32))
)
  (let (
    (profile (map-get? user-profiles tx-sender))
    (current-count (default-to u0 (map-get? user-strategy-count tx-sender)))
    (new-count (+ current-count u1))
  )
    (asserts! (is-some profile) ERR-NOT-FOUND)
    ;; ...
    (ok new-count)
  )
)

string-ascii

required

SHA-256 hash (hex string) of the complete strategy details. Should be 64 characters.

string-ascii

required

Name of the target DeFi protocol (e.g., “ALEX”, “Velar”, “StackSwap”). Max 32 characters.

response

Show Success

uint

Returns the new strategy ID (incrementing counter starting at 1)

Show Errors

ERR-NOT-FOUND

User must have a risk profile before saving strategies. Call set-risk-profile first.

Behavior

Requires user to have an existing risk profile (call set-risk-profile first)
Increments strategy counter and assigns new strategy ID
Stores strategy with user’s current risk level
Updates profile’s strategy-count and updated-at fields
Each strategy is permanently stored and cannot be modified

Example Usage

import { makeContractCall, stringAsciiCV, AnchorMode } from '@stacks/transactions';
import crypto from 'crypto';

// Hash the strategy
const strategy = { protocol: 'ALEX', actions: [...], apy: 12.5 };
const hash = crypto
  .createHash('sha256')
  .update(JSON.stringify(strategy))
  .digest('hex');

const txOptions = {
  contractAddress: 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ',
  contractName: 'staxiq-user-profile',
  functionName: 'save-strategy',
  functionArgs: [
    stringAsciiCV(hash.slice(0, 64)),
    stringAsciiCV('ALEX')
  ],
  network: STACKS_TESTNET,
  anchorMode: AnchorMode.Any,
};

const transaction = await makeContractCall(txOptions);
const result = await broadcastTransaction({ transaction, network });

import { anchorStrategy } from './services/contractService';
import crypto from 'crypto';

const strategy = generateStrategy(); // Your AI strategy
const hash = crypto
  .createHash('sha256')
  .update(JSON.stringify(strategy))
  .digest('hex');

const txId = await anchorStrategy(hash, 'ALEX');
console.log('Strategy anchored with TX:', txId);

(contract-call? .staxiq-user-profile save-strategy
  "a1b2c3d4e5f6..." ;; 64-char hash
  "ALEX"            ;; protocol
)
;; Returns: (ok u1) - first strategy for this user

Read-Only Functions

Read-only functions query blockchain data without modifying state. They are free to call (no gas fees) and return data instantly.

get-user-profile

Retrieve complete profile information for a user.

contracts/staxiq-user-profile.clar:142

(define-read-only (get-user-profile (user principal))
  (match (map-get? user-profiles user)
    profile (ok profile)
    ERR-NOT-FOUND
  )
)

principal

required

Stacks wallet address (e.g., ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ)

response

Show Success

object

Profile data object

Show Profile Fields

uint

1 = Conservative, 2 = Balanced, 3 = Aggressive

uint

Block height when profile was created

uint

Block height of last update

uint

Total strategies saved by this user

Show Errors

ERR-NOT-FOUND

User has not created a profile yet

Example Usage

import { fetchCallReadOnlyFunction, cvToJSON } from '@stacks/blockchain-api-client';
import { principalCV } from '@stacks/transactions';

const result = await fetchCallReadOnlyFunction({
  contractAddress: 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ',
  contractName: 'staxiq-user-profile',
  functionName: 'get-user-profile',
  functionArgs: [principalCV('ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ')],
  senderAddress: 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ',
  network: STACKS_TESTNET
});

const profile = cvToJSON(result);
console.log(profile);
// { risk_level: 2, created_at: 150000, updated_at: 150500, strategy_count: 3 }

import { getUserProfile } from './services/contractService';

const profile = await getUserProfile(userAddress);
if (profile) {
  console.log('Risk level:', profile.risk_level);
  console.log('Strategies:', profile.strategy_count);
}

(contract-call? .staxiq-user-profile get-user-profile 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ)
;; Returns: (ok { risk-level: u2, created-at: u150000, updated-at: u150500, strategy-count: u3 })

get-strategy

Retrieve a specific strategy from user’s history.

contracts/staxiq-user-profile.clar:150

(define-read-only (get-strategy
  (user principal)
  (strategy-id uint)
)
  (match (map-get? strategy-history { user: user, strategy-id: strategy-id })
    strategy (ok strategy)
    ERR-NOT-FOUND
  )
)

principal

required

Stacks wallet address of the user

uint

required

Strategy ID number (starting from 1)

response

Show Success

object

Strategy details object

Show Strategy Fields

uint

User’s risk level when strategy was generated

string-ascii

64-character SHA-256 hash of strategy

string-ascii

DeFi protocol name (max 32 chars)

uint

Block height when strategy was saved

Show Errors

ERR-NOT-FOUND

Strategy with this ID does not exist for this user

Example Usage

import { fetchCallReadOnlyFunction, cvToJSON } from '@stacks/blockchain-api-client';
import { principalCV, uintCV } from '@stacks/transactions';

const result = await fetchCallReadOnlyFunction({
  contractAddress: 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ',
  contractName: 'staxiq-user-profile',
  functionName: 'get-strategy',
  functionArgs: [
    principalCV(userAddress),
    uintCV(1) // Get first strategy
  ],
  senderAddress: userAddress,
  network: STACKS_TESTNET
});

const strategy = cvToJSON(result);
console.log(strategy);
// { risk_level: 2, strategy_hash: "a1b2c3...", protocol: "ALEX", timestamp: 150000 }

(contract-call? .staxiq-user-profile get-strategy
  'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ
  u1
)
;; Returns: (ok { risk-level: u2, strategy-hash: "a1b2c3...", protocol: "ALEX", timestamp: u150000 })

get-strategy-count

Get total number of strategies saved by a user.

contracts/staxiq-user-profile.clar:161

(define-read-only (get-strategy-count (user principal))
  (ok (default-to u0 (map-get? user-strategy-count user)))
)

principal

required

Stacks wallet address

response

uint

Total number of strategies (returns u0 if user has no strategies)

Example Usage

import { getStrategyCount } from './services/contractService';

const count = await getStrategyCount(userAddress);
console.log(`User has ${count} strategies`);

(contract-call? .staxiq-user-profile get-strategy-count 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ)
;; Returns: (ok u3)

has-profile

Check if a user has created a risk profile.

contracts/staxiq-user-profile.clar:166

(define-read-only (has-profile (user principal))
  (is-some (map-get? user-profiles user))
)

principal

required

Stacks wallet address

bool

true if user has a profile, false otherwise

Example Usage

import { checkHasProfile } from './services/contractService';

const hasProfile = await checkHasProfile(userAddress);
if (!hasProfile) {
  console.log('Please set your risk profile first');
}

(contract-call? .staxiq-user-profile has-profile 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ)
;; Returns: true

get-risk-label

Get user’s risk level as a human-readable string.

contracts/staxiq-user-profile.clar:171

(define-read-only (get-risk-label (user principal))
  (match (map-get? user-profiles user)
    profile (ok
      (if (is-eq (get risk-level profile) RISK-CONSERVATIVE)
        "Conservative"
        (if (is-eq (get risk-level profile) RISK-BALANCED)
          "Balanced"
          "Aggressive"
        )
      )
    )
    ERR-NOT-FOUND
  )
)

principal

required

Stacks wallet address

response

Show Success

string

One of: "Conservative", "Balanced", or "Aggressive"

Show Errors

ERR-NOT-FOUND

User has no profile

Example Usage

import { fetchCallReadOnlyFunction, cvToJSON } from '@stacks/blockchain-api-client';
import { principalCV } from '@stacks/transactions';

const result = await fetchCallReadOnlyFunction({
  contractAddress: 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ',
  contractName: 'staxiq-user-profile',
  functionName: 'get-risk-label',
  functionArgs: [principalCV(userAddress)],
  senderAddress: userAddress,
  network: STACKS_TESTNET
});

const label = cvToJSON(result);
console.log('Risk profile:', label); // "Balanced"

(contract-call? .staxiq-user-profile get-risk-label 'ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ)
;; Returns: (ok "Balanced")

Function Summary

Public Functions (Require Transaction)

Function	Parameters	Returns	Description
`set-risk-profile`	`risk-level: uint`	`(ok uint)`	Set/update user risk tolerance (1, 2, or 3)
`save-strategy`	`strategy-hash: string-ascii(64)` `protocol: string-ascii(32)`	`(ok uint)`	Anchor AI strategy to blockchain, returns strategy ID

Read-Only Functions (Free)

Function	Parameters	Returns	Description
`get-user-profile`	`user: principal`	`(ok profile)`	Get complete user profile
`get-strategy`	`user: principal` `strategy-id: uint`	`(ok strategy)`	Get specific strategy details
`get-strategy-count`	`user: principal`	`(ok uint)`	Get total strategy count
`has-profile`	`user: principal`	`bool`	Check if user has profile
`get-risk-label`	`user: principal`	`(ok string)`	Get risk level as readable string

Overview

User Profile Contract

Development

Contract Functions

Public Functions

set-risk-profile

Behavior

Example Usage

save-strategy

Behavior

Example Usage

Read-Only Functions

get-user-profile

Example Usage

get-strategy

Example Usage

get-strategy-count

Example Usage

has-profile

Example Usage

get-risk-label

Example Usage

Function Summary

Public Functions (Require Transaction)

Read-Only Functions (Free)

Next Steps

Integration Guide

Testing

​Public Functions

​set-risk-profile

​Behavior

​Example Usage

​save-strategy

​Behavior

​Example Usage

​Read-Only Functions

​get-user-profile

​Example Usage

​get-strategy

​Example Usage

​get-strategy-count

​Example Usage

​has-profile

​Example Usage

​get-risk-label

​Example Usage

​Function Summary

​Public Functions (Require Transaction)

​Read-Only Functions (Free)

​Next Steps

Integration Guide

Testing

Public Functions

set-risk-profile

Behavior

Example Usage

save-strategy

Behavior

Example Usage

Read-Only Functions

get-user-profile

Example Usage

get-strategy

Example Usage

get-strategy-count

Example Usage

has-profile

Example Usage

get-risk-label

Example Usage

Function Summary

Public Functions (Require Transaction)

Read-Only Functions (Free)

Next Steps