Closes https://github.com/paritytech/polkadot-sdk-docs/issues/70
WIP PR for an overview of how to develop tokens in FRAME.
- [x] Tokens in Substrate Ref Doc
- High-level overview of the token-related logic in FRAME
- Improve docs with better explanation of how holds, freezes, ed, free
balance, etc, all work
- [x] Update `pallet_balances` docs
- Clearly mark what is deprecated (currency)
- [x] Write fungible trait docs
- [x] Evaluate and if required update `pallet_assets`, `pallet_uniques`,
`pallet_nfts` docs
- [x] Absorb https://github.com/paritytech/polkadot-sdk/pull/2683/
- [x] Audit individual trait method docs, and improve if possible
Feel free to suggest additional TODOs for this PR in the comments
---------
Co-authored-by: Bill Laboon <laboon@users.noreply.github.com>
Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com>
Co-authored-by: Kian Paimani <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Sebastian Kunert <skunert49@gmail.com>
**Update:** Pushed additional changes based on the review comments.
**This pull request fixes various spelling mistakes in this
repository.**
Most of the changes are contained in the first **3** commits:
- `Fix spelling mistakes in comments and docs`
- `Fix spelling mistakes in test names`
- `Fix spelling mistakes in error messages, panic messages, logs and
tracing`
Other source code spelling mistakes are separated into individual
commits for easier reviewing:
- `Fix the spelling of 'authority'`
- `Fix the spelling of 'REASONABLE_HEADERS_IN_JUSTIFICATION_ANCESTRY'`
- `Fix the spelling of 'prev_enqueud_messages'`
- `Fix the spelling of 'endpoint'`
- `Fix the spelling of 'children'`
- `Fix the spelling of 'PenpalSiblingSovereignAccount'`
- `Fix the spelling of 'PenpalSudoAccount'`
- `Fix the spelling of 'insufficient'`
- `Fix the spelling of 'PalletXcmExtrinsicsBenchmark'`
- `Fix the spelling of 'subtracted'`
- `Fix the spelling of 'CandidatePendingAvailability'`
- `Fix the spelling of 'exclusive'`
- `Fix the spelling of 'until'`
- `Fix the spelling of 'discriminator'`
- `Fix the spelling of 'nonexistent'`
- `Fix the spelling of 'subsystem'`
- `Fix the spelling of 'indices'`
- `Fix the spelling of 'committed'`
- `Fix the spelling of 'topology'`
- `Fix the spelling of 'response'`
- `Fix the spelling of 'beneficiary'`
- `Fix the spelling of 'formatted'`
- `Fix the spelling of 'UNKNOWN_PROOF_REQUEST'`
- `Fix the spelling of 'succeeded'`
- `Fix the spelling of 'reopened'`
- `Fix the spelling of 'proposer'`
- `Fix the spelling of 'InstantiationNonce'`
- `Fix the spelling of 'depositor'`
- `Fix the spelling of 'expiration'`
- `Fix the spelling of 'phantom'`
- `Fix the spelling of 'AggregatedKeyValue'`
- `Fix the spelling of 'randomness'`
- `Fix the spelling of 'defendant'`
- `Fix the spelling of 'AquaticMammal'`
- `Fix the spelling of 'transactions'`
- `Fix the spelling of 'PassingTracingSubscriber'`
- `Fix the spelling of 'TxSignaturePayload'`
- `Fix the spelling of 'versioning'`
- `Fix the spelling of 'descendant'`
- `Fix the spelling of 'overridden'`
- `Fix the spelling of 'network'`
Let me know if this structure is adequate.
**Note:** The usage of the words `Merkle`, `Merkelize`, `Merklization`,
`Merkelization`, `Merkleization`, is somewhat inconsistent but I left it
as it is.
~~**Note:** In some places the term `Receival` is used to refer to
message reception, IMO `Reception` is the correct word here, but I left
it as it is.~~
~~**Note:** In some places the term `Overlayed` is used instead of the
more acceptable version `Overlaid` but I also left it as it is.~~
~~**Note:** In some places the term `Applyable` is used instead of the
correct version `Applicable` but I also left it as it is.~~
**Note:** Some usage of British vs American english e.g. `judgement` vs
`judgment`, `initialise` vs `initialize`, `optimise` vs `optimize` etc.
are both present in different places, but I suppose that's
understandable given the number of contributors.
~~**Note:** There is a spelling mistake in `.github/CODEOWNERS` but it
triggers errors in CI when I make changes to it, so I left it as it
is.~~
# Note for reviewer
Most changes are just syntax changes necessary for the new version.
Most important files should be the ones under the `xcm` folder.
# Description
Added XCMv4.
## Removed `Multi` prefix
The following types have been renamed:
- MultiLocation -> Location
- MultiAsset -> Asset
- MultiAssets -> Assets
- InteriorMultiLocation -> InteriorLocation
- MultiAssetFilter -> AssetFilter
- VersionedMultiAsset -> VersionedAsset
- WildMultiAsset -> WildAsset
- VersionedMultiLocation -> VersionedLocation
In order to fix a name conflict, the `Assets` in `xcm-executor` were
renamed to `HoldingAssets`, as they represent assets in holding.
## Removed `Abstract` asset id
It was not being used anywhere and this simplifies the code.
Now assets are just constructed as follows:
```rust
let asset: Asset = (AssetId(Location::new(1, Here)), 100u128).into();
```
No need for specifying `Concrete` anymore.
## Outcome is now a named fields struct
Instead of
```rust
pub enum Outcome {
Complete(Weight),
Incomplete(Weight, Error),
Error(Error),
}
```
we now have
```rust
pub enum Outcome {
Complete { used: Weight },
Incomplete { used: Weight, error: Error },
Error { error: Error },
}
```
## Added Reanchorable trait
Now both locations and assets implement this trait, making it easier to
reanchor both.
## New syntax for building locations and junctions
Now junctions are built using the following methods:
```rust
let location = Location {
parents: 1,
interior: [Parachain(1000), PalletInstance(50), GeneralIndex(1984)].into()
};
```
or
```rust
let location = Location::new(1, [Parachain(1000), PalletInstance(50), GeneralIndex(1984)]);
```
And they are matched like so:
```rust
match location.unpack() {
(1, [Parachain(id)]) => ...
(0, Here) => ...,
(1, [_]) => ...,
}
```
This syntax is mandatory in v4, and has been also implemented for v2 and
v3 for easier migration.
This was needed to make all sizes smaller.
# TODO
- [x] Scaffold v4
- [x] Port github.com/paritytech/polkadot/pull/7236
- [x] Remove `Multi` prefix
- [x] Remove `Abstract` asset id
---------
Co-authored-by: command-bot <>
Co-authored-by: Keith Yeung <kungfukeith11@gmail.com>
# Motivation (+testing)
### Enable easy `ForeignAssets` transfers using `pallet-xcm`
We had just previously added capabilities to teleport fees during
reserve-based transfers, but what about reserve-transferring fees when
needing to teleport some non-fee asset?
This PR aligns everything under either explicit reserve-transfer,
explicit teleport, or this new flexible `transfer_assets()` which can
mix and match as needed with fewer artificial constraints imposed to the
user.
This will enable, for example, a (non-system) parachain to teleport
their `ForeignAssets` assets to AssetHub while using DOT to pay fees.
(the assets are teleported - as foreign assets should from their owner
chain - while DOT used for fees can only be reserve-based transferred
between said parachain and AssetHub).
Added `xcm-emulator` tests for this scenario ^.
# Description
Reverts `(limited_)reserve_transfer_assets` to only allow reserve-based
transfers for all `assets` including fees.
Similarly `(limited_)teleport_assets` only allows teleports for all
`assets` including fees.
For complex combinations of asset transfers where assets and fees may
have different reserves or different reserve/teleport trust
configurations, users can use the newly added `transfer_assets()`
extrinsic which is more flexible in allowing more complex scenarios.
`assets` (excluding `fees`) must have same reserve location or otherwise
be teleportable to `dest`.
No limitations imposed on `fees`.
- for local reserve: transfer assets to sovereign account of destination
chain and forward a notification XCM to `dest` to mint and deposit
reserve-based assets to `beneficiary`.
- for destination reserve: burn local assets and forward a notification
to `dest` chain to withdraw the reserve assets from this chain's
sovereign account and deposit them to `beneficiary`.
- for remote reserve: burn local assets, forward XCM to reserve chain to
move reserves from this chain's SA to `dest` chain's SA, and forward
another XCM to `dest` to mint and deposit reserve-based assets to
`beneficiary`.
- for teleports: burn local assets and forward XCM to `dest` chain to
mint/teleport assets and deposit them to `beneficiary`.
## Review notes
Only around 500 lines are prod code (see `pallet_xcm/src/lib.rs`), the
rest of the PR is new tests and improving existing tests.
---------
Co-authored-by: command-bot <>
* Remove the `Copy` bound on `AssetId`
* Also relax the `Copy` bound in the assets pallet
* Fix warnings on the newest nightly Rust
* Remove some unnecessary `clone()`s
* Try to satisfy clippy
* Remove some more unnecessary `clone()`s
* Add more `.clone()`s for newly merged code
* Also add `clone()`s in the benchmarks
---------
Co-authored-by: parity-processbot <>
* frame: Default for GenesisConfig in no_std
`Default` for `GenesisConfig` will be required for no_std in no native
runtime world. It must be possible to instantiate default GenesisConfig
for pallets and runtime.
* ".git/.scripts/commands/fmt/fmt.sh"
* hash69 in no_std reverted
* derive(DefaultNoBound) for GenesisConfig used when possible
* treasury: derive(Default)
* Cargo.lock update
* genesis_config: compiler error improved
When std feature is not enabled for pallet, the GenesisConfig will be
defined, but serde::{Serialize,Deserialize} traits will not be
implemented.
The compiler error indicates the reason of latter errors.
This is temporary and serde traits will be enabled with together with
`serde` support in frame.
---------
Co-authored-by: command-bot <>
* Remove use of trait Store from staking pallet
* Remove use of trait Store from bounties pallet
* Remove use of trait Store from collective pallet
* Remove use of trait Store from babe pallet
* Remove use of trait Store from assets pallet
* Remove use of trait Store from grandpa pallet
* Remove use of trait Store from balances pallet
* Remove use of trait Store from authorship pallet
* Remove use of trait Store from authority-discovery pallet
* Remove use of trait Store from atomic-swap pallet
* Remove use of trait Store from sudo pallet
* Remove use of trait Store from scheduler pallet
* Remove use of trait Store from scored-pool pallet
* Remove use of trait Store from society pallet
* Remove use of trait Store from lottery pallet
* Remove use of trait Store from executive pallet
* Remove use of trait Store from democracy pallet
* Remove use of trait Store from elections-phragmen pallet
* Remove use of trait Store from indices pallet
* Remove use of trait Store from identity pallet
* Remove use of trait Store from multisig pallet
* Remove use of trait Store from merkle-mountain-range pallet
* Remove use of trait Store from im-online pallet
* Remove use of trait Store from membership pallet
* Remove use of trait Store from nicks pallet
* Remove use of trait Store from session pallet
* Remove use of trait Store from transaction-payment pallet
* Remove use of trait Store from utility pallet
* Remove use of trait Store from child-bounties pallet
* Remove use of trait Store from nis pallet
* Remove use of trait Store from nfts pallet
* Remove use of trait Store from conviction-voting pallet
* Remove use of trait Store from treasury pallet
* Remove use of trait Store from vesting pallet
* Remove use of trait Store from preimage pallet
* Remove use of trait Store from uniques pallet
* Remove use of trait Store from ranked-collective pallet
* Remove use of trait Store from beefy-mmr pallet
* Remove use of trait Store from referenda pallet
* Remove use of trait Store from whitelist pallet
* Remove use of trait Store from alliance pallet
* Remove use of trait Store from nomination-pools pallet
* Remove use of trait Store from state-trie-migration pallet
* Remove use of trait Store from message-queue pallet
* Remove use of trait Store from root-offences pallet
* Remove use of trait Store from root-testing pallet
* Remove use of trait Store from timestamps pallet
* Remove use of trait Store from system pallet
* Remove use of trait Store from offences pallet
* Remove use of trait Store from recovery pallet
* Remove use of trait Store from node-authorization pallet
* Remove use of trait Store from proxy pallet
* Remove use of trait Store from benchmarking pallet
* Remove use of trait Store from bags-list pallet
* Add deprecated warning in store_trait
* Change warning message
* Run cargo fmt
* Fix warning and update tests
* Remove unnecessary allow deprecated
* Remove use of trait Store
* Fix mismatch in expected output
* Minor update to warning message for deprecation of generate_store with Store trait attribute
* Fixes as per review comments
* Fixes as per review suggestions
* Remove use of Store trait from core-fellowship pallet
* Fix type in store_trait.rs
* Fixes as pre review comment
* Change copyright year to 2023 from 2022
* Fix incorrect update of copyright year
* Remove years from copy right header
* Fix remaining files
* Fix typo in a header and remove update-copyright.sh
* pallet-assets: Rename `total_supply` to `amount`
We are actually passing the `amount` on assets being minted and not the total supply.
Closes: https://github.com/paritytech/substrate/issues/13210
* ".git/.scripts/commands/fmt/fmt.sh"
* Fix compilation
* FMT
Co-authored-by: command-bot <>
* Add CallbackHandle to pallet-assets
* Address review comments
* Add use for sp_io::storage
* Rebase & review comments
* Fix UT
Co-authored-by: Hoon Kim <mail@hoonkim.me>
* Fixup some wrong dependencies
Dev dependencies should not appear in the feature list. If features are required, they should be
directly enabled for the `dev-dependency`.
* More fixups
* Fix fix
* Remove deprecated feature
* Make all work properly and nice!!
* FMT
* Fix formatting
* frame-system: explicit call index
Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Use explicit call indices
Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* pallet-template: explicit call index
Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* DNM: Temporarily require call_index
Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Revert "DNM: Temporarily require call_index"
This reverts commit c4934e312e12af72ca05a8029d7da753a9c99346.
Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Remove Default, HasCompact, and TypeInfo trait bounds on AssetId
* don't use default in benchmarking
* add helper trait
* add helper to assets tx payment test
* docs fixes
* i'm confused
* aha, cargo
* move affected dispatchable calls into new indices
* Helper -> BenchmarkHelper
* benchmark use of helper
* actually, don't break every call interface
* use into on AssetIdParameter
* Remove From from AssetIdParameter and use it in BenchmarkHelper
* include from
Co-authored-by: parity-processbot <>
* Support repeated destroys to safely destroy large assets
* require freezing accounts before destroying
* support only deleting asset as final stage when there's no assets left
* pre: introduce the RemoveKeyLimit config parameter
* debug_ensure empty account in the right if block
* update to having separate max values for accounts and approvals
* add tests and use RemoveKeyLimit constant
* add useful comments to the extrinsics, and calculate returned weight
* add benchmarking for start_destroy and finish destroy
* push failing benchmark logic
* add benchmark tests for new functions
* update weights via local benchmarks
* remove extra weight file
* Update frame/assets/src/lib.rs
Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
* Update frame/assets/src/types.rs
Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
* Update frame/assets/src/lib.rs
Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
* effect some changes from codereview
* use NotFrozen error
* remove origin checks, as anyone can complete destruction after owner has begun the process; Add live check for other extrinsics
* fix comments about Origin behaviour
* add AssetStatus docs
* modularize logic to allow calling logic in on_idle and on_initialize hooks
* introduce simple migration for assets details
* reintroduce logging in the migrations
* move deposit_Event out of the mutate block
* Update frame/assets/src/functions.rs
Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com>
* Update frame/assets/src/migration.rs
Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com>
* move AssetNotLive checkout out of the mutate blocks
* rename RemoveKeysLimit to RemoveItemsLimit
* update docs
* fix event name in benchmark
* fix cargo fmt.
* fix lint in benchmarking
* Empty commit to trigger CI
* Update frame/assets/src/lib.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Update frame/assets/src/lib.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Update frame/assets/src/functions.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Update frame/assets/src/functions.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Update frame/assets/src/functions.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Update frame/assets/src/lib.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* Update frame/assets/src/functions.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* effect change suggested during code review
* move limit to a single location
* Update frame/assets/src/functions.rs
Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
* rename events
* fix weight typo, using rocksdb instead of T::DbWeight. Pending generating weights
* switch to using dead_account.len()
* rename event in the benchmarks
* empty to retrigger CI
* trigger CI to check cumulus dependency
* trigger CI for dependent cumulus
* Update frame/assets/src/migration.rs
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* move is-frozen to the assetStatus enum (#12547)
* add pre and post migration hooks
* update do_transfer logic to add new assert for more correct error messages
* trigger CI
* switch checking AssetStatus from checking Destroying state to checking live state
* fix error type in tests from Frozen to AssetNotLive
* trigger CI
* change ensure check for fn reducible_balance()
* change the error type to Error:<T,I>::IncorrectStatus to be clearer
* Trigger CI
Co-authored-by: joe petrowski <25483142+joepetrowski@users.noreply.github.com>
Co-authored-by: parity-processbot <>
Co-authored-by: Muharem Ismailov <ismailov.m.h@gmail.com>
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
* BREAKING: Rename Origin
* more renaming
* a bit more renaming
* fix
* more fixing
* fix in frame_support
* even more fixes
* fix
* small fix
* ...
* update .stderr
* docs
* update docs
* update docs
* docs
Liam Aharon