mobilestacks

A Hardhat-style development framework for Stacks. Write, test, and deploy Clarity smart contracts with a task-based CLI, local Simnet testing, and a pluggable runtime.

Install

npm install mobilestacks

Quick Start

Scaffold a new project:

npx mobilestacks init

This generates a config file, a sample Clarity contract, and an example task.

Configuration

All config lives in mobilestacks.config.ts:

export default {
  networks: {
    mainnet: { url: "https://api.mainnet.hiro.so", name: "mainnet" },
    testnet: { url: "https://api.testnet.hiro.so", name: "testnet" },
  },
  defaultNetwork: "testnet",
  wallet: {
    privateKey: process.env.STACKS_PRIVATE_KEY,
  },
};

Secrets can live in .env — they override config values automatically.

CLI

npx mobilestacks                    # list all tasks
npx mobilestacks deploy-contract    # deploy a contract
npx mobilestacks get-balance        # check STX balance
npx mobilestacks send-stx           # send STX
npx mobilestacks faucet-request     # get testnet tokens

Missing params are prompted interactively. Run any task with --help for options.

Built-in Tasks

Task	What it does
deploy-contract	Deploy a .clar file to mainnet/testnet
send-stx	Transfer STX to an address
get-balance	Check STX balance for any address
faucet-request	Request testnet STX from the faucet
list-accounts	List derived wallet accounts
get-tx-history	Fetch recent transactions
call-contract-function	Call a read-only contract function
get-contract-info	Fetch deployed contract metadata
verify-contract	Diff on-chain source against a local file

Writing Tasks

Drop a file in src/tasks/ — it's auto-discovered:

import { task } from "mobilestacks";
import { z } from "zod";

task("greet", "Say hello")
  .addParam("name", "Who to greet", { schema: z.string().min(1) })
  .setAction(async (args, env) => {
    return `Hello, ${args.name}! (network: ${env.config.defaultNetwork})`;
  });

Subtasks and workflows are also supported:

import { subtask, runWorkflow } from "mobilestacks";

// subtask tied to a parent
subtask("deploy:validate", "Pre-deploy check", "deploy-contract")
  .setAction(async (args, env) => { /* ... */ });

// run tasks in sequence
await runWorkflow([
  { taskName: "deploy-contract", args: { /* ... */ } },
  { taskName: "verify-contract", args: { /* ... */ } },
], env);

Extending the Runtime

Add custom properties to the runtime environment, available in every task:

import { extendEnvironment } from "mobilestacks";

extendEnvironment((env) => {
  env.formatSTX = (micro: number) => `${(micro / 1e6).toFixed(6)} STX`;
});

Testing with Simnet

Test contracts locally using the Clarinet SDK — no devnet needed:

import { describe, it, expect, beforeAll } from "vitest";
import { Simnet } from "mobilestacks";
import { Cl } from "@stacks/transactions";

describe("My Contract", () => {
  let simnet: Simnet;

  beforeAll(async () => {
    simnet = await Simnet.init();
  });

  it("calls hello-world", () => {
    const deployer = simnet.getDeployer();
    const { result } = simnet.callPublic("sample-contract", "hello-world", [], deployer);
    expect(result).toStrictEqual(Cl.ok(Cl.stringAscii("Hello, Stacks!")));
  });
});

Setup

Contract tests need a Clarinet.toml and test accounts. Run the setup script once:

npm run setup:simnet

Then run tests:

npm test

Programmatic API

Use mobilestacks as a library:

import { task, subtask, extendEnvironment, Simnet, RuntimeEnvironment } from "mobilestacks";

Project Structure

├── src/
│   ├── cli/           # CLI entry point + init scaffolding
│   ├── core/          # DSL, Simnet, RuntimeEnvironment, task registry
│   ├── tasks/         # Built-in tasks (auto-loaded)
│   ├── types/         # Zod schemas + TypeScript types
│   └── index.ts       # Public API
├── tests/             # Vitest test files
├── contracts/         # Clarity contracts
├── Clarinet.toml      # Clarinet project manifest
└── mobilestacks.config.ts

Contributing

git clone https://github.com/Wizbisy/mobilestacks.git
cd mobilestacks
npm install
npm run setup:simnet   # generate test accounts
npm test               # run all tests

See CONTRIBUTING.md for details.

Security

Private keys and seed phrases are never logged. Output is scanned for secrets and masked automatically. Keep your .env out of version control.

License

MIT