# Fungibles
Module to act as single entry point to fungible tokens supported by a chain.

This module only handles asset balance querying and, if available, transfer; it *does not* act as a registry for discovery purposes (that may be handled in a separate module).

This is created for two actors:
- Wallets & other external RPC-based agents, to be able to query and list all fungible assets on any compatible chain.
- Inter-chain asset transfers; specifically for chains to be able to query and transfer assets between them.

Realistically, the second use-case will eventually be fulfilled by a fungibles SPREE module, therefore the greatest amount of effort will be spent ensuring the design requirements of the first.

## Identifying and utilising a fungible asset on Polkadot

Polkadot will have many chains. Each chain may have 0, 1 or many fungibles. Assets may be hosted by one or more modules, for example the Balances module is able to host a single fungible token whereas the `assets` module can manage multiple. Chains may also be nested, or otherwise host multiple distinct sets of fungibles.

We can imagine a simple URI-like format to allow a wallet to be able to identify and index any given asset on Polkadot:

`polkadot://<Chain index or address>/<API or module ID>/<Asset index or ID>`

For example:
- Polkadot DOT token: `polkadot:///balances`
- Polkadot single-instance of Balances module on parachain 1: `polkadot://1/balances`
- Polkadot multi-instanced index 3 of Balances module on parachain 2: `polkadot://2/balances[3]`
- Assuming parachain 3 is a bridge hub, then the asset 5 in the `assets` module of bridge index 4 of that hub: `polkadot://3.4/assets/5`
- Assuming parachain 4 is a smart contract chain, then the erc20 asset at address `0xabcdef`: `polkadot://4/erc20/0xabcdef`

(A name resolution chain is likely to exist on Polkadot in order to obviate the need for numeric indices, but that's beyond the scope here.)

In case a chain writes its own module for managing balances, then there needs to be some abstract (and standard) API that is fulfilled and which wallets can rely on. While we can rely on the module name, instance and/or indexing and to ensure a single asset may be identified, there is the practical matter of actually interacting with a module whose API, though introspectable, is unfamiliar. Wallets, and in particular *light-client* wallets, need some way of "understanding" how to use the module in order to deliver at least two pieces of practical functionality:
- How to inspect storage to determine the balance of a particular account.
- How to construct a transaction that transfers some balance to a different account.

For the latter we will, for now, assume that the transfer is to an account on the same chain. An associate SPREE module will likely handle standards for interchain transfer.

Finally, we would also want to expose some meta-API, particularly the capabilities and version information.

The fact that this must fully support light-clients means that we cannot use Substrate's runtime APIs and expect it to work (at least not on day 1). Rather, we must work only with events, storage and transactions. One major advantage is that we can assume the existence of the metadata API, which allows us to query constant values, extrinsic/transaction formats and storage item formats. This dramatically reduces the amount of low-level information that needs to be provided when defining a module's API.

## Specifying transaction construction formats

Transaction construction formats, at least initially, are likely to be clones of the APIs provided by the Assets and Balances module. As such, it makes sense to simply ratify these APIs by naming portions of them as *capabilities* that may be advertised. Versioning allows us update these APIs, and we can also add entirely new ones should it be needed.

These APIs, expressed as strings, may be placed, and thus inspected by wallets, in the module's metadata. In principle, two APIs can be defined (we'll use JSON here), though these may end up just being standard formats obviating the need for any explicit definition in the module itself:

- "balances": `{ call: 'transfer', args=[ { contents: DESTINATION }, { contents: VALUE } ]`
- "assets": `{ call: 'transfer', args=[ { contents: ID }, { contents: DESTINATION }, { contents: VALUE } ] }`

Importantly, `DESTINATION`, `ID` and `VALUE` are all placeholder values. Their datatypes (and thus encoding format can be derived from the metadata of the chain in question). Thus the wallet is capable of filling them with appropriate values (i.e. from its own interface). If, practically speaking, chain metadata isn't enough to allow wallets to accurately deliver these values, then additional fields may be added alongside `contents` to facilitate matters.

## Specifying storage formats

While transaction formats are relatively simple, storage of balance data tends to be more complex in practical situations, handling complexities such as reserved and free balances, locks and vesting schedules.

While it may be an interesting possibility to design a JSON-based format that can adequately and abstractly express all of these minutiae, it is unneeded for an initial implementation. Rather, we can simply define three possible storage-level APIs supported by the module:

- "balances": Conforms to the standard Substrate Balances module's storage format.
- "assets": Conforms to the standard Substrate Assets module's storage format.
- "custom": Conforms to a custom format as defined by a string, found in the module's metadata.

The format of the string in the case of `"custom"` would likely take the form of a list specifying each of several items of storage and how to combine them into a single value. E.g.:
- Assuming one single storage item, mapping `AccountId` to `Balance`, then the format specification would be quite trivial: `{ total: [ { item: "Balances", key: ACCOUNT } ] }`.
- Supposing that the map was instead from `AccountId` to `(FreeBalance, ReservedBalance)`, then we might specify the format:

{
  total: [ {
    item: "Balances",
    key: ACCOUNT,
    tuple: 0
  }, {
    item: "Balances",
    key: ACCOUNT,
    tuple: 1,
  } ],
  spendable: [ {
    item: "Balances",
    key: ACCOUNT,
    tuple: 0
  } ]`
}

- Different operations may be used to combine things, for example suppose the mapping is to `(TotalBalance, SpendableBalance)`, then we might specify the format:

{
  total: [ {
    item: "Balances",
    key: ACCOUNT,
    tuple: 0
  } ],
  spendable: [ {
    item: "Balances",
    key: ACCOUNT,
    tuple: 0
  }, {
    item: "Balances",
    key: ACCOUNT,
    tuple: 1,
    combine: MINUS,
  } ]`
}

## WebAssembly

A later version of this spec may allow for WebAssembly components to be added into metadata to provide a much richer possibility to inspect and combine storage. Such an API would need to be lightweight (to avoid bloating the runtime), isolatable (to avoid introducing security issues into the runtime) and manage with the fact the all APIs available to light-clients (and thus also to this Wasm blob) for inspecting storage are fully asynchronous.