@signarank/client

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

The official client SDK for SignaRank — a cooperative blockchain game where players band together to take down powerful Constructs living on the Signum 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 and join the hunt.

Installation

npm install @signarank/client

The SDK requires @signumjs as peer dependencies:

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

Quick Start

Read-only: Check construct status & player stats

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

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") },
  ],
});

Character: read a sheet & take actions

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

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

// Discover your (non-migrated) characters
const characters = await player.getCharacters();
const character = player.character(characters[0].characterId);

// Read the full sheet: attributes, combat profile, progression, vitals, inventory, conditions
const sheet = await character.getSheet();
const { level, xpPoints, xpToNextLevel } = sheet.progression;
console.log(`Level ${level} (${xpPoints} XP, ${xpToNextLevel} to next) — HP ${sheet.vitals.currentHp}/${sheet.vitals.maxHp}`);

// Check what went wrong recently, in plain English
for (const error of await character.getErrorLog()) {
  console.log(`[${error.txId}] ${error.message}`);
}

// Spend a skill point (1=Strength, 2=Stamina, 3=Dexterity, 4=Luck, 5=Willpower)
await character.allocateSkillPoint(1);

// Attack a construct through the character — force must cover both the
// character's and the construct's activation amounts
await character.attack({
  constructId: "CONSTRUCT_ID",
  force: Amount.fromSigna("10"),
});

A read-only Character (no signer, reads only) can also be obtained from ReadOnlyPlayer.character(characterId).

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) | | getCharacters() | { characterId: string; version: string }[] | Live (non-migrated) characters owned by this account | | character(characterId) | Character | Read-only Character controller (no signer) | | 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) | | character(characterId) | Character | Write-enabled Character controller (signer bound) |

Character

Obtained via player.character(characterId) (write-enabled) or readOnlyPlayer.character(characterId) (read-only).

Reads:

| Method | Returns | Description | |---|---|---| | getSheet() | CharacterSheet | Full sheet: attributes, combat profile, progression, vitals, inventory, conditions | | getAttributes() | Attributes | Strength, stamina, dexterity, luck, willpower | | getCombatProfile() | CombatProfile | Effective combat stats (base + equipment/status bonuses) and current attack effect | | getProgression() | Progression | Level, unspent skill points, XP (character's balance of the registry's XP token), and XP still needed for the next level (triangular curve) | | getVitals() | Vitals | Current/max HP and death state | | getInventory() | InventoryItem[] | Owned items, resolved against the item registry | | getConditions() | Condition[] | Active (non-expired) status effects | | getErrorLog() | CharacterError[] | Recorded on-chain error slots, each with a human-readable message | | getInternalState() | InternalState | Reroll count, committed/migrated flags (read from contract memory) |

Writes (require a signer — use a Character obtained from Player, not ReadOnlyPlayer):

| Method | Returns | Description | |---|---|---| | allocateSkillPoint(attribute) | TransactionId | Spend one skill point (1=Strength, 2=Stamina, 3=Dexterity, 4=Luck, 5=Willpower) | | attack({ constructId, force, elementToken? }) | TransactionId | Attack a construct through the character; force must cover both the character's and the construct's activation amounts | | reroll() | TransactionId | Re-roll attributes (costs 100 SIGNA; tops up the character's balance automatically if needed) | | useItem(tokenId) | TransactionId | Consume/use an inventory item | | transferItem(tokenId, recipientId) | TransactionId | Send an inventory item to another account (recipient must not be a contract) | | seppuku() | TransactionId | Kill the character (only once dead + committed on-chain) | | migrate() | TransactionId | Liquidate the character to a newer version while a migration window is open | | refund() | TransactionId | Return the character's spare SIGNA balance to the owner |

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