The conformance kit: prove your wallet against the contract

The conformance kit sends real, signed wallet calls to your staging wallet and checks that every answer follows the operator contract (openapi.yaml): signatures, idempotency, money, rollbacks and the error codes. It is the deeper version of the back office's Test wallet (and of the Test suite, when that is offered): run it before your first real player, and in your own CI whenever your wallet changes.

The kit has two parts:

• conformance, the checker: a command-line tool, shipped as a Docker image so you need no Node.js.
• wallet-sim, the reference wallet Telos tests against. Run the checker against it to see what a passing wallet looks like, and compare its answers with yours.

Getting the images. The images are not on a public registry yet. Until they are, Telos runs the kit with you, or sends you the images on request: ask your Telos contact. The commands below use the image names spartacus/conformance and spartacus/wallet-sim.

#Before you run it

The kit moves real balances on the wallet you point it at. Use your staging wallet only, never production.

You need:

1. Your staging wallet's base URL: the address the five wallet calls hang off (<base>/player, <base>/balance, <base>/bet, <base>/win, <base>/rollback).
2. Its signing secret, in an environment variable. Never put it on the command line.
3. A test player holding at least 1,000 minor units in each currency you test, whose own stake limits allow its balance + 1 (otherwise the "not enough money" check gets bet_not_allowed instead of insufficient_funds).
4. A second test player on the same wallet, holding the same currencies. Nothing of theirs moves: the kit uses them to send a rollback for a bet they do not own, which you must answer 200 with status: "not_found", moving nothing.
5. A fresh launch token for the first test player.
6. The currencies to test, with their decimals. Put a small-decimals currency first (for example EUR:2 before ETH:18).

#Run it against your wallet

export SP_WEBHOOK_SECRET='…'      # your staging signing secret; never echoed, never logged
docker run --rm -e SP_WEBHOOK_SECRET spartacus/conformance \
  --target https://wallet-staging.example.com/telos \
  --secret-env SP_WEBHOOK_SECRET \
  --test-player player-test-1 \
  --second-player player-test-2 \
  --launch-token "$LAUNCH_TOKEN" \
  --currency EUR:2 --currency ETH:18 \
  --bets-per-round 2 \
  --yes-this-is-a-test-wallet

Read the first line it prints: it names the target and both players. Stop it if any of them is wrong.

#Read the result

• The report lists every check in run order, with the five aggregate checks last.
• A check that was skipped says why.
• A skipped MUST is not a pass. To attest every check, include an 18-decimal currency and run with --bets-per-round 2. Without them, big-amount and two-bets-one-round skip themselves and are marked "not attested".
• In CI, add --report json or --report junit: the report goes to stdout and the progress to stderr.

Each failure is either a real defect in your wallet, or a real disagreement about the contract. Send the second kind to your Telos contact rather than working around it.

Clean-up: the run leaves some bets open on purpose, so it can prove a debit without a settlement (unknown-field, decimals-exact for each currency, two-bets-one-round, bet-repeat, bet-concurrent, conflict). Their stakes stay debited, and the balance-reconciles check already counts them. After the run, void or settle the test player's open bets yourself. Rotate the launch token afterwards if your tokens are reusable.

#See a passing wallet: run it against wallet-sim

docker network create telos-kit
docker run -d --name wallet-sim --network telos-kit spartacus/wallet-sim --secret=demo-secret
# seed the two test players on wallet-sim's admin port (4021)
docker run --rm --network telos-kit curlimages/curl -s -X POST http://wallet-sim:4021/players \
  -H 'Content-Type: application/json' \
  -d '{"user":"player-test-1","tokens":["launch-token-1"],"balances":{"EUR":"100000000"}}'
docker run --rm --network telos-kit curlimages/curl -s -X POST http://wallet-sim:4021/players \
  -H 'Content-Type: application/json' \
  -d '{"user":"player-test-2","balances":{"EUR":"100000000"}}'
docker run --rm --network telos-kit -e SP_WEBHOOK_SECRET=demo-secret spartacus/conformance \
  --target http://wallet-sim:4020 --secret-env SP_WEBHOOK_SECRET \
  --test-player player-test-1 --second-player player-test-2 --launch-token launch-token-1 \
  --currency EUR:2 --bets-per-round 2 --yes-this-is-a-test-wallet
docker rm -f wallet-sim && docker network rm telos-kit

• wallet-sim serves the five wallet calls on port 4020 and an admin API on port 4021:
  • POST /players: seed a player with user, optional tokens, balances and max_stake, and blocked;
  • GET /ledger: every player's balances, and how many bets and rollback markers it holds;
  • POST /reset, and POST /secrets with {"secrets": ["new", "old"]} to replace the signing secrets (list two to imitate a rotation).
• With only EUR:2, big-amount is skipped. Add an 18-decimal currency, and seed its balance, to attest it.

#The checks

The list below is generated from the kit's own source at the version this site was built from.

Per-request checks (31)

Aggregate checks, graded over the whole run (5)

Command line

spartacus-conformance --target <operator webhook base URL> --secret-env <VAR> \
  --test-player <user> --second-player <user> --launch-token <token> \
  --currency <code>:<decimals> [--currency …] \
  [--game-code <code>] [--bets-per-round <n>] --yes-this-is-a-test-wallet \
  [--report json|junit|text]

The suite moves real balances on the target. Point it at the operator's staging wallet, never at
production, with two test players and a fresh launch token.

--second-player is a second test player on the same wallet, holding the same currencies. Only
--test-player's balances move; --second-player exists so the suite can send a rollback signed for
one player naming the other player's bet, which must reverse nothing and disarm nothing.