gem-pluck-sdk

TypeScript SDK for interacting with the Gem Pluck smart contract on Stacks blockchain.

Gem Pluck is an on-chain pluck-a-gem dApp with 6 gems (Ruby, Sapphire, Emerald, Topaz, Amethyst, Onyx). Each pluck is recorded on Stacks mainnet (Clarity 4).

Installation

npm install gem-pluck-sdk

Quick Start

import { GemPluckClient } from "gem-pluck-sdk";

const client = new GemPluckClient({
  contractAddress: "SP16F6839630K5XX06KE7KVNSNMYBK89912NH6N4C",
  contractName: "gem-pluck",
});

// Get count for gem #1 (Ruby)
const ruby = await client.getGemCount(1);
console.log(`Ruby: ${ruby.count}`);

// Get all 6 gem counts in parallel
const all = await client.getAllGemCounts();

// Total plucks across all gems
const total = await client.getTotalPlucks();

// Per-user stats
const me = await client.getUserStats("SP...");

// Leaderboard, sorted by count desc
const board = await client.getLeaderboard();

// Build pluck transaction args (use with @stacks/connect)
const args = client.getPluckArgs(3); // pluck Emerald

API

new GemPluckClient(config)

| Param | Type | Description | |-------|------|-------------| | contractAddress | string | Deployer's Stacks address | | contractName | string | Contract name | | network | "mainnet" \| "testnet" | Network (default: "mainnet") |

Methods

| Method | Returns | |--------|---------| | getGemCount(gemId) | Promise<GemCount> | | getAllGemCounts() | Promise<GemCount[]> | | getTotalPlucks() | Promise<number> | | getUserStats(address) | Promise<UserStats> | | getLeaderboard() | Promise<(GemCount & { name: string })[]> | | getPluckArgs(gemId) | Args for openContractCall |

Constants

import { GEMS } from "gem-pluck-sdk";
// [{ id: 1, name: "Ruby", color: "#e02060" }, ...]

License

MIT