HackMD
  • Power Up!
    Power Up!  Browser extension
    Instantly search and open your HackMD note from your browser.
    Learn more Got it
    • Create new note
    • Create a note from template
  • Power Up!  Browser extension
    Power Up!  Browser extension
    Instantly search and open your HackMD note from your browser.
    Learn more Got it
    • Options
    • Versions
    • Transfer ownership
    • Delete this note
    • Template
    • Save as template
    • Insert from template
    • Export
    • Dropbox
    • Google Drive
    • Gist
    • Import
    • Dropbox
    • Google Drive
    • Gist
    • Clipboard
    • Download
    • Markdown
    • HTML
    • Raw HTML
    • ODF (Beta)
    • Sharing Link copied
    • /edit
    • View mode
      • Edit mode
      • View mode
      • Book mode
      • Slide mode
      Edit mode View mode Book mode Slide mode
    • Note Permission
    • Read
      Owners
      • Owners
      • Signed-in users
      • Everyone
      Owners Signed-in users Everyone
    • Write
      Owners
      • Owners
      • Signed-in users
      • Everyone
      Owners Signed-in users Everyone
    • More (Comment, Invitee)
    • Publishing

      After the note is published, everyone on the web can find and read this note.
      See all published notes on profile page.

    • More (Comment, Invitee)
    • Commenting Enable
      Disabled Forbidden Owners Signed-in users Everyone
    • Permission
      Owners
      • Forbidden
      • Owners
      • Signed-in users
      • Everyone
    • Invitee
    • No invitee
Menu Sharing Create Help
Create Create new note Create a note from template
Menu
Options
Versions Transfer ownership Delete this note
Export
Dropbox Google Drive Gist
Import
Dropbox Google Drive Gist Clipboard
Download
Markdown HTML Raw HTML ODF (Beta)
Back
Sharing
Sharing Link copied
/edit
View mode
  • Edit mode
  • View mode
  • Book mode
  • Slide mode
Edit mode View mode Book mode Slide mode
Note Permission
Read
Owners
  • Owners
  • Signed-in users
  • Everyone
Owners Signed-in users Everyone
Write
Owners
  • Owners
  • Signed-in users
  • Everyone
Owners Signed-in users Everyone
More (Comment, Invitee)
Publishing

After the note is published, everyone on the web can find and read this note.
See all published notes on profile page.

More (Comment, Invitee)
Commenting Enable
Disabled Forbidden Owners Signed-in users Everyone
Permission
Owners
  • Forbidden
  • Owners
  • Signed-in users
  • Everyone
Invitee
No invitee
   Published      
   owned this note    owned this note
   Linked with GitHub
  • Watch - Be notified of any changes
  • Never - Never be notified
# 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.

Import from clipboard

Editing is for members only

With current role, you can only comment.
Learn how

This team is disabled

Sorry, this team is disabled. You can't edit this note.

This note is locked

Sorry, only owner can edit this note.

Reach the limit

Sorry, you've reached the max length this note can be.
Please reduce the content or divide it to more notes, thank you!

Import from Gist

Import from Snippet

or

Export to Snippet

Are you sure?

Do you really want to delete this note?
All users will lost their connection.

Transfer ownership

    or

      Create a note from template

      Create a note from template

      Oops...
      This template is not available.
      All
      • All
      • Team
      No template found.

      Create a template

      Delete template

      Do you really want to delete this template?

      This page need refresh

      You have an incompatible client version.
      Refresh to update.
      New version available!
      See releases notes here
      Refresh to enjoy new features.
      Your user state has changed.
      Refresh to load new user state.
      Buy us coffee

      Sign in

      Forgot password

      or

      By clicking below, you agree to our terms of service.

      Sign in via Facebook Sign in via Twitter Sign in via GitHub Sign in via Dropbox Sign in via Google

      New to HackMD? Sign up

      Help

      Contacts

      Talk to us
      Report an issue
      Send us email
      Buy us coffee

      Documents

      Features
      YAML Metadata
      Slide Example
      Book Example

      Cheatsheet

      Example
      Header # Header
      • Unordered List
      - Unordered List
      1. Ordered List
      1. Ordered List
      • Todo List
      - [ ] Todo List
      Blockquote
      > Blockquote
      Bold font **Bold font**
      Italics font *Italics font*
      Strikethrough ~~Strikethrough~~
      19th 19^th^
      H2O H~2~O
      Inserted text ++Inserted text++
      Marked text ==Marked text==
      Link [link text](https:// "title")
      Image ![image alt](https:// "title")
      Code `Code`
      var i = 0;
      ```javascript
      var i = 0;
      ```
      :smile: :smile:
      Externals {%youtube youtube_id %}
      LaTeX $L^aT_eX$

      This is a alert area.

      :::info
      This is a alert area.
      :::

      Versions

      Versions

      Sign in to link this note to GitHub Learn more
      This note is not linked with GitHub Learn more
       

      Version named by    

      More Less
      • Edit
      • Delete

      Note content is identical to the latest version.
      Compare with
        Choose a version
        No search result
        Version not found

      Feedback

      Submission failed, please try again

      Thanks for your support.

      On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?

      Please give us some advice and help us improve HackMD.

       

      Thanks for your feedback

      Remove version name

      Do you want to remove this version name and description?

      Link with GitHub

      Please authorize HackMD on GitHub

      Please sign in to GitHub and install the HackMD app on your GitHub repo. Learn more

       Sign in to GitHub

      HackMD links with GitHub through a GitHub App. You can choose which repo to install our App.

      Push the note to GitHub Push to GitHub Pull a file from GitHub

       Authorize again
       

      Choose which file to push to

      Select repo
      Refresh Authorize more repos
      Select branch
      Select file
      Select branch
      Choose version(s) to push
      • Save a new version and push
      • Choose from existing versions

      Pull from GitHub

       
      File from GitHub
      File from HackMD

      GitHub Link Settings

      File linked

      Linked by
      File path
      Last synced branch

      Danger Zone

      Unlink
      You will no longer receive notification when GitHub file changes after unlink.

      Syncing

      Push failed

      Push successfully