buildr-sdk

TypeScript SDK for interacting with the Buildr smart contracts on the Stacks blockchain.

Installation

npm install buildr-sdk
# or
yarn add buildr-sdk
# or
pnpm add buildr-sdk

Quick Start

import { createBuildrConfig, fetchBuilderProfile, isBuilderRegistered } from 'buildr-sdk';

const config = createBuildrConfig({
  network: 'mainnet',
  contractAddress: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ',
});

const profile = await fetchBuilderProfile(config, 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ');
console.log(profile);
// {
//   address: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ',
//   githubHandle: 'octocat',
//   isVerified: true,
//   isActive: true,
//   registeredAt: 123456,
// }

Configuration

import { createBuildrConfig } from 'buildr-sdk';

const config = createBuildrConfig({
  // 'mainnet' | 'testnet' | 'devnet'
  network: 'mainnet',

  // Deployer principal of the Buildr contracts
  contractAddress: 'SP...',

  // Optional: override the default Stacks API URL
  stacksApiUrl: 'https://api.mainnet.hiro.so',

  // Optional: override individual contract names
  registryContractName: 'buildr-registry',
  scoresContractName: 'builder-scores',
  programContractName: 'reward-program',
  subscriptionContractName: 'subscription',
});

API Reference

Registry

import {
  fetchBuilderProfile,
  fetchBuilderCount,
  isBuilderRegistered,
  isGithubHandleTaken,
} from 'buildr-sdk';

// Fetch a builder's profile
const profile = await fetchBuilderProfile(config, address);

// Check if a builder is active
const active = await isBuilderRegistered(config, address);

// Check if a GitHub handle is already taken
const taken = await isGithubHandleTaken(config, 'octocat');

// Get total registered builder count
const count = await fetchBuilderCount(config);

Scores

import { fetchBuilderScore, fetchProgramScores, computeScore } from 'buildr-sdk';

// Fetch a builder's score for a specific program
const score = await fetchBuilderScore(config, address, programId);

// Fetch all scores for a program
const scores = await fetchProgramScores(config, programId);

// Compute the weighted score locally
const score = computeScore(contractsDeployed, githubContributions);
// Formula: (contractsDeployed × 60) + (githubContributions × 40)

Reward Programs

import {
  fetchRewardProgram,
  fetchProgramStatus,
  fetchRewardDistributions,
  fetchLatestProgramId,
} from 'buildr-sdk';

// Fetch full program details
const program = await fetchRewardProgram(config, programId);

// Get current program state: 'pending' | 'open' | 'finalising' | 'closed'
const state = await fetchProgramStatus(config, programId);

// Get the reward distribution for a closed program
const distributions = await fetchRewardDistributions(config, programId);

// Get the most recent program ID
const latestId = await fetchLatestProgramId(config);

Subscriptions

import {
  fetchSubscription,
  fetchSubscriptionTier,
  isSubscriptionActive,
} from 'buildr-sdk';

// Fetch full subscription record
const sub = await fetchSubscription(config, address);

// Get tier name: 'free' | 'pro' | 'enterprise'
const tier = await fetchSubscriptionTier(config, address);

// Check if the address has an active paid subscription
const active = await isSubscriptionActive(config, address);

Utilities

import {
  microToStx,
  stxToMicro,
  formatStx,
  truncateAddress,
  validateAddress,
  validateGithubHandle,
  formatScore,
  blocksToMinutes,
} from 'buildr-sdk';

microToStx(10_000_000)          // → 10
stxToMicro(10)                  // → 10_000_000
formatStx(10_000_000)           // → "10 STX"
truncateAddress('SP2J6...V9EJ') // → "SP2J…V9EJ"
validateAddress('SP2J6...')     // → true
validateGithubHandle('octocat') // → true
formatScore(1240)               // → "1,240"
blocksToMinutes(144)            // → 1440

Development

pnpm install
pnpm build      # compile CJS + ESM with DTS
pnpm test       # run Vitest test suite

License

MIT