StacksOne

StacksOne is a modular identity, progression, mission, badge, token, leaderboard, reputation, and engagement layer built on Stacks. This repository contains:

• a React reference application;
• the published @bayybays/stacksone-sdk package;
• browser wallet and contract integrations;
• a Clarinet workspace for the contract sources included in this repository;
• tests and operational documentation.

What StacksOne does

StacksOne gives a Stacks application a reusable progression model:

Connect wallet → read profile → complete mission → submit transaction
→ wait for confirmation → earn XP → unlock badges → build reputation

Wallet approval, transaction submission, and confirmed on-chain state are separate stages. A wallet callback means a transaction was submitted. It does not mean the expected state change is already confirmed.

Requirements

• Node.js >=18.18;
• npm with lockfile support;
• a browser Stacks wallet for interactive writes;
• Clarinet tooling only when developing or deploying Clarity contracts.

Quick start

git clone https://github.com/bayyubenjamin/stacksone.git
cd stacksone
npm ci
cp .env.example .env
npm run dev

The Supabase values in .env are optional. Leave them empty to run the wallet and on-chain features without the supporting cache layer.

Run the complete repository checks:

npm test
npm run build
npm pack --dry-run

cd smart-contracts
npm ci
npm test

SDK quick example

import { StacksOneClient } from '@bayybays/stacksone-sdk';

const client = new StacksOneClient({ network: 'mainnet' });

const stats = await client.getUserStats(address);
const oneBalance = await client.getTokenBalance(address, 'one');
const taskDone = await client.isTaskDone(address, 101);

The current 2.x SDK is intentionally read-oriented. It provides normalized protocol reads, registries, helpers, and browser wallet connection. Contract writes in the reference application use openContractCall directly so transaction arguments, post conditions, and confirmation behavior remain explicit.

Read SDK Quick Start, SDK API Reference, and Write Transactions.

Repository map

Path	Purpose
src/	Reference UI for Home, Tasks, Vault, Profile, and Gaming experiences
sdk/	Public client, canonical contract registry, network resolver, and value helpers
smart-contracts/	Clarity sources included in this repository, Clarinet manifest, and Simnet tests
tests/	Public SDK behavior and package-entrypoint tests
docs/	Architecture, contract inventory, transactions, deployment, workflow, and security guidance

Contract surfaces

The runtime registry and the local Clarinet workspace serve different purposes:

• sdk/contracts.js is the canonical application and SDK registry for configured mainnet contracts;
• smart-contracts/Clarinet.toml describes only the contract sources currently included in the local Clarinet workspace;
• a contract can be configured on mainnet without its historical source being registered in this workspace;
• a local contract can be experimental and not yet configured for the application.

Configured mainnet deployer:

SP3GHKMV4GSYNA8WGBX83DACG80K1RRVQZAZMB9J3

Configured runtime contracts:

genesis-core-v10
genesis-missions-v10
genesis-badges-v10
genesis-leaderboard-v1
genesis-boost-v1
chaintap
token-poin
token-one

See Contract Inventory for the exact local-versus-mainnet status and compatibility rules.

Architecture

React reference application
        ↓
StacksOne SDK + canonical registry
        ↓
Stacks API reads + browser wallet submissions
        ↓
Configured Clarity contracts

Confirmed on-chain records are authoritative. Supabase is optional and must remain a supporting cache or indexing layer. Frontend validation improves user experience but never replaces contract authorization.

See System Architecture.

Documentation

Document	Use it for
SDK Quick Start	Installing the package and reading protocol state
SDK API Reference	Method signatures, return values, errors, and advanced injection options
Contract Inventory	Understanding runtime contracts and the local Clarinet workspace
Write Transactions	Building confirmation-safe browser contract calls
Deployment Guide	Releasing contracts, registry changes, the SDK, and the frontend
Development Workflow	Changing code in the correct order and running quality gates
System Architecture	Data ownership, module boundaries, and transaction lifecycle
Security Policy	Reporting issues, trust boundaries, and known limitations

Engineering principles

• On-chain records remain authoritative.
• Frontend checks do not replace contract authorization.
• Submitted writes remain pending until confirmed state is readable.
• Contract identifiers are imported from sdk/contracts.js rather than duplicated.
• Supabase remains optional and secondary to chain state.
• Contract logic changes require explicit versioning and migration documentation.
• SDK behavior changes require public tests and documentation updates.

Security status

StacksOne has not completed an independent third-party audit. Administrative operations still require a documented multisig process, and deployed contract logic must be replaced with a new version when behavior changes. Review Security Policy before production integration.

Roadmap

Planned improvements include TypeScript declarations, React hooks, richer confirmation feedback, dedicated activity views, contract-controlled mission rewards, multisig operations, migration playbooks, and expanded integration examples.

License

Maintained by Bayu Benjamin and licensed under the MIT License.