npm package: @signarank/client
Description: Client SDK for SignaRank — cooperative on-chain monster battles on the Signum blockchain
Latest version: 0.0.2

# @signarank/client

**Battle on-chain monsters. Earn rewards. Compete for glory.**

The official client SDK for [SignaRank](https://signarank.club) — a cooperative blockchain game where players band together to take down powerful Constructs living on the [Signum](https://signum.network) blockchain.

## What is SignaRank?

SignaRank is an achievement system rewarding your Signum blockchain activity and ranks you among the top players.

But it does not stop there....

Imagine a world where monsters aren't pixels on a screen — they're **smart contracts**. Each Construct is a living, breathing entity on the Signum blockchain with its own hit points, defenses, and behavior.

Players rally together to attack these Constructs by sending real on-chain transactions. Every hit counts. Every player matters. But watch out — Constructs fight back with debuffs, regeneration, and unpredictable mechanics.

**Land the first hit** and claim the First Blood bonus. **Deal the killing blow** and earn the Final Blow reward. Accumulate XP tokens as you battle, climb the leaderboard, and prove your rank.

This isn't a simulation — it's real value, real strategy, and real competition. All transparent, all verifiable, all on-chain.

**Ready to fight?** Head over to [signarank.club](https://signarank.club) and join the hunt.

## Installation

```bash
npm install @signarank/client
```

The SDK requires `@signumjs` as peer dependencies:

```bash
npm install @signumjs/core @signumjs/util @signumjs/contracts @signumjs/standards @signumjs/http
```

## Quick Start

### Read-only: Check construct status & player stats

```ts
import { ReadOnlyPlayer } from "@signarank/client";
import { LedgerClientFactory } from "@signumjs/core";

const ledger = LedgerClientFactory.createClient({
  nodeHost: "https://europe.signum.network",
});

const player = new ReadOnlyPlayer({
  ledger,
  accountId: "YOUR_ACCOUNT_ID",
});

// Check your balances
const balances = await player.getBalances();

// Get your XP
const xp = await player.getTotalExperiencePoints();

// Read construct on-chain data
const status = await player.constructService.with("CONSTRUCT_ID").getStatus();
console.log(`HP: ${status.hitpoints} / ${status.maxHp}`);
console.log(`Active: ${status.isActive}, Defeated: ${status.isDefeated}`);
```

### Full player: Attack a construct

```ts
import { Player } from "@signarank/client";
import { Amount } from "@signumjs/util";

const player = new Player({
  Ledger: ledger,
  Signer: yourSignerImplementation,
  accountId: "YOUR_ACCOUNT_ID",
});

// Attack with pure force
const tx = await player.attackConstruct({
  targetConstruct: "CONSTRUCT_ID",
  force: Amount.fromSigna("10"),
  powerUps: [],
});

// Attack with a power-up token
const tx2 = await player.attackConstruct({
  targetConstruct: "CONSTRUCT_ID",
  force: Amount.fromSigna("5"),
  powerUps: [
    { assetId: "POWERUP_TOKEN_ID", value: ChainValue.create(0).setCompound("100") },
  ],
});
```

## API

### `ReadOnlyPlayer`

| Method | Returns | Description |
|---|---|---|
| `getBalances()` | `Record<string, AccountBalance>` | All token balances for the player |
| `getTotalExperiencePoints()` | `number` | Total XP earned |
| `getTokenInfo(tokenId)` | `Asset` | Token metadata (cached) |
| `constructService.with(id).getStatus()` | Construct status | HP, activity, defeat state, debuffs, regeneration |
| `constructService.with(id).getPlayerStatus(accountId)` | Player status | Cooldown, debuff, XP, last attack |
| `constructService.with(id).getMetadata()` | SRC44 descriptor | On-chain metadata |

### `Player` extends `ReadOnlyPlayer`

| Method | Returns | Description |
|---|---|---|
| `attackConstruct({ targetConstruct, force, powerUps })` | `UnsignedTransaction` | Attack a construct with optional power-ups (max 3) |

### Storage

The SDK includes `MemoryStorage` and `LocalStorage` implementations for caching token data. Pass a custom `IStorage<Asset>` to the player constructor if you need a different backend.

## License

MIT