Skip to content

Rewrite token concept for allow-listing #3392

@mDuo13

Description

@mDuo13

Both MPTs and trust line tokens support allow-listing of token holders through a Require Auth flag (on the AccountRoot for trust line tokens or on the MPTIssuance for MPTs).

Currently we have the (very outdated, not following best practices) Authorized Trust Lines article for trust line tokens, and a single bullet point in the MPTs concept under Transferability Controls.

It would be good to rewrite these into a single shared article (or perhaps two articles in similar structure) with a title like "Allow-listing Token Holders" (maybe check with marketing and product on a more SEO-ready title) and sub-sections for MPTs and Trust Line Tokens, hopefully with comparable structure.

The concept article should not contain code snippets; the authorized trust lines one currently does and they're not representative of current best practices. That might need to be split off from the existing documentation, and better code samples for

Content that should be in the concept article might include:

  • Why you would use allow-listing (what use cases or situations call for it)
  • The expected flow for using allow-listing, from a high level. This section should use prose names like Can Transfer instead of exact flag names like lsfMPTCanTransfer (since there may be different prefixes for, like, transaction flags vs ledger state flags).
  • Configurable options (like domain-based allow-listing)
  • Limitations and detailed rules / edge cases of allow-listing. (For example, with authorized trust lines, you cannot de-authorize a trust line that already exists, but an authorized trust line can be automatically deleted if it has no balance, and it won't be authorized if it later gets re-created.) Or, note that unauthorized users can still send a cross-currency transaction that delivers an allow-listed token by spending a different asset they have and converting it through the DEX (so they never actually need to hold the allow-listed token) as long as the recipient is authorized.
  • Interactions with other features (what happens if a trust line is both authorized and frozen/locked?)
  • Links to relevant code samples, tutorials showing how to create and use an allow-list token, and reference documentation for the relevant settings/flags in their respective data structures (ledger entries, transaction types, and API methods).

As part of this task, update the reference documentation to link to the newly (re-)written docs where appropriate.

Metadata

Metadata

Assignees

No one assigned

    Labels

    content updatesUpdating, cleaning up, or rewriting existing content for better usability or new contextstokenizationRelating to fungible or non-fungible token functionality

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions