Working protocol / Integration guide

Adding an API
to KMCoin.

Start with one question: can another validator independently obtain enough evidence to verify this producer’s proposal?

This guide describes a new source adapter. It does not register a producer or activate a new consensus rule.

01 / A discoverable source

The producer ID must lead validators to the same collection.

Encode a stable platform account ID in the block. Validators use it to query the source account, rather than trusting the submitting node’s private copy of its data. For Steam and the Xbox adapter, that collection is the producer’s friend list.

Minimum evidence path

source ID in block
  → independently readable collection
  → canonical list and commitment
  → eligible player selection
  → agreed verified candidate

Test the read from at least two independent validator accounts. A producer reading its own private list is not enough. The complete collection must be available, including every page; a truncated response cannot stand in for the whole set.

A group or roster could replace friends if membership can be read consistently and hashed under defined rules. Do not accept an arbitrary URL from a block as a verification target. The adapter defines the API endpoints and supported identity format.

02 / Canonical inputs

Write the byte-level rules before building the loop.

Define ID format, duplicate handling, sorting, delimiters, text encoding, pagination and commitment hashing. Validators must produce identical bytes for the same collection. Preserve long identifiers as strings or exact integers, without floating-point rounding.

Existing adapters have their own serialization rules. The Xbox adapter deduplicates XUIDs, sorts numerically and joins them with a newline before hashing. Do not silently change Steam’s serialization to match a new adapter.

Reserve a distinct source block range or another explicitly versioned discriminator. Specify height increments, wrap behavior, timestamp placement and Phase I/II recognition. The current seven-field API body stores timestamp and local number in its first field; adding an unrecognized token can break older parsers.

Persist source sequence and collection-change state across restarts. Specify which observations advance warmup counters. A replay must not advance them as though it were a new source block.

03 / Eligible rewards

Separate the network draw from the platform check.

The network winner calculation decides whether a proposal proceeds to API verification. The adapter then determines which player qualifies. In the current design, validators derive a starting index and walk the agreed friend order, wrapping to the first eligible in-game account.

Define eligibility precisely: which fields indicate a game, which states are excluded, and what missing presence means. A dashboard or media app must not accidentally qualify because a field is merely nonempty.

Retain Phase I audit evidence and bind Phase II to the original candidate. Validators independently query the API and submit their results; majority selects the exact Phase II transactions. A missing or different local API receipt does not override that majority. Current ledger authorization is checked again when applying the result.

04 / Transaction evidence

Resolve the sender from the wallet, then query its identity.

transaction sender wallet
  → stable copy of current ledger player record
  → local hash-chain, counter, type and balance checks
  → ledger-linked platform identity
  → API check of exact public transaction evidence
  → majority selection and current-state checks at finalization

A writable profile can be a transaction board. The producer observes a submission and includes the full candidate; other validators verify it again. Local polling and batching need not happen simultaneously, but accepted transactions need unambiguous bytes and an authorization path.

Transaction evidence used by the adapters
IdentityVerification rule
XboxThe Bio owner matches the wallet’s recorded XUID. The complete transaction appears on its own line.
Steam via XboxThe Xbox Bio carries the full transaction. The linked Steam real-name field equals the first 63 lowercase hexadecimal characters of SHA-256 of the entire UTF-8 transaction, including its semicolon.
Minecraft Java via XboxDecode the UUID from the wallet's first-mined block; require one unambiguous valid result. Fetch that UUID's skin and decode the exact full transaction. A skin checksum detects corruption; it does not replace account and ledger authorization.

Publishing another player’s ID in a Bio proves nothing by itself. A copied skin is insufficient unless retrieved from the account bound to the sending wallet. No Xbox/Minecraft ownership link is inferred from achievements or display names.

For images or other binary evidence, bound the download size, require the expected format and dimensions, and decode only the defined payload. The Minecraft route accepts a bounded 64x64 PNG and extracts literal transaction text from a fixed pixel region. It never evaluates that text as code. Parser and image-library failures must reject evidence rather than approve it.

Specify initial setup separately from spending and renewal. Native Steam’s abbreviated setup has a controlled final-character correction; that does not permit rewriting arbitrary transaction fields. Full renewal proves the old public key and binds the replacement key in the evidence.

05 / Integration surface

Keep collection and verification outside ledger mutation.

Producer

Reads its configured source ID, obtains the collection and stages a candidate under the sender’s timestamp and cadence rules.

Submission watcher

Batch-reads public fields, persists observations and stages changed submissions once. It does not write balances.

Verifier

Consumes agreed Phase I work, independently checks membership, presence and transaction evidence, then stages its verified result.

The Java integration recognizes the source, requires the matching winning Phase I record, and applies majority-selected transactions through current ledger rules. A local verifier's omitted transaction or unavailable API receipt does not veto the configured majority. Local authorization checks use a stable player-info copy before transaction evidence calls; finalization repeats the financial checks. No API helper directly appends a reward or transaction to the ledger.

Budget requests for production, presence, transaction evidence and authentication refresh. Batch where supported and test with a full collection. A free-tier quota is not a protocol capacity guarantee.

Developer notes on API capacity show rotating discovery, batched verification and separate service budgets. The Xbox watcher reads the next 20 Bios each minute; game selection walks friends in batches of 16; Steam evidence carried through Xbox is batched at up to 100 identities per request.

Keep API access separate from player authorization. A validator uses its own Xbox account to sign in on Microsoft's page and obtain a local token for API lookups. The adapter does not collect gaming passwords or edit player profiles. Players publish a valid transaction and its public evidence; their wallet secret stays local.

Preserve admitted transaction candidates when a Phase I proposal loses the winner test. Steam and Xbox keep separate pending pools, so a later winner of the matching source type can carry them. Xbox carries the relay Bio owner alongside cross-platform candidates, then writes only accepted transaction text to the ledger. Failed evidence attempts require a newly observed Bio change; pending candidates are checked against current wallet state before another API attempt.

Distinguish failed verification from unavailable evidence. A mismatched commitment rejects a candidate. A timeout, missing page or rate limit must not become approval. Bound work, expose failures and follow defined pending/deadline behavior.

Change-triggered submissions need an explicit manual retry mechanism. An unchanged Bio should not flood later blocks. Publish supporting proof first, then the submission, and keep both visible through verification. Passwords, unrevealed private material and login tokens stay out of blocks, profiles, skins and peer snapshots. A transaction intentionally publishes only the hash-chain proof needed for that step.

06 / Acceptance tests

Prove agreement before opening production.

  • Independent API identities can read the same producer collection and player evidence.
  • Reordered responses and duplicate IDs produce the defined commitment; incomplete pagination fails explicitly.
  • Changed lists, unexpected heights, allowed wrap and restarts produce the expected source-history behavior.
  • Wrong identities, changed transaction bytes, missing evidence and unrelated skin payloads are rejected.
  • Initial setup, transfers, bridges, boundary renewal and the first spend under the new key produce the expected state.
  • Block/transaction replays cannot award or spend twice. Interrupted work cannot reuse a previous block’s staged state.
  • API errors, rate limits and expired credentials never produce a verified result.
  • Equivalent accepted inputs produce matching ledger, balance, counter, key and consensus outputs on independent validators.

Finish with controlled live tests of visibility, changing profiles and restarts. Publish test vectors and a coordinated upgrade procedure. Participating validators must understand the source before its blocks enter the network.

Working protocol · Player data feed for local tools