Protocol Specification Document

1. Introduction

The BQuest platform uses smart contracts and CashTokens to validate user identities. The presence of a BQUser CashToken in a wallet indicates that the owner lays claim to the moniker stored in its commitment.

2. BQUser CashToken Structure

CashToken Format:

Length of Name: Between 4 and 15 characters (inclusive).

Allowed Characters: Lowercase letters (a–z), numbers (0–9), underscores (_). No other characters are allowed. Usernames are case-insensitive — input is normalised to lowercase before encoding and always stored on-chain as lowercase.

Platform ID / Validity Bytes: Three 1-byte (2 hex character) values representing the platform ID, positive validity, and negative validity.

3. BQUser CashToken Commitment

The CashToken commitment is a byte string that includes the length of the name, the name itself (ASCII hex-encoded), and three bytes for platform ID, positive validity, and negative validity.

CashToken Commitment Structure:

<length_of_name><name_hex><platform_id><positive_validity><negative_validity>

Field	Size	Description
Length of name	1 byte	Decimal length of the name (4–15), hex-encoded
Name	variable	Each character encoded as its ASCII hex value
Platform ID	1 byte (2 hex chars)	Identifies the issuing platform
Positive Validity	1 byte (2 hex chars)	Number of positive validity assertions
Negative Validity	1 byte (2 hex chars)	Number of negative validity (dispute) assertions

Example Commitment:

0a757365726e616d655f31090201

Field	Hex	Decoded
Length of name	`0a`	10
Name	`757365726e616d655f31`	`username_1`
Platform ID	`09`	Platform 09 (BQuest)
Positive Validity	`02`	2
Negative Validity	`01`	1

Initial state at registration: All tokens are minted with positive validity 02 and negative validity 01 regardless of platform. A freshly registered user is valid (pos > neg) but one dispute immediately contests that status.

Known Platform IDs:

Decimal	Hex	Platform	Registration path
2	`02`	X (Twitter)	`BQXOnboarding` contract — X handle verified, OTP via DM
3	`03`	Telegram	Reserved for future Telegram onboarding contract
9	`09`	BQuest	`BQUserGeneration` contract — direct self-registration
10	`0a`	Invited	`BQProcessNominee` contract — social sponsor flow
11	`0b`	Local	`BQProcessNominee` contract — in-person operator flow

Slots 01, 04–08 are reserved for future platforms. The <username, platform_id> pair is the canonical identity key — the same username may exist independently on different platforms.

What is claimed?

This commitment claims that username_1 is a valid user on platform 09 (BQuest). There may be another valid username_1 on a different platform.

4. Validation Mechanism

Validation involves a blockchain lookup to verify the existence of the CashToken commitment in an unspent transaction output (UTXO). The process is as follows:

Blockchain Lookup: Interested parties query the Bitcoin Cash blockchain for UTXOs containing the provided CashToken.

Verification:

If the lookup is successful and the last known commitment has a positive validity greater than its negative validity, the party can assume that the locking bytecode (LBC) of this UTXO belongs to a valid BQuest platform user. Funds can then be sent to the BCH address encoded in the LBC.

Note: Funds sent to an address whose validity is disputed (negative validity ≥ positive validity) are not blocked or sanctioned by the protocol in any way. The protocol provides an identity signal only; fund transfers remain the sender's responsibility.

Steps for Validation:

Query Blockchain: Perform a blockchain lookup to find the last known UTXO associated with the CashToken.
Check Validity: Verify that the positive validity of the commitment is greater than its negative validity.
Assume Valid User: If the conditions are met, assume the LBC belongs to a valid BQuest platform user.
Send Funds: Send funds to the BCH address encoded in the LBC.

For a concrete implementation guide including GraphQL queries, commitment encoding, and address derivation, see Integration.md.

Out-of-Band Registration and Gaming Resistance

The BQUserGeneration contract is permissionless: any party can call it directly, bypassing application-level checks such as username availability. However, this does not undermine the protocol's integrity.

Every token minted by BQUserGeneration carries the same initial commitment <platform_id> 02 01. Because the initial state is fixed and identical for all registrations, the protocol resolves ambiguity through a single rule:

The first on-chain occurrence of a <username, platform_id> pair with the initial validity state 02 01 is the canonical identity for that name.

Practically, this means:

If a legitimate user registers @alice on platform 09 and later an attacker attempts to register the same name out of band, the attacker's transaction mints a second token also starting at 02 01. Validators recognise the earlier transaction as the canonical one and ignore the duplicate.
If an attacker registers a name before the intended user, they hold the canonical slot. The intended user would need to choose a different name — this is ordinary first-come-first-served and imposes no special risk beyond that of any blockchain naming system.
The cost of squatting every plausible name is X per name with no return, since unused tokens carry no value and accumulate dispute vulnerability.

No application-level enforcement is needed to uphold this rule. Any compliant validator that performs the blockchain lookup described in steps 1–4 above and selects the earliest occurrence will automatically identify the canonical holder.

5. BQUser CashToken Generation

CashToken Generation Process:

The BQUserGeneration contract holds the BQUser minting token and is the sole authority for issuing new BQUser CashTokens. Any candidate may register a new BQUser CashToken by submitting a request to the BQUserGeneration smart contract.

Steps for CashToken Generation:

Let X be the base fee set at contract deployment (e.g. 0.01 BCH at initial launch).

Registration Submission: A candidate submits a request to the BQUserGeneration smart contract, providing:
- Desired username
- Destination wallet address
- Registration fee of at least X
Smart Contract Execution:
- The smart contract validates the username and wallet address.
- The smart contract generates a new CashToken commitment for the candidate.
- The smart contract mints a new BQUser CashToken and sends it to the destination wallet address.
Transaction Confirmation: Once the transaction is confirmed on the blockchain, the candidate becomes a registered BQuest user.

Two-step registration — BQRepute minting:

After the BQUser NFT is confirmed, the holder submits a second chained transaction to the BQRepute minting contract:

Input: The holder's BQUser NFT (presented as proof of valid identity).
Output: BQUser NFT returned to the same address, unchanged.
Output: BQRepute NFT minted and sent to the same address.

The BQRepute contract reads the BQUser commitment to extract the username and platform, and embeds the current block height as the BQUser block genesis anchor (bquserBlock). After this step, the BQUser NFT is not required as input to any further contract interaction. All subsequent BQuest contract calls (lottery, future protocols) use the BQRepute NFT.

6. Naming Disputes

The BQUserDispute contract holds the BQUser minting token and is the sole authority for updating validity fields on existing BQUser CashTokens.

X refers to the base fee defined in section 5.

A registered user may dispute the legitimacy of another user by interacting with the BQUserDispute smart contract. By specifying the target username and paying a fee of 2X, they increment the targeted user's Negative Validity by one.

The targeted user may restore their standing by interacting with the BQUserDispute smart contract and paying an escalating fee to increment their Positive Validity by one. The first defense costs 2X; each successive round of defense costs an additional 2X more than the last (i.e. 2X, 4X, 6X, …). A user's identity is considered valid when their Positive Validity exceeds their Negative Validity.

This structure means a determined attacker must keep paying 2X per dispute round, while the defender's costs grow. Spurious claimants also risk having their own accounts targeted in turn.

Note: Funds sent to a disputed address are not blocked or sanctioned by the protocol in any way. Senders bear full responsibility for verifying identity claims before transferring funds.

7. Name Recovery

If a user loses access to the wallet holding their BQUser identity token, the dispute mechanism provides a formal path to invalidate the lost identity.

A user who holds any valid BQUser identity may target their own lost username through the Dispute / Recover feature. By raising a dispute against the inaccessible identity with a stated reason of Name Recovery, the user signals to validators that the original holder no longer controls the claimed moniker. Once Negative Validity reaches or exceeds Positive Validity, validators treat the identity as invalid.

Recovery steps:

Register a new BQUser identity from your current wallet (if you do not already hold one).
Open the Dispute / Recover panel and enter the lost username as the target.
State Name Recovery as your reason, including a brief explanation.
Pay the dispute fee to increment the lost identity's Negative Validity by one.
Repeat if further dispute rounds are needed until Negative Validity ≥ Positive Validity.

Why does recovery cost BCH?

The fee requirement exists to protect system integrity. A zero-cost recovery path would allow any party to forcibly invalidate any identity at will. By making each dispute step economically meaningful, the protocol ensures that only genuinely motivated parties — those with a real stake in a name — will pursue it.

Note: This process does not restore control of the original token or its wallet address. It permanently records on-chain that the identity is disputed. The original name may subsequently be re-registered by any party, with the new registration becoming the canonical identity from its block height forward.

8. BQRepute Token

Overview

The BQRepute token is a companion credential minted alongside every BQUser identity. It serves as the token presented to BQuest smart contracts (lottery, future protocol functions), keeping the BQUser NFT permanently untouched after registration and preserving the first-seen canonical rule without relying on BQUser UTXO age.

BQRepute carries no independent validity state — the BQUser token remains the sole authority on identity validity (positive vs. negative validity). Contracts that require a validity check must accept both tokens.

Commitment Format

<nameLen:1><nameHex:var><platform:1><bquserBlock:4 LE>
<gamesWon:2 LE><totalSatsWon:4 LE>
<timesSent:2 LE><onboarded:2 LE><played:2 LE>

Field	Size	Description
nameLen	1 byte	Decimal length of the username (4–15)
nameHex	4–15 bytes	Username as ASCII hex (matches BQUser)
platform	1 byte	Platform ID (matches BQUser)
bquserBlock	4 bytes LE	Block height at which the BQUser was registered — the canonical genesis anchor
gamesWon	2 bytes LE	Cumulative lottery or game wins
totalSatsWon	4 bytes LE	Cumulative satoshis won (max ≈ 42.9 BCH)
timesSent	2 bytes LE	Cumulative BCH send operations via BQuest
onboarded	2 bytes LE	Users onboarded/referred by this identity (social onboarding feature)
played	2 bytes LE	Reserved for future game mechanic; always 0 until a contract path is defined

Maximum commitment size: 1 + 15 + 1 + 4 + 2 + 4 + 2 + 2 + 2 = 33 bytes (within the 40-byte BCH NFT commitment limit, with 7 bytes reserved for future fields).

All multi-byte fields are unsigned little-endian integers, consistent with BCH CashScript integer conventions.

Canonical Disambiguation

When multiple BQRepute tokens exist for the same username (due to duplicate BQUser registrations), the canonical holder is identified by the lowest bquserBlock value. This reflects the actual block height at which the corresponding BQUser was first registered, baked in at BQRepute minting time and preserved through all subsequent burn/remint cycles.

This enables O(1) canonical resolution: query current BQRepute UTXOs for a username, compare bquserBlock fields, take the lowest. No historical UTXO traversal required.

Credential Bytes

For operations that depend on a stable per-user identity (such as the Validity Draw win condition), the credential bytes are the fixed-identity portion of the commitment:

credentialBytes = nameLen(1) ++ nameHex(var) ++ platform(1) ++ bquserBlock(4)

These bytes are immutable across all burn/remint cycles — only the reputation fields that follow them are ever updated.

Burn / Remint Cycle

When a BQRepute holder interacts with a BQuest contract:

The existing BQRepute token is consumed as a transaction input (burnt).
A new BQRepute token is minted with the same credentialBytes but updated reputation fields.
The new token is sent to the same address as the input.

The credential bytes (nameLen, nameHex, platform, bquserBlock) are never modified after initial minting. Only gamesWon, totalSatsWon, timesSent, onboarded, and played change.

Soul-Bound Convention

BQRepute is intended to remain with the wallet that holds the corresponding BQUser token. Transferring BQRepute to a different address is not prevented at the protocol level but is strongly discouraged. Validators and applications should flag a mismatch between the BQRepute holder address and the BQUser holder address for the same username as a non-canonical or suspect identity.

BQUser Identity Protocol