Xian Documentation

Appearance

XSC-0001: Fungible Token ​

XSC-0001 is the core fungible-token interface used across the Xian stack.

Required Surface ​

The standard token surface is:

python
@export
def change_metadata(key: str, value: Any):
    ...

@export
def transfer(amount: float, to: str):
    ...

@export
def approve(amount: float, to: str):
    ...

@export
def transfer_from(amount: float, to: str, main_account: str):
    ...

@export
def balance_of(address: str) -> float:
    ...

Expected Semantics ​

  • transfer moves balance from ctx.caller to to
  • approve sets an allowance for to
  • transfer_from spends from main_account using the caller's allowance
  • balance_of returns the current balance for an address

The current canonical implementation stores allowances in a dedicated approvals hash using a two-dimensional key:

python
approvals[owner, spender] = amount

Expected Events ​

The canonical token contract emits:

  • Transfer
  • Approve

Typical indexed fields are sender and recipient/spender so that CometBFT and dashboard subscribers can query them efficiently.

python
balances = Hash(default_value=0)
approvals = Hash(default_value=0)
metadata = Hash()
operator = Variable()

The current canonical implementation stores metadata edit authority in the separate operator variable instead of metadata["operator"].

Common metadata keys in the canonical token are:

  • token_name
  • token_symbol
  • token_logo_url
  • token_logo_svg
  • token_website
  • total_supply

Wallets should prefer token_logo_url when it is present and non-empty. If the URL field is empty, they should fall back to token_logo_svg and render the on-chain SVG directly.

Compatibility Notes ​

  • validate amount > 0 for transfers
  • approvals may be 0 and should overwrite prior allowance
  • emit events on successful transfer/approval paths
  • keep function names and argument names stable so tooling can introspect them