Skip to content

Commit

Permalink
Update minter-flow.md
Browse files Browse the repository at this point in the history
  • Loading branch information
EmelyanenkoK authored Dec 6, 2024
1 parent d3557eb commit f52889d
Showing 1 changed file with 28 additions and 18 deletions.
46 changes: 28 additions & 18 deletions docs/v3/documentation/infra/minter-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,23 +32,33 @@ This minting message has source `-1:00000000000000000000000000000000000000000000
The issue here is that the minting message contains extra currencies only and no TON coins. That means that even if _Minter_ is set as a fundamental smart contract (presented in `ConfigParam31`), a minting message will cause the aborted transaction: `compute_ph:(tr_phase_compute_skipped reason:cskip_no_gas)`.

## High-level minting flow
_Minter_ smart contract upon receiving a request for the creation of new extracurrencies or minting additional tokens for existing ones should:
1. Check that fee determined in `ConfigParam6` can be deducted from the request message
2.
1. for existing tokens: check authorization for minting (only the _owner_ can mint new ones)
2. for the creation of new currencies: check that id of the cryptocurrency is not occupied and store owner of the new currency
3. send message to config contract (such message should cause the addition to `ExtraCurrencyCollection` in `ConfigParam7`)
4. send message to `0:0000...0000` (which is guaranteed to bounce in the next or following blocks) with extra_currency id

Upon receiving message from `0:0000...0000`
1. read extra_currency id from the bounce message
2. if there are tokens with corresponding id on minter balance send them to this currency owner with `ok` message
3. otherwise send to currency owner `fail` message

## Issues to be resolved
1. Workaround with sending a message to `0:0000...0000` for postponement of request processing is quite dirty.
2. Cases, when minting failed, should be thought out. For now, it looks like the only possible situation is when a currency amount is 0 or such that the current balance plus a minted amount doesn't fit into `(VarUInteger 32)`
3. How to burn? At first glance, there are no ways.
4. Should minting fees be prohibitive? In other words, is it dangerous to have millions of extracurrencies (big config, potential DoS due to unbound number of dict operations on collation?)
One of possible high-level minting flows implemented [here](https://github.com/ton-blockchain/governance-contract/tree/50ed2ecacc9e3cff4c77cbcc69aa07b39f5c46a2) (check `*.tolk` files) is as following:

1. There is `ExtraCurrencyAuthorizationConfig`: it is config that contains information which contracts (addresses) has authorization to request minter to mint new extracurrencies. This config has the following scheme:
```tlb
_ (Hashmap 32 std_addr) = ExtraCurrencyAuthorizationConfig;
```
where key - `currency_id` and `std_addr` is _admin_ of this currency (can be in any workchain).
2. Minter accepts mint requests from _admins_, forwards request for mint to Config, Config updates `ConfigParam 7` and responses to Minter. Since extracurrencies would be minted to Minter only on next masterchain block, withdrawing extracurrencies to _admin_ should be delayed. It is done via _Echo_ smart-contract not in masterchain. When response from _Echo_ came to Minter it sends extracurrencies to _admin_. So the scheme is as follows `Admin -> Minter -> Config -> Minter -> Echo (in other workchain to wait until the next masterchain block) -> Minter -> Admin`.

Example of such flow: [minting 2'000'000'000 units of `currency_id=100`](https://testnet.tonviewer.com/transaction/20fe328c04b4896acecb6e96aaebfe6fef90dcc1441e27049302f29770904ef0)

:::danger
Each mint of new extracurrency or increasing supply of existing one requires change of ConfigParam 7, thus changing config and creation keyblock. Too frequent keyblocks slows down shards (each keyblock leads to rotation of validator groups) and lite-client sync. Thus contracts like swap.tolk should not be used in production. Instead schemes with reserves, that minimize minting events, need to be used.
:::


:::Info
Sending of extracurrency to blackhole has the following effect: extracurrency amount is burnt, but since ConfigParam 7 is not changed, on next block Minter will receive burnt amount on it's balance.
:::

## Bird-eye minting flow
How to mint your own extracurrency:
1. Ensure your network has Minter Contract and ConfigParam 2, ConfigParam 6 set.
2. Create Currency Admin contract that controls how extracurrency is minted.
3. Create proposal to validators to add your Currency Admin contract address to ExtraCurrencyAuthorizationConfig for some `currency_id`, and get it accepted.
4. Send `mint` request from Currency Admin contract to Minter. Wait till Minter send back extracurrency.




0 comments on commit f52889d

Please sign in to comment.