{"_id":"@blockrealm/stacks-sdk","name":"@blockrealm/stacks-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@blockrealm/stacks-sdk","version":"0.1.0","description":"Build on-chain territory games on Stacks using GridWar contracts","type":"module","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["stacks","blockchain","game","sdk","clarity","bitcoin"],"license":"MIT","author":{"name":"Sukanto01899"},"repository":{"type":"git","url":"git+https://github.com/Sukanto01899/blockrealm-stacks-sdk.git"},"homepage":"https://github.com/Sukanto01899/blockrealm-stacks-sdk#readme","bugs":{"url":"https://github.com/Sukanto01899/blockrealm-stacks-sdk/issues"},"publishConfig":{"access":"public"},"dependencies":{"@stacks/connect":"^7.10.0","@stacks/network":"^6.13.0","@stacks/transactions":"^6.12.0"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.4.0"},"peerDependencies":{"@stacks/connect":">=7.0.0"},"_id":"@blockrealm/stacks-sdk@0.1.0","gitHead":"2a1a4fc7983abfadeb351775520e49f24b7cc21a","_nodeVersion":"24.2.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-sN2C313ypf7T/e21/3ZecH342TUvHC6I7txfvd1NAGhhv9Re0xGLACCZNNEn/3FOxdvVyDdUcrJug3xM+eNC9A==","shasum":"61930535a475138054e4cb6126e8862169383537","tarball":"https://registry.npmjs.org/@blockrealm/stacks-sdk/-/stacks-sdk-0.1.0.tgz","fileCount":9,"unpackedSize":112549,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCz4nmPdlCVGnCochyvJr8xPJKau/98P3HtWJL2uvU3AgIgHJZBUvcqZVhi6YowmtSKlM0EelznW1xV3iwYF3JiVW4="}]},"_npmUser":{"name":"sukanto","email":"sukanto01899@gmail.com"},"directories":{},"maintainers":[{"name":"sukanto","email":"sukanto01899@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stacks-sdk_0.1.0_1780767481680_0.11173680288938193"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-06T17:38:01.564Z","0.1.0":"2026-06-06T17:38:01.827Z","modified":"2026-06-06T17:38:02.018Z"},"maintainers":[{"name":"sukanto","email":"sukanto01899@gmail.com"}],"description":"Build on-chain territory games on Stacks using GridWar contracts","homepage":"https://github.com/Sukanto01899/blockrealm-stacks-sdk#readme","keywords":["stacks","blockchain","game","sdk","clarity","bitcoin"],"repository":{"type":"git","url":"git+https://github.com/Sukanto01899/blockrealm-stacks-sdk.git"},"author":{"name":"Sukanto01899"},"bugs":{"url":"https://github.com/Sukanto01899/blockrealm-stacks-sdk/issues"},"license":"MIT","readme":"# @blockrealm/stacks-sdk\n\n> Build on-chain territory games on Stacks (Bitcoin L2)\n\nA TypeScript SDK for building **GridWar**-style on-chain territory war games on the\nStacks blockchain. Capture tiles, attack rivals, harvest resources, upgrade your\nterritory, and compete on an epoch-based leaderboard — all backed by Clarity smart\ncontracts.\n\n## Install\n\n```bash\nnpm install @blockrealm/stacks-sdk\n```\n\nPeer dependency: `@stacks/connect` (`>=7.0.0`) for wallet transactions.\n\n## Quick Start\n\n```ts\nimport { GridWarSDK } from '@blockrealm/stacks-sdk'\n\nconst sdk = new GridWarSDK({\n  network: 'testnet',\n  contractAddress: 'ST1ABC...XYZ', // your deployer address\n  // optional overrides:\n  // tileRegistryName: 'tile-registry',\n  // gameEngineName: 'game-engine',\n})\n\n// --- Reads (no wallet needed) ---\nconst tile = await sdk.tiles.get(5, 10)\nconsole.log(tile.owner, tile.level, tile.resources, tile.isOwned)\n\nconst stats = await sdk.player.getStats('ST2PLAYER...')\nconsole.log(stats.tileCount, stats.totalResources)\n\n// --- Writes (opens the connected wallet) ---\nconst cap = await sdk.tiles.capture(5, 10)\nconsole.log('Captured! Track:', cap.explorerUrl)\n\nawait sdk.tiles.attack(3, 7)\nawait sdk.leaderboard.register()\n\n// --- Events ---\nconst unsubscribe = sdk.on('tile:captured', (e) => {\n  console.log(`Tile ${e.tileId} captured by ${e.owner} at (${e.x}, ${e.y})`)\n})\n// later: unsubscribe()\n```\n\n## API Reference\n\n### `sdk.tiles`\n\n| Method | Returns | Description |\n| --- | --- | --- |\n| `get(x, y)` | `Promise<Tile>` | Full tile data at `(x, y)` |\n| `getOwner(x, y)` | `Promise<string>` | Owner principal (`''` if unowned) |\n| `isOwned(x, y)` | `Promise<boolean>` | Whether the tile is owned |\n| `capture(x, y)` | `Promise<TxResult>` | Capture an unowned tile |\n| `attack(x, y)` | `Promise<TxResult>` | Attack an enemy tile |\n| `harvest(x, y)` | `Promise<TxResult>` | Harvest resources from your tile |\n| `upgrade(x, y)` | `Promise<TxResult>` | Upgrade your tile (max level 5) |\n| `calculateAttackCost(level)` | `bigint` | Attack cost in microSTX |\n| `calculateUpgradeCost(level)` | `bigint` | Upgrade cost in microSTX |\n| `calculateHarvestAmount(level, blocks)` | `bigint` | Harvestable amount for elapsed blocks |\n\n### `sdk.player`\n\n| Method | Returns | Description |\n| --- | --- | --- |\n| `getStats(address)` | `Promise<PlayerStats>` | Tile count + total resources |\n| `getTileCount(address)` | `Promise<number>` | Number of tiles owned |\n| `getTotalResources(address)` | `Promise<bigint>` | Total resources harvested |\n| `calculateScore(stats)` | `number` | `tileCount * 100 + resources` |\n\n### `sdk.leaderboard`\n\n| Method | Returns | Description |\n| --- | --- | --- |\n| `register()` | `Promise<TxResult>` | Register the connected wallet |\n| `submitScore()` | `Promise<TxResult>` | Submit score for the active epoch |\n| `endEpoch(first, second, third)` | `Promise<TxResult>` | End epoch with top 3 (anyone, after it ends) |\n| `fundRewards(amount)` | `Promise<TxResult>` | Add microSTX to the reward pool |\n| `getCurrentEpoch()` | `Promise<number>` | Current epoch number |\n| `getEpochWinner(epoch)` | `Promise<EpochWinner \\| null>` | Winners of a past epoch |\n| `getPlayerScore(address, epoch)` | `Promise<PlayerEpochScore \\| null>` | A player's score for an epoch |\n| `getEpochBlocksRemaining()` | `Promise<number>` | Blocks left until the epoch ends |\n| `isRegistered(address)` | `Promise<boolean>` | Whether an address is registered |\n\n### Events\n\n```ts\nsdk.on(type, handler) // returns an unsubscribe function\nsdk.emit(event)\nsdk.off(type)\n```\n\nEvent types: `tile:captured`, `tile:attacked`, `tile:harvested`, `tile:upgraded`,\n`player:registered`, `score:submitted`, `epoch:ended`.\n\n## Error Handling\n\nAll failures throw a typed `GridWarError` with a `code` from `GridWarErrorCode`.\nContract revert codes (`u100`–`u207`) are mapped automatically.\n\n```ts\nimport { GridWarError, GridWarErrorCode } from '@blockrealm/stacks-sdk'\n\ntry {\n  await sdk.tiles.capture(5, 10)\n} catch (err) {\n  if (err instanceof GridWarError) {\n    switch (err.code) {\n      case GridWarErrorCode.TILE_ALREADY_OWNED:\n        console.warn('That tile is already taken.')\n        break\n      case GridWarErrorCode.USER_CANCELLED:\n        console.warn('You cancelled the transaction.')\n        break\n      default:\n        console.error(err.code, err.message, err.contractErrorCode)\n    }\n  }\n}\n```\n\n## Deploy Your Own Contracts\n\nThe SDK talks to two Clarity contracts: `tile-registry` (core data + leaderboard)\nand `game-engine` (attack / harvest / upgrade). Deploy your own with\n[Clarinet](https://docs.hiro.so/stacks/clarinet):\n\n```bash\n# scaffold + add tile-registry.clar and game-engine.clar\nclarinet check\n\n# testnet\nclarinet deployments generate --testnet --medium-cost\nclarinet deployments apply --testnet\n\n# after deploy, authorize the engine to write tile state:\n#   tile-registry.authorize-contract(<deployer>.game-engine)\n```\n\nThen point the SDK at your deployer address:\n\n```ts\nconst sdk = new GridWarSDK({ network: 'testnet', contractAddress: 'ST_YOUR_DEPLOYER' })\n```\n\nIf you use custom contract names, pass `tileRegistryName` / `gameEngineName`.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-3700bcac0b966c3e8c841b874e665d80"}