Skip to content

README contradicts wallets-v2.schema.json on three required fields #246

@ArkadiyStena

Description

@ArkadiyStena

The README's "Description" section in README.md describes three fields in a way that disagrees with wallets-v2.schema.json. Two of the three also disagree with the data already in wallets-v2.json. Implementers reading the README and implementers running schema validation get different answers.

Counts below are against wallets-v2.json at HEAD (34 entries total, 29 list an sse bridge).

1. universal_url — README claims "strictly required for sse bridges"

  • README:

    universal_url: (strictly required for sse bridges, optional otherwise)

  • Schema: universal_url is not in the top-level required array, and the schema has no if/then clause keying it on bridge[].type == "sse". Validation accepts an entry that lists an sse bridge but omits universal_url.
  • Practice: 0 / 29 sse entries currently violate the README claim. The mismatch is theoretical today, but the schema does not protect future PRs.

2. deepLink — README claims "strictly required for sse bridges"

  • README:

    deepLink: (strictly required for sse bridges, optional otherwise)

  • Schema: deepLink is not in required. No conditional. Validation accepts sse entries without it.
  • Practice: 16 / 29 sse entries (55%) omit deepLink, including telegram-wallet, tonhub, okxWallet, okxTonWallet, hot, dewallet, GateWallet, BitgetWeb3, bitgetWalletLite, tomoWallet, miraiapp-tg, Architec.ton, tokenpocket, uxuyWallet, koloWeb3Wallet, sparx. Either the README is wrong or these entries are non-conformant.

3. extraCurrencySupported — README claims "optional, false by default"

  • README:

    extraCurrencySupported: (optional, false by default) whether wallet supports extra currencies

  • Schema: extraCurrencySupported is listed in required for the SendTransaction feature shape:
    "required": ["name", "maxMessages", "extraCurrencySupported"]
    A SendTransaction feature object that omits the field fails schema validation. There is no default in the schema.
  • Practice: every SendTransaction entry in wallets-v2.json sets the field explicitly, so a PR that follows the README's "optional" wording and omits it will be rejected on CI.

Suggested resolution

Pick one source of truth per field, then make the other match. A few options:

  • Tighten the schema to match the README. For (1) and (2), add if: { properties: { bridge: { contains: { properties: { type: { const: "sse" } } } } } }, then: { required: ["universal_url", "deepLink"] }. For (3), keep schema as-is and update the README.
    • Caveat: this option breaks 16 existing entries for deepLink until they are amended.
  • Loosen the README to match the schema. Reword deepLink and universal_url as "SHOULD be provided when an sse bridge is listed" rather than "strictly required", and reword extraCurrencySupported as required with no default.

Either direction is fine; the current state has wallet developers reading two different specs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions