Overview

@CityOfZion/monopoly-sdk exposes a typed Monopoly facade for frontend and backend clients. The SDK currently supports player registration and login flows, leaderboard reads, user portfolio reads, property discovery, property purchases, tip reveals, and administrative update transactions.

The SDK follows the same high-level interaction model as other COZ TypeScript tooling:

• read-only methods use testInvoke
• transaction methods return a txid
• Sync methods submit the transaction, wait for the application log, and parse the finalized result
• mock mode lets frontend developers integrate against generated in-memory data before the backend is complete

Getting started

Installation

npm install @CityOfZion/monopoly-sdk

Real transport

Use Monopoly.init() with a Neo N3 RPC node, contract script hash, and optionally a signer account for transaction-producing methods.

import { Monopoly, constants } from "@CityOfZion/monopoly-sdk";

const monopoly = await Monopoly.init({
  node: constants.NeoN3NetworkOptions.TestNet,
  scriptHash: "0x...",
});

const leaderboard = await monopoly.getLeaderboard();
console.log(leaderboard.ladder);

Mock transport

Mock mode uses the same public SDK methods as production, but swaps in generated in-memory data and mock Neon transport objects. This is useful for frontend integration while the backend and contract surfaces are still being finalized.

By default, mock invocations wait 6000ms to mimic real network latency.

import { Monopoly } from "@CityOfZion/monopoly-sdk";

const monopoly = await Monopoly.init({ mock: true });

const balance = await monopoly.getUserBalance({ pubKey: "demo-player" });
console.log(balance.balance);

Override mock behavior with mock options:

const monopoly = await Monopoly.init({
  mock: {
    scenario: "richUser",
    latencyMs: 0,
    seed: 42,
  },
});

Available scenarios:

• default: a normal demo player with one property, tips, rewards, and leaderboard data
• empty: no generated users or leaderboard entries
• richUser: a higher-balance demo player with more owned properties, tips, and rewards

Usage

Authentication and profile

const registration = await monopoly.registration({
  name: "Demo Player",
  email: "[email protected]",
  age: "21",
  mnemonic: "...",
  contact_marketing: true,
  contact_results: true,
});

const login = await monopoly.login({
  email: "[email protected]",
  code: 123456,
});

Read user state

const pubKey = login.pubKey;

const [balance, properties, tips, rewards] = await Promise.all([
  monopoly.getUserBalance({ pubKey }),
  monopoly.getUserProperties({ pubKey }),
  monopoly.getUserTips({ pubKey }),
  monopoly.getUserRewards({ pubKey }),
]);

Discover and buy properties

const investing = await monopoly.getInvestingProperties({
  locationId: 1,
});

const property = investing.properties[0];

const submitted = await monopoly.buyProperty({
  propertyId: property.id,
});

console.log(submitted.txid);

Use the synchronous helper when the caller needs the finalized contract result:

const result = await monopoly.buyPropertySync({
  propertyId: property.id,
});

console.log(result.profit);

Reveal tips

const submitted = await monopoly.revealTip();
console.log(submitted.txid);

const revealed = await monopoly.revealTipSync();
console.log(revealed.description);

Low-level invocations

For methods that are not yet represented by a typed SDK wrapper, use the generic invocation helpers.

const result = await monopoly.testInvoke({
  operation: "getSomething",
  args: [{ type: "String", value: "demo-player" }],
});

const txid = await monopoly.invoke({
  operation: "setSomething",
  args: [{ type: "Integer", value: "1" }],
});

Development

Install dependencies:

npm install

Build ESM, CJS, and declaration outputs:

npm run tsc

Generated files are emitted to dist/.

Public API

The package entrypoint exports:

• Monopoly: high-level SDK facade
• createMonopolyMock: mock harness factory used by Monopoly.init({ mock: true })
• types: request, response, mock, and transport option types
• constants: Neo N3 network defaults and SDK runtime constants
• helpers: lower-level utility helpers for transaction completion and Neo response handling

License

License details are not yet specified in this repository.