mobilestacks 0.1.0

package/src/core/simnet.ts

@@ -0,0 +1,56 @@
+import { initSimnet } from '@hirosystems/clarinet-sdk';
+import { ClarityValue } from '@stacks/transactions';
+
+
+
+// Import the SDK's Simnet type under an alias
+type SimnetInstance = Awaited<ReturnType<typeof initSimnet>>;
+
+export class Simnet {
+  private static _instance: Simnet;
+  public simnet!: SimnetInstance;
+  public accounts!: Map<string, string>;
+
+  private constructor() {}
+
+  public static async init(): Promise<Simnet> {
+    if (!Simnet._instance) {
+      Simnet._instance = new Simnet();
+      // Initialize SDK - auto-detects Clarinet.toml from CWD
+      try {
+        console.log('Initializing Simnet...');
+        Simnet._instance.simnet = await initSimnet();
+        // Get accounts
+        Simnet._instance.accounts = Simnet._instance.simnet.getAccounts();
+      } catch (error) {
+        console.error('Failed to initialize Simnet:', error);
+        throw error;
+      }
+    }
+    return Simnet._instance;
+  }
+
+  public getDeployer(): string {
+    const deployer = this.accounts.get('deployer');
+    if (!deployer) throw new Error('Deployer account not found');
+    return deployer;
+  }
+
+  public getAccount(name: string): string {
+    const acc = this.accounts.get(name);
+    if (!acc) throw new Error(`Account ${name} not found`);
+    return acc;
+  }
+
+  public callPublic(contract: string, func: string, args: ClarityValue[], sender: string) {
+    return this.simnet.callPublicFn(contract, func, args, sender);
+  }
+
+  public callReadOnly(contract: string, func: string, args: ClarityValue[], sender: string) {
+    return this.simnet.callReadOnlyFn(contract, func, args, sender);
+  }
+
+  public async mineBlock(txs: Parameters<SimnetInstance['mineBlock']>[0]) {
+    return this.simnet.mineBlock(txs);
+  }
+}

package/src/core/tasks-definitions.ts

@@ -0,0 +1,47 @@
+import { ZodSchema } from 'zod';
+import { RuntimeEnvironment } from './runtime-environment';
+
+export type TaskParamType = 'string' | 'number' | 'boolean';
+export interface TaskParam {
+  name: string;
+  description: string;
+  type?: TaskParamType;
+  required?: boolean;
+  defaultValue?: unknown;
+  schema?: ZodSchema;
+}
+
+export interface TaskDefinition {
+  name: string;
+  description: string;
+  params: TaskParam[];
+  action: (args: Record<string, unknown>, env: RuntimeEnvironment) => Promise<unknown>;
+}
+
+class TaskDefinitions {
+  private static _instance: TaskDefinitions;
+  private _tasks: TaskDefinition[] = [];
+
+  private constructor() {}
+
+  public static getInstance(): TaskDefinitions {
+    if (!TaskDefinitions._instance) {
+      TaskDefinitions._instance = new TaskDefinitions();
+    }
+    return TaskDefinitions._instance;
+  }
+
+  public addTask(task: TaskDefinition) {
+    this._tasks.push(task);
+  }
+
+  public getTask(name: string): TaskDefinition | undefined {
+    return this._tasks.find((t) => t.name === name);
+  }
+
+  public getAllTasks(): TaskDefinition[] {
+    return this._tasks;
+  }
+}
+
+export { TaskDefinitions };

package/src/index.ts

@@ -0,0 +1,4 @@
+export { task, subtask, extendEnvironment } from './core/dsl';
+export { Simnet } from './core/simnet';
+export { RuntimeEnvironment } from './core/runtime-environment';
+export * from './core/tasks-definitions';

package/src/tasks/call-contract-function.ts

@@ -0,0 +1,31 @@
+import { task } from '../core/dsl';
+import fetch from 'node-fetch';
+
+task('call-contract-function', 'Call a public function on a deployed Clarity contract')
+  .addParam('contractAddress', 'Deployed contract address (STX...)', { type: 'string', required: true })
+  .addParam('contractName', 'Contract name', { type: 'string', required: true })
+  .addParam('functionName', 'Function name', { type: 'string', required: true })
+  .addParam('args', 'Comma-separated function arguments', { type: 'string', required: false, defaultValue: '' })
+  .addParam('network', 'Network (mainnet|testnet)', { type: 'string', required: false, defaultValue: 'testnet' })
+  .setAction(async (args) => {
+    const contractAddress = args.contractAddress as string;
+    const contractName = args.contractName as string;
+    const functionName = args.functionName as string;
+    const fnArgs = args.args as string;
+    const network = args.network as string;
+    const apiUrl = network === 'mainnet'
+      ? 'https://stacks-node-api.mainnet.stacks.co'
+      : 'https://stacks-node-api.testnet.stacks.co';
+    const url = `${apiUrl}/v2/contracts/call-read/${contractAddress}/${contractName}/${functionName}`;
+    const body = fnArgs
+      ? { arguments: fnArgs.split(',').map((a: string) => a.trim()) }
+      : { arguments: [] };
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw new Error(`Failed to call contract function: ${res.statusText}`);
+    const result = await res.json();
+    return result;
+  });

package/src/tasks/deploy-contract.ts

@@ -0,0 +1,49 @@
+import { task } from '../core/dsl';
+import {
+  makeContractDeploy,
+  broadcastTransaction,
+} from '@stacks/transactions';
+import { createNetwork } from '@stacks/network';
+import fs from 'fs';
+
+function maskAddress(address: string) {
+  return address ? address.slice(0, 6) + '...' + address.slice(-4) : '';
+}
+
+function containsSecret(obj: unknown): boolean {
+  const str = JSON.stringify(obj);
+  return /[A-Za-z0-9]{32,}/.test(str); // crude check for long secrets
+}
+
+// Deploy a Clarity contract to Stacks mainnet or testnet
+task('deploy-contract', 'Deploy a Clarity smart contract to Stacks blockchain')
+  .addParam('contractName', 'Name of the contract', { type: 'string', required: true })
+  .addParam('file', 'Path to Clarity contract file', { type: 'string', required: true })
+  .addParam('network', 'Network to deploy to (mainnet|testnet)', { type: 'string', required: false, defaultValue: 'testnet' })
+  .setAction(async (args, env) => {
+    const contractName = args.contractName as string;
+    const file = args.file as string;
+    const network = args.network as string;
+    const codeBody = fs.readFileSync(file, 'utf8');
+    // Switch network if needed
+    if (network === 'mainnet') {
+      env.network = createNetwork({ network: 'mainnet', client: { baseUrl: env.config.networks.mainnet.url } });
+    } else {
+      env.network = createNetwork({ network: 'testnet', client: { baseUrl: env.config.networks.testnet.url } });
+    }
+    const tx = await makeContractDeploy({
+      contractName,
+      codeBody,
+      senderKey: env.wallet.privateKey,
+      network: env.network,
+    });
+    const result = await broadcastTransaction({ transaction: tx, network: env.network });
+    if (containsSecret(result)) {
+      console.warn('[mobilestacks] Warning: Output may contain sensitive data.');
+    }
+    // Mask any address fields if present
+    if (result && result.txid) {
+      result.txid = maskAddress(result.txid);
+    }
+    return result;
+  });

package/src/tasks/example-task.ts

@@ -0,0 +1,7 @@
+import { task } from '../core/dsl';
+
+task('example', 'An example user task for onboarding')
+  .addParam('name', 'Your name', { type: 'string', required: false, defaultValue: 'World' })
+  .setAction(async (args) => {
+    return `Hello, ${args.name}! Welcome to mobilestacks.`;
+  });

package/src/tasks/faucet-request.ts

@@ -0,0 +1,21 @@
+import { task } from '../core/dsl';
+import fetch from 'node-fetch';
+
+task('faucet-request', 'Request STX from the testnet faucet')
+  .addParam('address', 'STX address to fund', { type: 'string', required: true })
+  .setAction(async (args, env) => {
+    if (env.network.client.baseUrl && env.network.client.baseUrl.includes('testnet')) {
+      const url = `https://stacks-node-api.testnet.stacks.co/extended/v1/faucet/stx`; // Default testnet faucet
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ address: args.address })
+      });
+      if (!res.ok) {
+        throw new Error(`Faucet request failed: ${res.statusText}`);
+      }
+      return await res.json();
+    } else {
+      throw new Error('Faucet is only available on testnet.');
+    }
+  });

package/src/tasks/get-balance.ts

@@ -0,0 +1,34 @@
+import { task } from '../core/dsl';
+import fetch from 'node-fetch';
+
+function maskAddress(address: string) {
+  return address ? address.slice(0, 6) + '...' + address.slice(-4) : '';
+}
+
+function containsSecret(obj: unknown): boolean {
+  const str = JSON.stringify(obj);
+  return /[A-Za-z0-9]{32,}/.test(str); // crude check for long secrets
+}
+
+task('get-balance', 'Get STX balance for the configured wallet address or a provided address')
+  .addParam('address', 'STX address to check (optional, defaults to wallet main address)', { type: 'string', required: false })
+  .setAction(async (args, env) => {
+    const address = (args.address as string) || env.wallet.address;
+    if (!address) throw new Error('No wallet address found.');
+    const network = env.network;
+    const apiUrl = network.client.baseUrl;
+    const url = `${apiUrl}/extended/v1/address/${address}/balances`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch balance: ${res.statusText}`);
+    const data: unknown = await res.json();
+    const result = {
+      address: maskAddress(address),
+      stx: (data as { stx: { balance: string; locked: string; unlock_height: number } }).stx.balance,
+      locked: (data as { stx: { balance: string; locked: string; unlock_height: number } }).stx.locked,
+      unlock_height: (data as { stx: { balance: string; locked: string; unlock_height: number } }).stx.unlock_height
+    };
+    if (containsSecret(result)) {
+      console.warn('[mobilestacks] Warning: Output may contain sensitive data.');
+    }
+    return result;
+  });

package/src/tasks/get-contract-info.ts

@@ -0,0 +1,18 @@
+import { task } from '../core/dsl';
+import fetch from 'node-fetch';
+
+task('get-contract-info', 'Get contract attributes and details from Stacks blockchain')
+  .addParam('contractAddress', 'Deployed contract address (STX...)', { type: 'string', required: true })
+  .addParam('contractName', 'Contract name', { type: 'string', required: true })
+  .addParam('network', 'Network (mainnet|testnet)', { type: 'string', required: false, defaultValue: 'testnet' })
+  .setAction(async (args) => {
+    const { contractAddress, contractName, network } = args;
+    const apiUrl = network === 'mainnet'
+      ? 'https://stacks-node-api.mainnet.stacks.co'
+      : 'https://stacks-node-api.testnet.stacks.co';
+    const url = `${apiUrl}/extended/v1/contract/${contractAddress}/${contractName}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch contract info: ${res.statusText}`);
+    const info = await res.json();
+    return info;
+  });

package/src/tasks/get-tx-history.ts

@@ -0,0 +1,39 @@
+import { task } from '../core/dsl';
+import fetch from 'node-fetch';
+
+function maskAddress(address: string) {
+  return address ? address.slice(0, 6) + '...' + address.slice(-4) : '';
+}
+
+function containsSecret(obj: unknown): boolean {
+  const str = JSON.stringify(obj);
+  return /[A-Za-z0-9]{32,}/.test(str); // crude check for long secrets
+}
+
+task('get-tx-history', 'Get transaction history for the configured wallet address')
+  .addParam('limit', 'Number of transactions to fetch', { type: 'number', required: false, defaultValue: 10 })
+  .setAction(async (args, env) => {
+    const address = env.wallet.address;
+    if (!address) throw new Error('No wallet address found.');
+    const network = env.network;
+    const apiUrl = network.client.baseUrl;
+    const url = `${apiUrl}/extended/v1/address/${address}/transactions?limit=${args.limit}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch tx history: ${res.statusText}`);
+    const data = await res.json() as { results: unknown[] };
+    const txs = data.results.map((tx) => ({
+      tx_id: (tx as { tx_id: string }).tx_id,
+      type: (tx as { tx_type: string }).tx_type,
+      status: (tx as { tx_status: string }).tx_status,
+      fee_rate: (tx as { fee_rate: string }).fee_rate,
+      block_height: (tx as { block_height: number }).block_height
+    }));
+    // Mask address in logs and warn if secrets detected
+    if (containsSecret(txs)) {
+      console.warn('[mobilestacks] Warning: Output may contain sensitive data.');
+    }
+    return {
+      address: maskAddress(address),
+      transactions: txs
+    };
+  });

package/src/tasks/list-accounts.ts

@@ -0,0 +1,27 @@
+import { task } from '../core/dsl';
+import { generateWallet } from '@stacks/wallet-sdk';
+
+function maskAddress(address: string) {
+  return address ? address.slice(0, 6) + '...' + address.slice(-4) : '';
+}
+
+function containsSecret(obj: unknown): boolean {
+  const str = JSON.stringify(obj);
+  return /[A-Za-z0-9]{32,}/.test(str); // crude check for long secrets
+}
+
+task('list-accounts', 'List all accounts derived from the configured seed phrase')
+  .setAction(async (args, env) => {
+    if (!env.config.wallet.seedPhrase) {
+      throw new Error('No seed phrase configured.');
+    }
+    const wallet = await generateWallet({ secretKey: env.config.wallet.seedPhrase, password: '' });
+    const result = wallet.accounts.map((a: unknown) => ({
+      address: maskAddress((a as { address: string }).address || (a as { stxAddress: string }).stxAddress),
+      index: (a as { index: number }).index
+    }));
+    if (containsSecret(result)) {
+      console.warn('[mobilestacks] Warning: Output may contain sensitive data.');
+    }
+    return result;
+  });

package/src/tasks/send-stx.ts

@@ -0,0 +1,39 @@
+import { task } from '../core/dsl';
+import { broadcastTransaction, makeSTXTokenTransfer } from '@stacks/transactions';
+
+function maskAddress(address: string) {
+  return address ? address.slice(0, 6) + '...' + address.slice(-4) : '';
+}
+
+function containsSecret(obj: unknown): boolean {
+  const str = JSON.stringify(obj);
+  return /[A-Za-z0-9]{32,}/.test(str); // crude check for long secrets
+}
+
+// This task sends STX to an address using the loaded SRE (env)
+task('send-stx', 'Sends STX to an address')
+  .addParam('to', 'Recipient STX address', { type: 'string', required: true })
+  .addParam('amount', 'Amount in microSTX', { type: 'number', required: true })
+  .addParam('memo', 'Optional memo', { type: 'string', required: false, defaultValue: '' })
+  .setAction(async (args, env) => {
+    const to = args.to as string;
+    const amount = args.amount as number;
+    const memo = args.memo as string | undefined;
+    const { wallet, network } = env;
+    const tx = await makeSTXTokenTransfer({
+      recipient: to,
+      amount: BigInt(amount),
+      senderKey: wallet.privateKey,
+      network,
+      memo: memo || undefined
+    });
+    const result = await broadcastTransaction({ transaction: tx, network });
+    if (containsSecret(result)) {
+      console.warn('[mobilestacks] Warning: Output may contain sensitive data.');
+    }
+    // Mask any address fields if present
+    if (result && result.txid) {
+      result.txid = maskAddress(result.txid);
+    }
+    return result;
+  });

package/src/tasks/verify-contract.ts

@@ -0,0 +1,33 @@
+import { task } from '../core/dsl';
+import fetch from 'node-fetch';
+import fs from 'fs';
+
+task('verify-contract', 'Verify a deployed Clarity contract on the Stacks explorer')
+  .addParam('contractAddress', 'Deployed contract address (STX...)', { type: 'string', required: true })
+  .addParam('contractName', 'Contract name', { type: 'string', required: true })
+  .addParam('source', 'Path to contract source file', { type: 'string', required: true })
+  .addParam('network', 'Network (mainnet|testnet)', { type: 'string', required: false, defaultValue: 'testnet' })
+  .setAction(async (args) => {
+    const contractAddress = args.contractAddress as string;
+    const contractName = args.contractName as string;
+    const source = args.source as string;
+    const network = args.network as string;
+    const codeBody = fs.readFileSync(source, 'utf8');
+    const apiUrl = network === 'mainnet'
+      ? 'https://stacks-node-api.mainnet.stacks.co'
+      : 'https://stacks-node-api.testnet.stacks.co';
+    // Fetch contract source from chain
+    const url = `${apiUrl}/extended/v1/contract/source/${contractAddress}/${contractName}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Failed to fetch on-chain contract source: ${res.statusText}`);
+    const onChain = await res.json() as { source_code?: string };
+    const verified = onChain.source_code && onChain.source_code.trim() === codeBody.trim();
+    const explorer = network === 'mainnet'
+      ? `https://explorer.stacks.co/txid/${contractAddress}.${contractName}`
+      : `https://explorer.stacks.co/txid/${contractAddress}.${contractName}?chain=testnet`;
+    return {
+      verified,
+      message: verified ? 'Contract source matches on-chain code!' : 'Source does NOT match on-chain code!',
+      explorer
+    };
+  });

package/src/types/config.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+export const NetworkConfigSchema = z.object({
+  url: z.string().url(),
+  name: z.string(),
+  explorerUrl: z.string().url().optional(),
+  faucetUrl: z.string().url().nullable().optional(),
+});
+
+
+// Wallet config: allow privateKey, seedPhrase, or both. If both, privateKey is used.
+export const WalletConfigSchema = z.object({
+  privateKey: z.string().min(1, "Private key is required").optional(),
+  seedPhrase: z.string().optional(),
+  derivationPath: z.string().optional(),
+  address: z.string().optional(),
+}).refine(
+  (data) => data.privateKey || data.seedPhrase,
+  { message: "Either privateKey or seedPhrase is required" }
+);
+
+export const MobilestacksConfigSchema = z.object({
+  networks: z.record(NetworkConfigSchema),
+  defaultNetwork: z.string(),
+  wallet: WalletConfigSchema,
+});
+
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+export type WalletConfig = z.infer<typeof WalletConfigSchema>;
+export type MobilestacksConfig = z.infer<typeof MobilestacksConfigSchema>;