diff --git a/examples/.gitignore b/examples/.gitignore new file mode 100644 index 0000000..b7e28fc --- /dev/null +++ b/examples/.gitignore @@ -0,0 +1,16 @@ +# Generated by Cargo +# will have compiled files and executables +/target/ + +# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries +# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html +Cargo.lock + +# These are backup files generated by rustfmt +**/*.rs.bk + + +# Added by cargo + +/target +/Cargo.lock diff --git a/examples/Cargo.toml b/examples/Cargo.toml new file mode 100644 index 0000000..63137d0 --- /dev/null +++ b/examples/Cargo.toml @@ -0,0 +1,68 @@ +[package] +name = "xcm-examples" +version = "0.1.0" +edition = "2021" +authors = ["Xcm Team"] + + +[dependencies] +bounded-collections = { version = "0.1.5", default-features = false } +smallvec = "1.4.0" +codec = { package = "parity-scale-codec", version = "3.0.0", features = ["derive", "max-encoded-len"] } +scale-info = { version = "2.1.1", default-features = false, features = ["derive"] } +serde_json = { version = "1.0.85" } +hex = { version = "0.4" } +hex-literal = { version = "0.3.1" } +libsecp256k1 = { version = "0.7" } + +#Polkadot +polkadot-parachain = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +xcm = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +xcm-executor = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +xcm-builder = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +pallet-xcm = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +pallet-balances = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39"} +pallet-assets = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +pallet-uniques = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +pallet-nfts = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +polkadot-primitives = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +polkadot-runtime-parachains = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +kusama-runtime = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +kusama-runtime-constants = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +xcm-simulator = { git = "/~https://github.com/paritytech/polkadot", branch = "release-v0.9.39" } +# substrate +frame-support = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +frame-system = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-api = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-application-crypto = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-block-builder = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-core = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-inherents = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-io = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-runtime = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-session = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-std = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-version = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-keyring = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } + +cumulus-primitives-core = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-primitives-utility = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-primitives-timestamp = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-pallet-parachain-system = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-pallet-dmp-queue = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-pallet-xcmp-queue = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-pallet-xcm = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +parachain-info = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-primitives-parachain-inherent = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +cumulus-test-relay-sproof-builder = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } +statemine-runtime = { git = "/~https://github.com/paritytech/cumulus", branch = "polkadot-v0.9.39" } + +xcm-emulator = { git = "/~https://github.com/shaunxw/xcm-simulator", rev = "aa13dce47596e150806dfc3af99096dae6ffc65e" } + +[dev-dependencies] +env_logger = "0.9.0" +log = "0.4.17" +sp-io = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } +sp-trie = { git = "/~https://github.com/paritytech/substrate", branch = "polkadot-v0.9.39" } + + diff --git a/examples/LICENSE b/examples/LICENSE new file mode 100644 index 0000000..f288702 --- /dev/null +++ b/examples/LICENSE @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..b65cada --- /dev/null +++ b/examples/README.md @@ -0,0 +1,2 @@ +# xcm-examples +This repository shows the xcm examples for the xcm docs diff --git a/examples/rustfmt.toml b/examples/rustfmt.toml new file mode 100644 index 0000000..44d6c5a --- /dev/null +++ b/examples/rustfmt.toml @@ -0,0 +1,21 @@ +# Basic +hard_tabs = true +max_width = 100 +use_small_heuristics = "Max" +# Imports +imports_granularity = "Crate" +reorder_imports = true +# Consistency +newline_style = "Unix" +# Misc +chain_width = 80 +spaces_around_ranges = false +binop_separator = "Back" +reorder_impl_items = false +match_arm_leading_pipes = "Preserve" +match_arm_blocks = false +match_block_trailing_comma = true +trailing_comma = "Vertical" +trailing_semicolon = false +use_field_init_shorthand = true +edition = "2021" \ No newline at end of file diff --git a/examples/src/expects/mod.rs b/examples/src/expects/mod.rs new file mode 100644 index 0000000..976d9a5 --- /dev/null +++ b/examples/src/expects/mod.rs @@ -0,0 +1,238 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use bounded_collections::BoundedVec; + use codec::Encode; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + const AMOUNT: u128 = 10; + const QUERY_ID: u64 = 1234; + + /// Scenario: + /// Parachain wants to execute specific instructions on the relay chain that use assets in the holding register. + /// Before executing these instructions it want to check if the assets in the holding register are expected. + /// If the assets are not expected, it wants to be notified with an `ExpectationFalse` error. + /// It first sets an error handler that reports back an error using the `ReportError` instruction. + /// And adds a `ExpectAsset` instruction just before executing the specific instructions. + #[test] + fn expect_asset() { + MockNet::reset(); + ParaA::execute_with(|| { + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + // Set the instructions that are executed when ExpectAsset does not pass. + // In this case, reporting back an error to the Parachain. + SetErrorHandler(Xcm(vec![ReportError(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + })])), + ExpectAsset((Here, AMOUNT + 10).into()), + // Add Instructions that do something with assets in holding when ExpectAsset passes. + ]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // Check that QueryResponse message with ExpectationFalse error was received. + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::ExecutionResult(Some((3, XcmError::ExpectationFalse))), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }); + } + + /// Scenario: + /// Parachain wants to make sure that XcmContext contains the expected `origin` at a certain point during execution. + /// It sets the `ExpectOrigin` instruction to check for the expected `origin`. + /// If the origin is not as expected, the instruction errors, and the ErrorHandler reports back the corresponding error to the parachain. + #[test] + fn expect_origin() { + MockNet::reset(); + + ParaA::execute_with(|| { + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + // Set the instructions that are executed when ExpectOrigin does not pass. + // In this case, reporting back an error to the Parachain. + SetErrorHandler(Xcm(vec![ReportError(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + })])), + ClearOrigin, + // Checks if the XcmContext origin is `Parachain(1). + ExpectOrigin(Some(Parachain(1).into())), + ]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // Check that QueryResponse message with ExpectationFalse error was received. + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::ExecutionResult(Some((4, XcmError::ExpectationFalse))), + max_weight: Weight::from_all(0), + querier: None, + }])], + ); + }); + } + + /// Scenario: + /// Parachain wants to make sure that the relay chain has configured a specific pallet with a specific version. + /// It sets the `ExpectPallet` instruction to check for the expected pallet. + /// If the pallet is not as expected, the instruction errors, and the ErrorHandler reports back the corresponding error to the parachain. + #[test] + fn expect_pallet() { + MockNet::reset(); + + ParaA::execute_with(|| { + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + // Set the instructions that are executed when ExpectPallet does not pass. + // In this case, reporting back an error to the Parachain. + SetErrorHandler(Xcm(vec![ReportError(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + })])), + // Configured pallet has different `crate_major` so `VersionIncompatible` error is thrown. + ExpectPallet { + index: 1, + name: "Balances".into(), + module_name: "pallet_balances".into(), + crate_major: 3, + min_crate_minor: 0, + }, + // Could execute pallet specific instructions after the expect pallet succeeds. + ]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // Check that QueryResponse message with `VersionIncompatible` error was received. + // Can also be a different error based on the pallet mismatch (i.e. PalletNotFound, NameMismatch). + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::ExecutionResult(Some((3, XcmError::VersionIncompatible))), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }); + } + + /// Scenario: + /// Parachain wants to make sure that the `ErrorHandler` that it sets is only executed when a specific error is thrown. + /// It sets an `ExpectError` instruction in the `SetErrorHandler` to check for the specific error. + /// If a different Error is thrown, the `ErrorHandler` execution is halted. + /// + /// Asserts that the ExpectPallet instruction throws an `PalletNotFound` error instead of the expected `VersionIncompatible` error. + #[test] + fn expect_error() { + MockNet::reset(); + + ParaA::execute_with(|| { + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + // ReportError is only executed if the thrown error is the `VersionIncompatible` error. + SetErrorHandler(Xcm(vec![ + ExpectError(Some((1, XcmError::VersionIncompatible))), + ReportError(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + }), + ])), + // Pallet index is wrong, so throws `PalletNotFound` error. + ExpectPallet { + index: 100, + name: "Balances".into(), + module_name: "pallet_balances".into(), + crate_major: 4, + min_crate_minor: 0, + }, + ]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // Does not receive a message as the incorrect error was thrown during execution. + ParaA::execute_with(|| { + assert_eq!(parachain::MsgQueue::received_dmp(), vec![],); + }); + } + + /// Scenario: + /// Parachain wants to make sure that the `Transact` instruction succeeded as it does not throw an XcmError. + /// It sets an `ExpectTransactStatus` instruction to MaybeErrorCode::Success to check if the transact succeeded. + /// If the status was not succesful, the `ExpectTransactStatus` errors, + /// and the ErrorHandler will report the error back to the Parachain. + /// + /// Assert that `set_balance` execution fails as it requires the origin to be root, + /// and the origin_kind is `SovereignAccount`. + #[test] + fn expect_transact_status() { + MockNet::reset(); + // Runtime call dispatched by the Transact instruction. + // set_balance requires root origin. + let call = relay_chain::RuntimeCall::Balances(pallet_balances::Call::< + relay_chain::Runtime, + >::set_balance { + who: ALICE, + new_free: 100, + new_reserved: 0, + }); + + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + SetErrorHandler(Xcm(vec![ReportTransactStatus(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + })])), + Transact { + origin_kind: OriginKind::SovereignAccount, + require_weight_at_most: Weight::from_parts(INITIAL_BALANCE as u64, 1024 * 1024), + call: call.encode().into(), + }, + ExpectTransactStatus(MaybeErrorCode::Success), + ]); + + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // The execution of set_balance does not succeed, and error is reported back to the parachain. + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::DispatchResult(MaybeErrorCode::Error( + // The 2 is the scale encoded Error from the balances pallet + BoundedVec::truncate_from(vec![2]) + )), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }); + } +} diff --git a/examples/src/first_look.rs b/examples/src/first_look.rs new file mode 100644 index 0000000..a7bbe2d --- /dev/null +++ b/examples/src/first_look.rs @@ -0,0 +1,47 @@ +#[cfg(test)] +mod tests { + // use crate::test_net::kusama_test_net::*; + use crate::simple_test_net::*; + use frame_support::assert_ok; + pub use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + #[test] + fn para_a_simple_transfer() { + MockNet::reset(); + + ParaA::execute_with(|| { + // Amount to transfer. + let amount: u128 = 10; + // Check that the balance of Alice is equal to the `INITIAL_BALANCE`. + assert_eq!(ParachainBalances::free_balance(&ALICE), INITIAL_BALANCE); + + // The XCM used to transfer funds from Alice to Bob. + let message = Xcm(vec![ + WithdrawAsset((Here, amount).into()), + BuyExecution { fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited }, + DepositAsset { + assets: All.into(), + beneficiary: MultiLocation { + parents: 0, + interior: Junction::AccountId32 { network: None, id: BOB.clone().into() } + .into(), + } + .into(), + }, + ]); + + // Execution of the XCM Instructions in the local consensus system. + // The RuntimeOrigin is Alice, so Alice's account will be used for the WithdrawAsset. + assert_ok!(ParachainPalletXcm::execute( + parachain::RuntimeOrigin::signed(ALICE), + Box::new(xcm::VersionedXcm::from(message.clone())), + 10.into() + )); + + // Check if the funds are subtracted from the account of Alice and added to the account of Bob. + assert_eq!(ParachainBalances::free_balance(ALICE), INITIAL_BALANCE - amount); + assert_eq!(ParachainBalances::free_balance(BOB), amount); + }); + } +} diff --git a/examples/src/forum.rs b/examples/src/forum.rs new file mode 100644 index 0000000..28d47f1 --- /dev/null +++ b/examples/src/forum.rs @@ -0,0 +1,65 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::assert_ok; + use xcm::v3::prelude::*; + use xcm_simulator::TestExt; + + const BOB: sp_runtime::AccountId32 = sp_runtime::AccountId32::new([2u8; 32]); + const QUERY_ID: u64 = 1234; + + /// Scenario: + /// ALICE sends message from parachain A to parachain B + /// Goal is to move both A's native asset and B's native asset to BOB + fn forum() { + MockNet::reset(); + + let amount_a = 50 * CENTS; + let amount_b = 50 * CENTS; + + let message: Xcm<()> = Xcm(vec![ + SetErrorHandler(Xcm(vec![ReportError(QueryResponseInfo { + destination: ParentThen(X1(Parachain(1))).into(), + query_id: QUERY_ID, + max_weight: 0.into(), + })])), + ReserveAssetDeposited((ParentThen(X1(Parachain(1))), amount_a).into()), + WithdrawAsset((Here, amount_b).into()), + ClearOrigin, + BuyExecution { fees: (Here, amount_b).into(), weight_limit: WeightLimit::Unlimited }, + DepositAsset { + assets: AllCounted(2).into(), + beneficiary: Junction::AccountId32 { network: None, id: BOB.clone().into() }.into(), + }, + ]); + + let destination: MultiLocation = (Parent, Parachain(2)).into(); + let alice = Junction::AccountId32 { id: ALICE.into(), network: None }; + + ParaA::execute_with(|| { + assert_ok!(parachain::PolkadotXcm::send_xcm(alice, destination, message)); + + // ALICE on ParaA does not give up any balance + assert_eq!(parachain::Balances::free_balance(ALICE), INITIAL_BALANCE); + }); + + ParaA::execute_with(|| { + dbg!(¶chain::MsgQueue::received_dmp()); + }); + + ParaB::execute_with(|| { + dbg!(parachain::Balances::free_balance(sibling_account_sovereign_account_id(1, ALICE))); + + // ALICE does give up balance of ParaB's native asset... + assert_eq!( + parachain::Balances::free_balance(sibling_account_sovereign_account_id(1, ALICE)), + INITIAL_BALANCE - amount_b + ); + // ...and gives it to BOB + assert_eq!(parachain::Balances::free_balance(BOB), amount_b); + + // ParaA's native asset is minted and deposited to BOB's account + assert_eq!(parachain::Assets::balance(1, &BOB), amount_a); + }); + } +} diff --git a/examples/src/holding_modifiers/mod.rs b/examples/src/holding_modifiers/mod.rs new file mode 100644 index 0000000..e22d329 --- /dev/null +++ b/examples/src/holding_modifiers/mod.rs @@ -0,0 +1,137 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::{parachain::RelayNativeAsset, *}; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + const QUERY_ID: u64 = 1234; + + /// Scenario: + /// Parachain A withdraws funds from its sovereign account on the relay chain and burns part of them. + /// The relay chain then reports back the status of the Holding Register to Parachain A. + #[test] + fn burn_assets() { + let message = Xcm(vec![ + WithdrawAsset((Here, 10 * CENTS).into()), + BuyExecution { fees: (Here, CENTS).into(), weight_limit: WeightLimit::Unlimited }, + BurnAsset((Here, 4 * CENTS).into()), + ReportHolding { + response_info: QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_parts(1_000_000_000, 64 * 64), + }, + assets: All.into(), + }, + ]); + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::Assets((Parent, 6 * CENTS).into()), + max_weight: Weight::from_parts(1_000_000_000, 64 * 64), + querier: Some(Here.into()), + }])], + ) + }); + } + + /// Scenario: + /// The relay chain sends an XCM to Parachain A that: + /// 1) Withdraws some native assets + /// 2) Exchanges these assets for relay chain derivative tokens, with maximal set to true. + /// 3) Deposit all the assets that are in the Holding in the account of Alice. + /// + /// NOTE: The implementation of the AssetExchanger is simple + /// and in this case swaps all the assets in the exchange for the assets in `give`. + /// Depending on the implementation of AssetExchanger, the test results could differ. + #[test] + fn exchange_asset_maximal_true() { + // Exchange contains 10 CENTS worth of parachain A's derivative of the relay token + let assets_in_exchange = vec![(Parent, 10 * CENTS).into()]; + parachain::set_exchange_assets(assets_in_exchange); + + let message = Xcm(vec![ + WithdrawAsset((Here, 10 * CENTS).into()), + BuyExecution { fees: (Here, CENTS).into(), weight_limit: WeightLimit::Unlimited }, + // Maximal field set to true. + ExchangeAsset { + give: Definite((Here, 5 * CENTS).into()), + want: (Parent, 5 * CENTS).into(), + maximal: true, + }, + DepositAsset { + assets: AllCounted(2).into(), + beneficiary: AccountId32 { + network: Some(parachain::RelayNetwork::get()), + id: ALICE.into(), + } + .into(), + }, + ]); + + Relay::execute_with(|| { + assert_ok!(RelaychainPalletXcm::send_xcm(Here, Parachain(1), message.clone())); + }); + + ParaA::execute_with(|| { + assert_eq!(parachain::exchange_assets(), vec![(Here, 5 * CENTS).into()].into()); + assert_eq!(ParachainAssets::balance(1u128, &ALICE), INITIAL_BALANCE + 10 * CENTS); + assert_eq!(ParachainBalances::free_balance(ALICE), INITIAL_BALANCE + 5 * CENTS); + }) + } + + /// Scenario: + /// The relay chain sends an XCM to Parachain A that: + /// 1) Withdraws some native assets + /// 2) Exchanges these assets for relay chain derivative tokens, with maximal set to false. + /// 3) Deposit all the assets that are in the Holding in the account of Alice. + /// + /// NOTE: The implementation of the AssetExchanger is simple + /// and in this case swaps all the assets in the exchange for the assets in `give`. + /// Depending on the implementation of AssetExchanger, the test results could differ. + #[test] + fn exchange_asset_maximal_false() { + // Exchange contains 10 CENTS worth of parachain A's derivative of the relay token + let assets_in_exchange = vec![(Parent, 10 * CENTS).into()]; + parachain::set_exchange_assets(assets_in_exchange); + + let message = Xcm(vec![ + WithdrawAsset((Here, 10 * CENTS).into()), + BuyExecution { fees: (Here, CENTS).into(), weight_limit: WeightLimit::Unlimited }, + // Maximal field set to false. + ExchangeAsset { + give: Definite((Here, 5 * CENTS).into()), + want: (Parent, 5 * CENTS).into(), + maximal: false, + }, + DepositAsset { + assets: AllCounted(2).into(), + beneficiary: AccountId32 { + network: Some(parachain::RelayNetwork::get()), + id: ALICE.into(), + } + .into(), + }, + ]); + + Relay::execute_with(|| { + assert_ok!(RelaychainPalletXcm::send_xcm(Here, Parachain(1), message.clone())); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::exchange_assets(), + vec![(Parent, 5 * CENTS).into(), (Here, 5 * CENTS).into()].into() + ); + assert_eq!(ParachainAssets::balance(1u128, &ALICE), INITIAL_BALANCE + 5 * CENTS); + assert_eq!(ParachainBalances::free_balance(ALICE), INITIAL_BALANCE + 5 * CENTS); + }) + } +} diff --git a/examples/src/kusama_test_net/kusama_test_net.rs b/examples/src/kusama_test_net/kusama_test_net.rs new file mode 100644 index 0000000..5c3153c --- /dev/null +++ b/examples/src/kusama_test_net/kusama_test_net.rs @@ -0,0 +1,176 @@ +use crate::kusama_test_net::yayoi; +pub use codec::{Decode, Encode}; +use frame_support::{pallet_prelude::Weight, traits::GenesisBuild}; +use polkadot_primitives::v2::{BlockNumber, MAX_CODE_SIZE, MAX_POV_SIZE}; +use polkadot_runtime_parachains::configuration::HostConfiguration; +use sp_runtime::AccountId32; +pub use xcm::v3::prelude::*; +use xcm_emulator::{decl_test_network, decl_test_parachain, decl_test_relay_chain}; +use xcm_executor::traits::Convert; + +pub const ALICE: AccountId32 = AccountId32::new([0u8; 32]); +#[allow(dead_code)] +pub const BOB: AccountId32 = AccountId32::new([1u8; 32]); +pub const INITIAL_BALANCE: u128 = 1_000_000_000_000; + +decl_test_relay_chain! { + pub struct KusamaNet { + Runtime = kusama_runtime::Runtime, + XcmConfig = kusama_runtime::xcm_config::XcmConfig, + new_ext = kusama_ext(), + } +} + +decl_test_parachain! { + pub struct Statemine { + Runtime = statemine_runtime::Runtime, + RuntimeOrigin = statemine_runtime::RuntimeOrigin, + XcmpMessageHandler = statemine_runtime::XcmpQueue, + DmpMessageHandler = statemine_runtime::DmpQueue, + new_ext = statemine_ext(1000), + } +} + +decl_test_parachain! { + pub struct SimpleParachain { + Runtime = yayoi::Runtime, + RuntimeOrigin = yayoi::RuntimeOrigin, + XcmpMessageHandler = yayoi::XcmpQueue, + DmpMessageHandler = yayoi::DmpQueue, + new_ext = yayoi_ext(1001), + } +} + +decl_test_parachain! { + pub struct SimpleParachain2 { + Runtime = yayoi::Runtime, + RuntimeOrigin = yayoi::RuntimeOrigin, + XcmpMessageHandler = yayoi::XcmpQueue, + DmpMessageHandler = yayoi::DmpQueue, + new_ext = yayoi_ext(1002), + } +} + +decl_test_network! { + pub struct TestNet { + relay_chain = KusamaNet, + parachains = vec![ + (1000, Statemine), + (1001, SimpleParachain), + (1002, SimpleParachain2), + ], + } +} + +fn default_parachains_host_configuration() -> HostConfiguration { + HostConfiguration { + minimum_validation_upgrade_delay: 5, + validation_upgrade_cooldown: 5u32, + validation_upgrade_delay: 5, + code_retention_period: 1200, + max_code_size: MAX_CODE_SIZE, + max_pov_size: MAX_POV_SIZE, + max_head_data_size: 32 * 1024, + group_rotation_frequency: 20, + chain_availability_period: 4, + thread_availability_period: 4, + max_upward_queue_count: 8, + max_upward_queue_size: 1024 * 1024, + max_downward_message_size: 1024, + ump_service_total_weight: Weight::from_ref_time(4 * 1_000_000_000), + max_upward_message_size: 50 * 1024, + max_upward_message_num_per_candidate: 5, + hrmp_sender_deposit: 0, + hrmp_recipient_deposit: 0, + hrmp_channel_max_capacity: 8, + hrmp_channel_max_total_size: 8 * 1024, + hrmp_max_parachain_inbound_channels: 4, + hrmp_max_parathread_inbound_channels: 4, + hrmp_channel_max_message_size: 1024 * 1024, + hrmp_max_parachain_outbound_channels: 4, + hrmp_max_parathread_outbound_channels: 4, + hrmp_max_message_num_per_candidate: 5, + dispute_period: 6, + no_show_slots: 2, + n_delay_tranches: 25, + needed_approvals: 2, + relay_vrf_modulo_samples: 2, + zeroth_delay_tranche_width: 0, + ..Default::default() + } +} + +pub fn kusama_ext() -> sp_io::TestExternalities { + use kusama_runtime::{Runtime, System}; + + let mut t = frame_system::GenesisConfig::default().build_storage::().unwrap(); + + pallet_balances::GenesisConfig:: { balances: vec![(ALICE, INITIAL_BALANCE)] } + .assimilate_storage(&mut t) + .unwrap(); + + polkadot_runtime_parachains::configuration::GenesisConfig:: { + config: default_parachains_host_configuration(), + } + .assimilate_storage(&mut t) + .unwrap(); + + let mut ext = sp_io::TestExternalities::new(t); + ext.execute_with(|| System::set_block_number(1)); + ext +} + +pub fn statemine_ext(para_id: u32) -> sp_io::TestExternalities { + use statemine_runtime::{Runtime, System}; + + let mut t = frame_system::GenesisConfig::default().build_storage::().unwrap(); + + let parachain_info_config = parachain_info::GenesisConfig { parachain_id: para_id.into() }; + + >::assimilate_storage( + ¶chain_info_config, + &mut t, + ) + .unwrap(); + + pallet_balances::GenesisConfig:: { + balances: vec![ + (ALICE, INITIAL_BALANCE), + (statemine_sibling_account_id(1001), INITIAL_BALANCE), + (statemine_sibling_account_id(1002), INITIAL_BALANCE), + ], + } + .assimilate_storage(&mut t) + .unwrap(); + + let mut ext = sp_io::TestExternalities::new(t); + ext.execute_with(|| System::set_block_number(1)); + ext +} + +pub fn yayoi_ext(para_id: u32) -> sp_io::TestExternalities { + use crate::kusama_test_net::yayoi::{Runtime, System}; + + let mut t = frame_system::GenesisConfig::default().build_storage::().unwrap(); + + let parachain_info_config = parachain_info::GenesisConfig { parachain_id: para_id.into() }; + + >::assimilate_storage( + ¶chain_info_config, + &mut t, + ) + .unwrap(); + + pallet_balances::GenesisConfig:: { balances: vec![(ALICE, INITIAL_BALANCE)] } + .assimilate_storage(&mut t) + .unwrap(); + + let mut ext = sp_io::TestExternalities::new(t); + ext.execute_with(|| System::set_block_number(1)); + ext +} + +pub fn statemine_sibling_account_id(para: u32) -> sp_runtime::AccountId32 { + statemine_runtime::xcm_config::LocationToAccountId::convert((Parent, Parachain(para)).into()) + .unwrap() +} diff --git a/examples/src/kusama_test_net/mod.rs b/examples/src/kusama_test_net/mod.rs new file mode 100644 index 0000000..0c45b13 --- /dev/null +++ b/examples/src/kusama_test_net/mod.rs @@ -0,0 +1,2 @@ +pub mod kusama_test_net; +pub mod yayoi; diff --git a/examples/src/kusama_test_net/yayoi.rs b/examples/src/kusama_test_net/yayoi.rs new file mode 100644 index 0000000..5271816 --- /dev/null +++ b/examples/src/kusama_test_net/yayoi.rs @@ -0,0 +1,237 @@ +use frame_support::{ + construct_runtime, parameter_types, + traits::{ConstU32, Everything, Nothing}, + weights::{constants::WEIGHT_REF_TIME_PER_SECOND, Weight}, +}; +use frame_system::EnsureRoot; +use pallet_xcm::XcmPassthrough; +use polkadot_parachain::primitives::Sibling; +use sp_core::H256; +use sp_runtime::{ + testing::Header, + traits::{Convert, IdentityLookup}, + AccountId32, +}; +use xcm::v3::prelude::*; +use xcm_builder::{ + AccountId32Aliases, AllowUnpaidExecutionFrom, CurrencyAdapter, EnsureXcmOrigin, + FixedWeightBounds, IsConcrete, ParentIsPreset, RelayChainAsNative, SiblingParachainAsNative, + SiblingParachainConvertsVia, SignedAccountId32AsNative, SignedToAccountId32, + SovereignSignedViaLocation, +}; +use xcm_executor::{Config, XcmExecutor}; + +pub type AccountId = AccountId32; +pub type Balance = u128; + +parameter_types! { + pub const BlockHashCount: u64 = 250; +} + +impl frame_system::Config for Runtime { + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + type Index = u64; + type BlockNumber = u64; + type Hash = H256; + type Hashing = ::sp_runtime::traits::BlakeTwo256; + type AccountId = AccountId; + type Lookup = IdentityLookup; + type Header = Header; + type RuntimeEvent = RuntimeEvent; + type BlockHashCount = BlockHashCount; + type BlockWeights = (); + type BlockLength = (); + type Version = (); + type PalletInfo = PalletInfo; + type AccountData = pallet_balances::AccountData; + type OnNewAccount = (); + type OnKilledAccount = (); + type DbWeight = (); + type BaseCallFilter = Everything; + type SystemWeightInfo = (); + type SS58Prefix = (); + type OnSetCode = cumulus_pallet_parachain_system::ParachainSetCode; + type MaxConsumers = ConstU32<16>; +} + +parameter_types! { + pub ExistentialDeposit: Balance = 1; + pub const MaxLocks: u32 = 50; + pub const MaxReserves: u32 = 50; +} + +impl pallet_balances::Config for Runtime { + type MaxLocks = MaxLocks; + type Balance = Balance; + type RuntimeEvent = RuntimeEvent; + type DustRemoval = (); + type ExistentialDeposit = ExistentialDeposit; + type AccountStore = System; + type WeightInfo = (); + type MaxReserves = MaxReserves; + type ReserveIdentifier = [u8; 8]; +} + +impl parachain_info::Config for Runtime {} + +parameter_types! { + pub const RelayLocation: MultiLocation = MultiLocation::parent(); + pub const TokenLocation: MultiLocation = Here.into_location(); + pub const RelayNetwork: NetworkId = NetworkId::Kusama; + pub RelayChainOrigin: RuntimeOrigin = cumulus_pallet_xcm::Origin::Relay.into(); + pub UniversalLocation: InteriorMultiLocation = X2(GlobalConsensus(RelayNetwork::get()), Parachain(ParachainInfo::parachain_id().into())); +} + +pub type LocationToAccountId = ( + ParentIsPreset, + SiblingParachainConvertsVia, + AccountId32Aliases, +); + +pub type XcmOriginToCallOrigin = ( + SovereignSignedViaLocation, + RelayChainAsNative, + SiblingParachainAsNative, + SignedAccountId32AsNative, + XcmPassthrough, +); + +parameter_types! { + pub const UnitWeightCost: u64 = 10; + pub const MaxInstructions: u32 = 100; + pub const MaxAssetsIntoHolding: u32 = 64; +} + +pub type LocalAssetTransactor = + CurrencyAdapter, LocationToAccountId, AccountId, ()>; + +/// The means for routing XCM messages which are not for local execution into +/// the right message queues. +pub type XcmRouter = ( + // Two routers - use UMP to communicate with the relay chain: + cumulus_primitives_utility::ParentAsUmp, + // ..and XCMP to communicate with the sibling chains. + XcmpQueue, +); + +pub type Barrier = AllowUnpaidExecutionFrom; + +pub struct XcmConfig; +impl Config for XcmConfig { + type RuntimeCall = RuntimeCall; + type XcmSender = XcmRouter; + type AssetTransactor = LocalAssetTransactor; + type OriginConverter = XcmOriginToCallOrigin; + type IsReserve = (); + type IsTeleporter = (); + type UniversalLocation = UniversalLocation; + type Barrier = Barrier; + type Weigher = FixedWeightBounds; + type Trader = (); + type ResponseHandler = (); + type AssetTrap = (); + type AssetClaims = (); + type SubscriptionService = (); + type AssetLocker = PolkadotXcm; + type AssetExchanger = (); + type PalletInstancesInfo = (); + type MaxAssetsIntoHolding = MaxAssetsIntoHolding; + type FeeManager = (); + type MessageExporter = (); + type UniversalAliases = Nothing; + type CallDispatcher = RuntimeCall; + type SafeCallFilter = Everything; +} + +parameter_types! { + pub const ReservedXcmpWeight: Weight = Weight::from_ref_time(WEIGHT_REF_TIME_PER_SECOND.saturating_div(4)); + pub const ReservedDmpWeight: Weight = Weight::from_ref_time(WEIGHT_REF_TIME_PER_SECOND.saturating_div(4)); +} + +impl cumulus_pallet_parachain_system::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type OnSystemEvent = (); + type SelfParaId = ParachainInfo; + type DmpMessageHandler = DmpQueue; + type ReservedDmpWeight = ReservedDmpWeight; + type OutboundXcmpMessageSource = XcmpQueue; + type XcmpMessageHandler = XcmpQueue; + type ReservedXcmpWeight = ReservedXcmpWeight; + type CheckAssociatedRelayNumber = cumulus_pallet_parachain_system::RelayNumberStrictlyIncreases; +} + +impl cumulus_pallet_xcmp_queue::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type XcmExecutor = XcmExecutor; + type ChannelInfo = ParachainSystem; + type VersionWrapper = (); + type ExecuteOverweightOrigin = EnsureRoot; + type ControllerOrigin = EnsureRoot; + type ControllerOriginConverter = XcmOriginToCallOrigin; + type WeightInfo = (); + type PriceForSiblingDelivery = (); +} + +impl cumulus_pallet_dmp_queue::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type XcmExecutor = XcmExecutor; + type ExecuteOverweightOrigin = EnsureRoot; +} + +impl cumulus_pallet_xcm::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type XcmExecutor = XcmExecutor; +} + +pub type LocalOriginToLocation = SignedToAccountId32; + +impl pallet_xcm::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type SendXcmOrigin = EnsureXcmOrigin; + type XcmRouter = XcmRouter; + type ExecuteXcmOrigin = EnsureXcmOrigin; + type XcmExecuteFilter = Everything; + type XcmExecutor = XcmExecutor; + type XcmTeleportFilter = Nothing; + type XcmReserveTransferFilter = Everything; + type Weigher = FixedWeightBounds; + type UniversalLocation = UniversalLocation; + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + const VERSION_DISCOVERY_QUEUE_SIZE: u32 = 100; + type AdvertisedXcmVersion = pallet_xcm::CurrentXcmVersion; + type Currency = Balances; + type CurrencyMatcher = (); + type TrustedLockers = (); + type SovereignAccountOf = (); + type MaxLockers = ConstU32<8>; + type WeightInfo = pallet_xcm::TestWeightInfo; +} + +pub struct AccountIdToMultiLocation; +impl Convert for AccountIdToMultiLocation { + fn convert(account: AccountId) -> MultiLocation { + X1(Junction::AccountId32 { network: None, id: account.into() }).into() + } +} + +type UncheckedExtrinsic = frame_system::mocking::MockUncheckedExtrinsic; +type Block = frame_system::mocking::MockBlock; + +construct_runtime!( + pub enum Runtime where + Block = Block, + NodeBlock = Block, + UncheckedExtrinsic = UncheckedExtrinsic, + { + System: frame_system::{Pallet, Call, Storage, Config, Event}, + Balances: pallet_balances::{Pallet, Call, Storage, Config, Event}, + ParachainSystem: cumulus_pallet_parachain_system::{Pallet, Call, Storage, Inherent, Config, Event}, + ParachainInfo: parachain_info::{Pallet, Storage, Config}, + XcmpQueue: cumulus_pallet_xcmp_queue::{Pallet, Call, Storage, Event}, + DmpQueue: cumulus_pallet_dmp_queue::{Pallet, Call, Storage, Event}, + CumulusXcm: cumulus_pallet_xcm::{Pallet, Event, Origin}, + PolkadotXcm: pallet_xcm::{Pallet, Call, Event, Origin}, + } +); diff --git a/examples/src/lib.rs b/examples/src/lib.rs new file mode 100644 index 0000000..072e1ae --- /dev/null +++ b/examples/src/lib.rs @@ -0,0 +1,12 @@ +mod expects; +mod first_look; +mod holding_modifiers; +mod kusama_test_net; +mod locks; +mod origins; +mod queries; +mod simple_test_net; +mod transact; +mod transfers; +mod trap_and_claim; +mod version_subscription; diff --git a/examples/src/locks/mod.rs b/examples/src/locks/mod.rs new file mode 100644 index 0000000..6d1d404 --- /dev/null +++ b/examples/src/locks/mod.rs @@ -0,0 +1,131 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use pallet_balances::{BalanceLock, Reasons}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + /// Scenario: + /// Parachain A locks 5 Cents of relay chain native assets of its Sovereign account on the relay chain and assigns Parachain B as unlocker. + /// Parachain A then asks Parachain B to unlock the funds partly. Parachain B responds by sending an UnlockAssets instruction to the relay chain. + #[test] + fn remote_locking_on_relay() { + MockNet::reset(); + + ParaA::execute_with(|| { + let message = Xcm(vec![LockAsset { + asset: (Here, 5 * CENTS).into(), + unlocker: (Parachain(2)).into(), + }]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + Relay::execute_with(|| { + assert_eq!( + relay_chain::Balances::locks(¶chain_sovereign_account_id(1)), + vec![BalanceLock { id: *b"py/xcmlk", amount: 5 * CENTS, reasons: Reasons::All }] + ); + }); + + ParaB::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![NoteUnlockable { + owner: (Parent, Parachain(1)).into(), + asset: (Parent, 5 * CENTS).into() + }])] + ); + }); + + ParaA::execute_with(|| { + let message = Xcm(vec![RequestUnlock { + asset: (Parent, 3 * CENTS).into(), + locker: Parent.into(), + }]); + + assert_ok!(ParachainPalletXcm::send_xcm(Here, (Parent, Parachain(2)), message.clone())); + }); + + Relay::execute_with(|| { + assert_eq!( + relay_chain::Balances::locks(¶chain_sovereign_account_id(1)), + vec![BalanceLock { id: *b"py/xcmlk", amount: 2 * CENTS, reasons: Reasons::All }] + ); + }); + } + + /// Scenario: + /// Parachain A sets two locks with Parachain B and Parachain C as unlockers on the relay chain. + /// Parachain A then requests Parachain B to partly unlock. + /// Note: The locks overlap. + /// Steps: + /// 1) Set locks on the relay chain. + /// Unlockers: B, C; Funds registered in pallet-xcm: 10, 5. + /// Lock set in pallet-balances: 10. + /// 2) Parachain B and C receive `NoteUnlockable` instruction. + /// 3) Parachain A sends an `RequestUnlock` instruction to Parachain B for 8 Cents. + /// 4) Parachain B Unlocks a part of the funds by sending a `UnlockAsset` instruction to the relay chain. + /// Unlockers: B, C; Funds registered in pallet-xcm: 2, 5. + /// Lock set in pallet-balances: 5. + /// + #[test] + fn locking_overlap() { + MockNet::reset(); + + // 1) + ParaA::execute_with(|| { + let message = Xcm(vec![ + LockAsset { asset: (Here, 10 * CENTS).into(), unlocker: (Parachain(2)).into() }, + LockAsset { asset: (Here, 5 * CENTS).into(), unlocker: (Parachain(3)).into() }, + ]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + Relay::execute_with(|| { + assert_eq!( + relay_chain::Balances::locks(¶chain_sovereign_account_id(1)), + vec![BalanceLock { id: *b"py/xcmlk", amount: 10 * CENTS, reasons: Reasons::All }] + ); + }); + + // 2) + ParaB::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![NoteUnlockable { + owner: (Parent, Parachain(1)).into(), + asset: (Parent, 10 * CENTS).into() + }])] + ); + }); + + ParaC::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![NoteUnlockable { + owner: (Parent, Parachain(1)).into(), + asset: (Parent, 5 * CENTS).into() + }])] + ); + }); + + // 3) + ParaA::execute_with(|| { + let message = Xcm(vec![RequestUnlock { + asset: (Parent, 8 * CENTS).into(), + locker: Parent.into(), + }]); + + assert_ok!(ParachainPalletXcm::send_xcm(Here, (Parent, Parachain(2)), message.clone())); + }); + + // 4) + Relay::execute_with(|| { + assert_eq!( + relay_chain::Balances::locks(¶chain_sovereign_account_id(1)), + vec![BalanceLock { id: *b"py/xcmlk", amount: 5 * CENTS, reasons: Reasons::All }] + ); + }); + } +} diff --git a/examples/src/origins/mod.rs b/examples/src/origins/mod.rs new file mode 100644 index 0000000..97a775f --- /dev/null +++ b/examples/src/origins/mod.rs @@ -0,0 +1,37 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + const AMOUNT: u128 = 10; + const QUERY_ID: u64 = 1234; + + /// Scenario: + #[test] + fn descend_origin() { + MockNet::reset(); + ParaA::execute_with(|| { + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + // Set the instructions that are executed when ExpectOrigin does not pass. + // In this case, reporting back an error to the Parachain. + SetErrorHandler(Xcm(vec![ReportError(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + })])), + DescendOrigin((PalletInstance(1)).into()), + // Checks if the XcmContext origin descended to `Parachain(1)/PalletInstance(1)`. + ExpectOrigin(Some((Parachain(1), PalletInstance(1)).into())), + ]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // Check that message queue is empty. + // The ExpectOrigin instruction passed so we should not receive an error response. + ParaA::execute_with(|| assert_eq!(parachain::MsgQueue::received_dmp(), vec![])); + } +} diff --git a/examples/src/queries/mod.rs b/examples/src/queries/mod.rs new file mode 100644 index 0000000..96004df --- /dev/null +++ b/examples/src/queries/mod.rs @@ -0,0 +1,194 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use bounded_collections::BoundedVec; + use codec::Encode; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + const AMOUNT: u128 = 1 * CENTS; + /// Arbitrary query id + const QUERY_ID: u64 = 1234; + + /// Scenario: + /// A parachain wants to be notified that a transfer worked correctly. + /// It sends a `ReportHolding` after the deposit to get notified on success. + /// + /// Asserts that the balances are updated correctly and the expected XCM is sent. + #[test] + fn query_holding() { + MockNet::reset(); + + // Send a message which fully succeeds to the relay chain. + // And then report the status of the holding register back to ParaA + ParaA::execute_with(|| { + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: Unlimited }, + DepositAsset { + assets: Definite((Here, AMOUNT - 5).into()), + beneficiary: Parachain(2).into(), + }, + ReportHolding { + response_info: QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + }, + assets: All.into(), + }, + ]); + + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + // Check that transfer was executed + Relay::execute_with(|| { + // Withdraw executed + assert_eq!( + relay_chain::Balances::free_balance(parachain_sovereign_account_id(1)), + INITIAL_BALANCE - AMOUNT + ); + // Deposit executed + assert_eq!( + relay_chain::Balances::free_balance(parachain_sovereign_account_id(2)), + INITIAL_BALANCE + AMOUNT - 5 + ); + }); + + // Check that QueryResponse message was received + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::Assets((Parent, AMOUNT - (AMOUNT - 5)).into()), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }); + } + + /// Scenario: + /// Parachain A wants to query the `PalletInfo` of the balances pallet in the relay chain. + /// It sends a `QueryPallet` instruction to the relay chain. + /// The relay chain responds with a `QueryResponse` instruction containing the `PalletInfo`. + /// + /// Asserts that the relay chain has the balances pallet configured. + #[test] + fn query_pallet() { + MockNet::reset(); + + ParaA::execute_with(|| { + let message = Xcm(vec![QueryPallet { + module_name: "pallet_balances".into(), + response_info: QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + }, + }]); + + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + print_para_events(); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::PalletsInfo(BoundedVec::truncate_from(vec![ + PalletInfo::new(1, "Balances".into(), "pallet_balances".into(), 4, 0, 0) + .unwrap() + ])), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }) + } + + /// Scenario: + /// Parachain A wants to know if the execution of their message on the relay chain succeeded without errors. + /// They set the ErrorHandler to report the value of the error register. + /// If the execution of the xcm instructions errors on the relay chain, the error is reported back to the Parachain. + /// + /// The Relay chain errors on the Trap instruction (Trap always throws an error). + #[test] + fn report_error() { + MockNet::reset(); + + let message = Xcm(vec![ + // Set the Error Handler to report back status of Error register. + SetErrorHandler(Xcm(vec![ReportError(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + })])), + Trap(1u64), + ]); + + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::ExecutionResult(Some((1, XcmError::Trap(1)))), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }); + } + + /// Scenario: + /// Parachain A wants to know if the execution of their `Transact` instruction on the relay chain succeeded without errors. + /// They add the `ReportTransactStatus` instruction to the XCM to get the status of the transact status register reported back. + #[test] + fn report_transact_status() { + MockNet::reset(); + + // Runtime call dispatched by the Transact instruction + let call = relay_chain::RuntimeCall::System( + frame_system::Call::::remark_with_event { + remark: "Hallo Relay!".as_bytes().to_vec(), + }, + ); + + let message = Xcm(vec![ + Transact { + origin_kind: OriginKind::SovereignAccount, + require_weight_at_most: Weight::from_parts(INITIAL_BALANCE as u64, 1024 * 1024), + call: call.encode().into(), + }, + ReportTransactStatus(QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_all(0), + }), + ]); + + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone(),)); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::DispatchResult(MaybeErrorCode::Success), + max_weight: Weight::from_all(0), + querier: Some(Here.into()), + }])], + ); + }); + } +} diff --git a/examples/src/simple_test_net/asset_hub.rs b/examples/src/simple_test_net/asset_hub.rs new file mode 100644 index 0000000..0937fc7 --- /dev/null +++ b/examples/src/simple_test_net/asset_hub.rs @@ -0,0 +1,530 @@ +// Copyright Parity Technologies (UK) Ltd. +// This file is part of Polkadot. + +// Polkadot is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Polkadot is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Polkadot. If not, see . + +//! Asset hub parachain runtime mock. + +use super::{Balance, ForeignChainAliasAccount, UNITS}; +use codec::{Decode, Encode}; +use core::marker::PhantomData; +use frame_support::{ + construct_runtime, parameter_types, + traits::{ + AsEnsureOriginWithArg, ContainsPair, EnsureOrigin, EnsureOriginWithArg, Everything, + EverythingBut, Nothing, + }, + weights::{ + constants::{WEIGHT_PROOF_SIZE_PER_MB, WEIGHT_REF_TIME_PER_SECOND}, + Weight, + }, +}; +use frame_system::{EnsureRoot, EnsureSigned}; +use pallet_xcm::XcmPassthrough; +use polkadot_parachain::primitives::{ + DmpMessageHandler, Id as ParaId, Sibling, XcmpMessageFormat, XcmpMessageHandler, +}; +use polkadot_primitives::BlockNumber as RelayBlockNumber; +use sp_core::{ConstU128, ConstU32, H256}; +use sp_runtime::{ + testing::Header, + traits::{Get, Hash, IdentityLookup}, + AccountId32, +}; +use sp_std::prelude::*; +use xcm::{latest::prelude::*, VersionedXcm}; +use xcm_builder::{ + AccountId32Aliases, AllowTopLevelPaidExecutionFrom, AsPrefixedGeneralIndex, Case, + ConvertedConcreteId, CurrencyAdapter as XcmCurrencyAdapter, EnsureXcmOrigin, + FixedRateOfFungible, FixedWeightBounds, FungiblesAdapter, IsConcrete, NativeAsset, NoChecking, + NonFungiblesAdapter, ParentAsSuperuser, ParentIsPreset, SiblingParachainConvertsVia, + SignedAccountId32AsNative, SignedToAccountId32, SovereignSignedViaLocation, +}; +use xcm_executor::{ + traits::{Convert, JustTry}, + Config, XcmExecutor, +}; + +pub type AccountId = AccountId32; +pub type AssetIdForAssets = u128; + +pub type SovereignAccountOf = ( + ForeignChainAliasAccount, + SiblingParachainConvertsVia, + AccountId32Aliases, + ParentIsPreset, +); + +parameter_types! { + pub const BlockHashCount: u64 = 250; +} + +impl frame_system::Config for Runtime { + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + type Index = u64; + type BlockNumber = u64; + type Hash = H256; + type Hashing = ::sp_runtime::traits::BlakeTwo256; + type AccountId = AccountId; + type Lookup = IdentityLookup; + type Header = Header; + type RuntimeEvent = RuntimeEvent; + type BlockHashCount = BlockHashCount; + type BlockWeights = (); + type BlockLength = (); + type Version = (); + type PalletInfo = PalletInfo; + type AccountData = pallet_balances::AccountData; + type OnNewAccount = (); + type OnKilledAccount = (); + type DbWeight = (); + type BaseCallFilter = Everything; + type SystemWeightInfo = (); + type SS58Prefix = (); + type OnSetCode = (); + type MaxConsumers = ConstU32<16>; +} + +parameter_types! { + pub ExistentialDeposit: Balance = 1; + pub const MaxLocks: u32 = 50; + pub const MaxReserves: u32 = 50; +} + +impl pallet_balances::Config for Runtime { + type MaxLocks = MaxLocks; + type Balance = Balance; + type RuntimeEvent = RuntimeEvent; + type DustRemoval = (); + type ExistentialDeposit = ExistentialDeposit; + type AccountStore = System; + type WeightInfo = (); + type MaxReserves = MaxReserves; + type ReserveIdentifier = [u8; 8]; +} + +parameter_types! { + pub const AssetDeposit: u128 = 1_000_000; + pub const MetadataDepositBase: u128 = 1_000_000; + pub const MetadataDepositPerByte: u128 = 100_000; + pub const AssetAccountDeposit: u128 = 1_000_000; + pub const ApprovalDeposit: u128 = 1_000_000; + pub const AssetsStringLimit: u32 = 50; + pub const RemoveItemsLimit: u32 = 50; +} + +impl pallet_assets::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type Balance = Balance; + type AssetId = AssetIdForAssets; + type Currency = Balances; + type CreateOrigin = AsEnsureOriginWithArg>; + type ForceOrigin = EnsureRoot; + type AssetDeposit = AssetDeposit; + type MetadataDepositBase = MetadataDepositBase; + type MetadataDepositPerByte = MetadataDepositPerByte; + type AssetAccountDeposit = AssetAccountDeposit; + type ApprovalDeposit = ApprovalDeposit; + type StringLimit = AssetsStringLimit; + type Freezer = (); + type Extra = (); + type WeightInfo = (); + type RemoveItemsLimit = RemoveItemsLimit; + type AssetIdParameter = AssetIdForAssets; + type CallbackHandle = (); +} + +// `EnsureOriginWithArg` impl for `CreateOrigin` which allows only XCM origins +// which are the correct sovereign account. +pub struct ForeignCreators; +impl EnsureOriginWithArg for ForeignCreators { + type Success = AccountId; + + fn try_origin( + o: RuntimeOrigin, + a: &MultiLocation, + ) -> sp_std::result::Result { + let origin_location = pallet_xcm::EnsureXcm::::try_origin(o.clone())?; + if !a.starts_with(&origin_location) { + return Err(o) + } + SovereignAccountOf::convert(origin_location).map_err(|_| o) + } + + #[cfg(feature = "runtime-benchmarks")] + fn try_successful_origin(a: &MultiLocation) -> Result { + Ok(pallet_xcm::Origin::Xcm(a.clone()).into()) + } +} + +impl pallet_uniques::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type CollectionId = u32; + type ItemId = u32; + type Currency = Balances; + type CreateOrigin = AsEnsureOriginWithArg>; + type ForceOrigin = EnsureRoot; + type CollectionDeposit = ConstU128<1_000>; + type ItemDeposit = ConstU128<1_000>; + type MetadataDepositBase = ConstU128<1_000>; + type AttributeDepositBase = ConstU128<1_000>; + type DepositPerByte = ConstU128<1>; + type StringLimit = ConstU32<64>; + type KeyLimit = ConstU32<64>; + type ValueLimit = ConstU32<128>; + type Locker = (); + type WeightInfo = (); + #[cfg(feature = "runtime-benchmarks")] + type Helper = (); +} + +parameter_types! { + pub const ReservedXcmpWeight: Weight = Weight::from_parts(WEIGHT_REF_TIME_PER_SECOND.saturating_div(4), 0); + pub const ReservedDmpWeight: Weight = Weight::from_parts(WEIGHT_REF_TIME_PER_SECOND.saturating_div(4), 0); +} + +parameter_types! { + pub const KsmLocation: MultiLocation = MultiLocation::parent(); + pub const TokenLocation: MultiLocation = Here.into_location(); + pub const RelayNetwork: NetworkId = ByGenesis([0; 32]); + pub UniversalLocation: InteriorMultiLocation = Parachain(MsgQueue::parachain_id().into()).into(); +} + +pub type XcmOriginToCallOrigin = ( + SovereignSignedViaLocation, + ParentAsSuperuser, + SignedAccountId32AsNative, + XcmPassthrough, +); + +parameter_types! { + pub const XcmInstructionWeight: Weight = Weight::from_parts(1_000, 1_000); + pub TokensPerSecondPerMegabyte: (AssetId, u128, u128) = (Concrete(Parent.into()), 1_000_000_000_000, 1024 * 1024); + pub const MaxInstructions: u32 = 100; + pub const MaxAssetsIntoHolding: u32 = 64; + pub ForeignPrefix: MultiLocation = (Parent,).into(); + pub CheckingAccount: AccountId = PolkadotXcm::check_account(); + pub TrustedLockPairs: (MultiLocation, MultiAssetFilter) = + (Parent.into(), Wild(AllOf { id: Concrete(Parent.into()), fun: WildFungible })); +} + +pub fn estimate_message_fee(number_of_instructions: u64) -> u128 { + let weight = estimate_message_weight(number_of_instructions); + + estimate_fee_for_weight(weight) +} + +pub fn estimate_message_weight(number_of_instructions: u64) -> Weight { + XcmInstructionWeight::get().saturating_mul(number_of_instructions) +} + +pub fn estimate_fee_for_weight(weight: Weight) -> u128 { + let (_, units_per_second, units_per_mb) = TokensPerSecondPerMegabyte::get(); + + units_per_second * (weight.ref_time() as u128) / (WEIGHT_REF_TIME_PER_SECOND as u128) + + units_per_mb * (weight.proof_size() as u128) / (WEIGHT_PROOF_SIZE_PER_MB as u128) +} + +pub type LocalBalancesTransactor = + XcmCurrencyAdapter, SovereignAccountOf, AccountId, ()>; + +pub struct FromMultiLocationToAsset( + core::marker::PhantomData<(MultiLocation, AssetId)>, +); +impl Convert + for FromMultiLocationToAsset +{ + fn convert(value: MultiLocation) -> Result { + match value { + MultiLocation { parents: 1, interior: Here } => Ok(0 as AssetIdForAssets), + MultiLocation { parents: 1, interior: X1(Parachain(para_id)) } => + Ok(para_id as AssetIdForAssets), + _ => Err(value), + } + } +} + +pub type AssetsTransactor = FungiblesAdapter< + Assets, + ConvertedConcreteId< + AssetIdForAssets, + Balance, + FromMultiLocationToAsset, + JustTry, + >, + SovereignAccountOf, + AccountId, + NoChecking, + CheckingAccount, +>; + +pub type ForeignUniquesTransactor = NonFungiblesAdapter< + ForeignUniques, + ConvertedConcreteId, JustTry>, + SovereignAccountOf, + AccountId, + NoChecking, + (), +>; + +/// Means for transacting assets on this chain +pub type AssetTransactors = (LocalBalancesTransactor, AssetsTransactor, ForeignUniquesTransactor); + +pub type XcmRouter = super::ParachainXcmRouter; +pub type Barrier = AllowTopLevelPaidExecutionFrom; + +parameter_types! { + pub NftCollectionOne: MultiAssetFilter + = Wild(AllOf { fun: WildNonFungible, id: Concrete((Parent, GeneralIndex(1)).into()) }); + pub NftCollectionOneForRelay: (MultiAssetFilter, MultiLocation) + = (NftCollectionOne::get(), Parent.into()); + pub RelayNativeAsset: MultiAssetFilter = Wild(AllOf { fun: WildFungible, id: Concrete((Parent, Here).into()) }); + pub RelayNativeAssetForRelay: (MultiAssetFilter, MultiLocation) = (RelayNativeAsset::get(), Parent.into()); +} +pub type TrustedTeleporters = + (xcm_builder::Case, xcm_builder::Case); +pub type TrustedReserves = EverythingBut>; + +pub struct XcmConfig; +impl Config for XcmConfig { + type RuntimeCall = RuntimeCall; + type XcmSender = XcmRouter; + type AssetTransactor = AssetTransactors; + type OriginConverter = XcmOriginToCallOrigin; + type IsReserve = (NativeAsset, TrustedReserves); + type IsTeleporter = TrustedTeleporters; + type UniversalLocation = UniversalLocation; + type Barrier = Barrier; + type Weigher = FixedWeightBounds; + type Trader = FixedRateOfFungible; + type ResponseHandler = (); + type AssetTrap = (); + type AssetLocker = PolkadotXcm; + type AssetExchanger = (); + type AssetClaims = (); + type SubscriptionService = PolkadotXcm; + type PalletInstancesInfo = AllPalletsWithSystem; + type FeeManager = (); + type MaxAssetsIntoHolding = MaxAssetsIntoHolding; + type MessageExporter = (); + type UniversalAliases = Nothing; + type CallDispatcher = RuntimeCall; + type SafeCallFilter = Everything; +} + +#[frame_support::pallet] +pub mod mock_msg_queue { + use super::*; + use frame_support::pallet_prelude::*; + + #[pallet::config] + pub trait Config: frame_system::Config { + type RuntimeEvent: From> + IsType<::RuntimeEvent>; + type XcmExecutor: ExecuteXcm; + } + + #[pallet::call] + impl Pallet {} + + #[pallet::pallet] + #[pallet::without_storage_info] + pub struct Pallet(_); + + #[pallet::storage] + #[pallet::getter(fn parachain_id)] + pub(super) type ParachainId = StorageValue<_, ParaId, ValueQuery>; + + #[pallet::storage] + #[pallet::getter(fn received_dmp)] + /// A queue of received DMP messages + pub(super) type ReceivedDmp = StorageValue<_, Vec>, ValueQuery>; + + impl Get for Pallet { + fn get() -> ParaId { + Self::parachain_id() + } + } + + pub type MessageId = [u8; 32]; + + #[pallet::event] + #[pallet::generate_deposit(pub(super) fn deposit_event)] + pub enum Event { + // XCMP + /// Some XCM was executed OK. + Success(Option), + /// Some XCM failed. + Fail(Option, XcmError), + /// Bad XCM version used. + BadVersion(Option), + /// Bad XCM format used. + BadFormat(Option), + + // DMP + /// Downward message is invalid XCM. + InvalidFormat(MessageId), + /// Downward message is unsupported version of XCM. + UnsupportedVersion(MessageId), + /// Downward message executed with the given outcome. + ExecutedDownward(MessageId, Outcome), + } + + impl Pallet { + pub fn set_para_id(para_id: ParaId) { + ParachainId::::put(para_id); + } + + fn handle_xcmp_message( + sender: ParaId, + _sent_at: RelayBlockNumber, + xcm: VersionedXcm, + max_weight: Weight, + ) -> Result { + let hash = Encode::using_encoded(&xcm, T::Hashing::hash); + let message_hash = Encode::using_encoded(&xcm, sp_io::hashing::blake2_256); + let (result, event) = match Xcm::::try_from(xcm) { + Ok(xcm) => { + let location = (Parent, Parachain(sender.into())); + match T::XcmExecutor::execute_xcm(location, xcm, message_hash, max_weight) { + Outcome::Error(e) => (Err(e.clone()), Event::Fail(Some(hash), e)), + Outcome::Complete(w) => (Ok(w), Event::Success(Some(hash))), + // As far as the caller is concerned, this was dispatched without error, so + // we just report the weight used. + Outcome::Incomplete(w, e) => (Ok(w), Event::Fail(Some(hash), e)), + } + }, + Err(()) => (Err(XcmError::UnhandledXcmVersion), Event::BadVersion(Some(hash))), + }; + Self::deposit_event(event); + result + } + } + + impl XcmpMessageHandler for Pallet { + fn handle_xcmp_messages<'a, I: Iterator>( + iter: I, + max_weight: Weight, + ) -> Weight { + for (sender, sent_at, data) in iter { + let mut data_ref = data; + let _ = XcmpMessageFormat::decode(&mut data_ref) + .expect("Simulator encodes with versioned xcm format; qed"); + + let mut remaining_fragments = &data_ref[..]; + while !remaining_fragments.is_empty() { + if let Ok(xcm) = + VersionedXcm::::decode(&mut remaining_fragments) + { + let _ = Self::handle_xcmp_message(sender, sent_at, xcm, max_weight); + } else { + debug_assert!(false, "Invalid incoming XCMP message data"); + } + } + } + max_weight + } + } + + impl DmpMessageHandler for Pallet { + fn handle_dmp_messages( + iter: impl Iterator)>, + limit: Weight, + ) -> Weight { + for (_i, (_sent_at, data)) in iter.enumerate() { + let id = sp_io::hashing::blake2_256(&data[..]); + let maybe_versioned = VersionedXcm::::decode(&mut &data[..]); + match maybe_versioned { + Err(_) => { + Self::deposit_event(Event::InvalidFormat(id)); + }, + Ok(versioned) => match Xcm::try_from(versioned) { + Err(()) => Self::deposit_event(Event::UnsupportedVersion(id)), + Ok(x) => { + let outcome = T::XcmExecutor::execute_xcm(Parent, x.clone(), id, limit); + >::append(x); + Self::deposit_event(Event::ExecutedDownward(id, outcome)); + }, + }, + } + } + limit + } + } +} + +impl mock_msg_queue::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type XcmExecutor = XcmExecutor; +} + +pub type LocalOriginToLocation = SignedToAccountId32; + +#[cfg(feature = "runtime-benchmarks")] +parameter_types! { + pub ReachableDest: Option = Some(Parent.into()); +} + +pub struct TrustedLockerCase(PhantomData); +impl> ContainsPair + for TrustedLockerCase +{ + fn contains(origin: &MultiLocation, asset: &MultiAsset) -> bool { + let (o, a) = T::get(); + a.matches(asset) && &o == origin + } +} + +impl pallet_xcm::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type SendXcmOrigin = EnsureXcmOrigin; + type XcmRouter = XcmRouter; + type ExecuteXcmOrigin = EnsureXcmOrigin; + type XcmExecuteFilter = Everything; + type XcmExecutor = XcmExecutor; + type XcmTeleportFilter = Nothing; + type XcmReserveTransferFilter = Everything; + type Weigher = FixedWeightBounds; + type UniversalLocation = UniversalLocation; + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + const VERSION_DISCOVERY_QUEUE_SIZE: u32 = 100; + type AdvertisedXcmVersion = pallet_xcm::CurrentXcmVersion; + type Currency = Balances; + type CurrencyMatcher = IsConcrete; + type TrustedLockers = TrustedLockerCase; + type SovereignAccountOf = SovereignAccountOf; + type MaxLockers = ConstU32<8>; + type WeightInfo = pallet_xcm::TestWeightInfo; + #[cfg(feature = "runtime-benchmarks")] + type ReachableDest = ReachableDest; +} + +type UncheckedExtrinsic = frame_system::mocking::MockUncheckedExtrinsic; +type Block = frame_system::mocking::MockBlock; + +construct_runtime!( + pub enum Runtime where + Block = Block, + NodeBlock = Block, + UncheckedExtrinsic = UncheckedExtrinsic, + { + System: frame_system::{Pallet, Call, Storage, Config, Event}, + Balances: pallet_balances::{Pallet, Call, Storage, Config, Event}, + MsgQueue: mock_msg_queue::{Pallet, Storage, Event}, + PolkadotXcm: pallet_xcm::{Pallet, Call, Event, Origin}, + Assets: pallet_assets, + ForeignUniques: pallet_uniques, + } +); diff --git a/examples/src/simple_test_net/mod.rs b/examples/src/simple_test_net/mod.rs new file mode 100644 index 0000000..8dc24b8 --- /dev/null +++ b/examples/src/simple_test_net/mod.rs @@ -0,0 +1,158 @@ +// Copyright 2021 Parity Technologies (UK) Ltd. +// This file is part of Polkadot. + +// Polkadot is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Polkadot is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Polkadot. If not, see . + +pub mod parachain; +pub mod relay_chain; + +use frame_support::{assert_ok, sp_tracing, traits::GenesisBuild}; +use xcm::prelude::*; +use xcm_executor::traits::Convert; +use xcm_simulator::{decl_test_network, decl_test_parachain, decl_test_relay_chain}; + +// Accounts +pub const ADMIN: sp_runtime::AccountId32 = sp_runtime::AccountId32::new([0u8; 32]); +pub const ALICE: sp_runtime::AccountId32 = sp_runtime::AccountId32::new([1u8; 32]); +pub const BOB: sp_runtime::AccountId32 = sp_runtime::AccountId32::new([2u8; 32]); + +// Balances +pub type Balance = u128; +pub const UNITS: Balance = 10_000_000_000; +pub const CENTS: Balance = UNITS / 100; // 100_000_000 +pub const INITIAL_BALANCE: u128 = 1 * UNITS; + +decl_test_parachain! { + pub struct ParaA { + Runtime = parachain::Runtime, + XcmpMessageHandler = parachain::MsgQueue, + DmpMessageHandler = parachain::MsgQueue, + new_ext = para_ext(1), + } +} + +decl_test_parachain! { + pub struct ParaB { + Runtime = parachain::Runtime, + XcmpMessageHandler = parachain::MsgQueue, + DmpMessageHandler = parachain::MsgQueue, + new_ext = para_ext(2), + } +} + +decl_test_parachain! { + pub struct ParaC { + Runtime = parachain::Runtime, + XcmpMessageHandler = parachain::MsgQueue, + DmpMessageHandler = parachain::MsgQueue, + new_ext = para_ext(3), + } +} + +decl_test_relay_chain! { + pub struct Relay { + Runtime = relay_chain::Runtime, + XcmConfig = relay_chain::XcmConfig, + new_ext = relay_ext(), + } +} + +decl_test_network! { + pub struct MockNet { + relay_chain = Relay, + parachains = vec![ + (1, ParaA), + (2, ParaB), + (3, ParaC), + ], + } +} + +pub fn relay_sovereign_account_id() -> parachain::AccountId { + let location = (Parent,); + parachain::SovereignAccountOf::convert(location.into()).unwrap() +} + +pub fn parachain_sovereign_account_id(para: u32) -> relay_chain::AccountId { + let location = (Parachain(para),); + relay_chain::SovereignAccountOf::convert(location.into()).unwrap() +} + +pub fn para_ext(para_id: u32) -> sp_io::TestExternalities { + use parachain::{MsgQueue, Runtime, System}; + + let mut t = frame_system::GenesisConfig::default().build_storage::().unwrap(); + + pallet_balances::GenesisConfig:: { + balances: vec![(ALICE, INITIAL_BALANCE), (relay_sovereign_account_id(), INITIAL_BALANCE)], + } + .assimilate_storage(&mut t) + .unwrap(); + + pallet_assets::GenesisConfig:: { + assets: vec![ + (1u128, ADMIN, false, 1u128), // Create derivative asset for relay's native token + ], + metadata: Default::default(), + accounts: vec![(1u128, ALICE, INITIAL_BALANCE)], + } + .assimilate_storage(&mut t) + .unwrap(); + + let mut ext = sp_io::TestExternalities::new(t); + ext.execute_with(|| { + sp_tracing::try_init_simple(); + System::set_block_number(1); + MsgQueue::set_para_id(para_id.into()); + }); + ext +} + +pub fn relay_ext() -> sp_io::TestExternalities { + use relay_chain::{Runtime, System}; + + let mut t = frame_system::GenesisConfig::default().build_storage::().unwrap(); + + pallet_balances::GenesisConfig:: { + balances: vec![ + (ALICE, INITIAL_BALANCE), + (parachain_sovereign_account_id(1), INITIAL_BALANCE), + (parachain_sovereign_account_id(2), INITIAL_BALANCE), + ], + } + .assimilate_storage(&mut t) + .unwrap(); + + let mut ext = sp_io::TestExternalities::new(t); + ext.execute_with(|| { + System::set_block_number(1); + }); + ext +} + +pub fn print_para_events() { + use parachain::System; + System::events().iter().for_each(|r| println!(">>> {:?}", r.event)); +} + +pub fn print_relay_events() { + use relay_chain::System; + System::events().iter().for_each(|r| println!(">>> {:?}", r.event)); +} + +pub type RelaychainPalletXcm = pallet_xcm::Pallet; +pub type ParachainPalletXcm = pallet_xcm::Pallet; +pub type RelaychainBalances = pallet_balances::Pallet; +pub type ParachainBalances = pallet_balances::Pallet; +pub type ParachainAssets = pallet_assets::Pallet; diff --git a/examples/src/simple_test_net/parachain.rs b/examples/src/simple_test_net/parachain.rs new file mode 100644 index 0000000..8ec22c2 --- /dev/null +++ b/examples/src/simple_test_net/parachain.rs @@ -0,0 +1,543 @@ +// Copyright 2021 Parity Technologies (UK) Ltd. +// This file is part of Polkadot. + +// Polkadot is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Polkadot is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Polkadot. If not, see . + +//! Parachain runtime mock. + +use super::Balance; +use codec::{Decode, Encode}; +use core::marker::PhantomData; +use frame_support::{ + construct_runtime, ensure, parameter_types, + traits::{ + AsEnsureOriginWithArg, ContainsPair, EnsureOrigin, EnsureOriginWithArg, Everything, + EverythingBut, Nothing, + }, + weights::{constants::WEIGHT_REF_TIME_PER_SECOND, Weight}, +}; +use frame_system::{EnsureRoot, EnsureSigned}; +use pallet_xcm::XcmPassthrough; +use polkadot_parachain::primitives::{ + DmpMessageHandler, Id as ParaId, Sibling, XcmpMessageFormat, XcmpMessageHandler, +}; +use polkadot_primitives::BlockNumber as RelayBlockNumber; +use sp_core::{ConstU128, ConstU32, H256}; +use sp_runtime::{ + testing::Header, + traits::{Get, Hash, IdentityLookup}, + AccountId32, +}; + +use sp_std::{cell::RefCell, prelude::*}; +use xcm::{latest::prelude::*, VersionedXcm}; +use xcm_builder::{ + AccountId32Aliases, AllowUnpaidExecutionFrom, AsPrefixedGeneralIndex, Case, + ConvertedConcreteId, CurrencyAdapter as XcmCurrencyAdapter, EnsureXcmOrigin, + FixedRateOfFungible, FixedWeightBounds, FungiblesAdapter, IsConcrete, NativeAsset, NoChecking, + NonFungiblesAdapter, ParentAsSuperuser, ParentIsPreset, SiblingParachainConvertsVia, + SignedAccountId32AsNative, SignedToAccountId32, SovereignSignedViaLocation, +}; +use xcm_executor::{ + traits::{AssetExchange, Convert, JustTry}, + Assets as HoldingAssets, Config, XcmExecutor, +}; + +pub type AccountId = AccountId32; +pub type AssetIdForAssets = u128; + +pub type SovereignAccountOf = ( + SiblingParachainConvertsVia, + AccountId32Aliases, + ParentIsPreset, +); + +parameter_types! { + pub const BlockHashCount: u64 = 250; +} + +impl frame_system::Config for Runtime { + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + type Index = u64; + type BlockNumber = u64; + type Hash = H256; + type Hashing = ::sp_runtime::traits::BlakeTwo256; + type AccountId = AccountId; + type Lookup = IdentityLookup; + type Header = Header; + type RuntimeEvent = RuntimeEvent; + type BlockHashCount = BlockHashCount; + type BlockWeights = (); + type BlockLength = (); + type Version = (); + type PalletInfo = PalletInfo; + type AccountData = pallet_balances::AccountData; + type OnNewAccount = (); + type OnKilledAccount = (); + type DbWeight = (); + type BaseCallFilter = Everything; + type SystemWeightInfo = (); + type SS58Prefix = (); + type OnSetCode = (); + type MaxConsumers = ConstU32<16>; +} + +parameter_types! { + pub ExistentialDeposit: Balance = 1; + pub const MaxLocks: u32 = 50; + pub const MaxReserves: u32 = 50; +} + +impl pallet_balances::Config for Runtime { + type MaxLocks = MaxLocks; + type Balance = Balance; + type RuntimeEvent = RuntimeEvent; + type DustRemoval = (); + type ExistentialDeposit = ExistentialDeposit; + type AccountStore = System; + type WeightInfo = (); + type MaxReserves = MaxReserves; + type ReserveIdentifier = [u8; 8]; +} + +parameter_types! { + pub const AssetDeposit: u128 = 1_000_000; + pub const MetadataDepositBase: u128 = 1_000_000; + pub const MetadataDepositPerByte: u128 = 100_000; + pub const AssetAccountDeposit: u128 = 1_000_000; + pub const ApprovalDeposit: u128 = 1_000_000; + pub const AssetsStringLimit: u32 = 50; + pub const RemoveItemsLimit: u32 = 50; +} + +impl pallet_assets::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type Balance = Balance; + type AssetId = AssetIdForAssets; + type Currency = Balances; + type CreateOrigin = AsEnsureOriginWithArg>; + type ForceOrigin = EnsureRoot; + type AssetDeposit = AssetDeposit; + type MetadataDepositBase = MetadataDepositBase; + type MetadataDepositPerByte = MetadataDepositPerByte; + type AssetAccountDeposit = AssetAccountDeposit; + type ApprovalDeposit = ApprovalDeposit; + type StringLimit = AssetsStringLimit; + type Freezer = (); + type Extra = (); + type WeightInfo = (); + type RemoveItemsLimit = RemoveItemsLimit; + type AssetIdParameter = AssetIdForAssets; + type CallbackHandle = (); +} + +// `EnsureOriginWithArg` impl for `CreateOrigin` which allows only XCM origins +// which are the correct sovereign account. +pub struct ForeignCreators; +impl EnsureOriginWithArg for ForeignCreators { + type Success = AccountId; + + fn try_origin( + o: RuntimeOrigin, + a: &MultiLocation, + ) -> sp_std::result::Result { + let origin_location = pallet_xcm::EnsureXcm::::try_origin(o.clone())?; + if !a.starts_with(&origin_location) { + return Err(o) + } + SovereignAccountOf::convert(origin_location).map_err(|_| o) + } + + #[cfg(feature = "runtime-benchmarks")] + fn try_successful_origin(a: &MultiLocation) -> Result { + Ok(pallet_xcm::Origin::Xcm(a.clone()).into()) + } +} + +impl pallet_uniques::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type CollectionId = u32; + type ItemId = u32; + type Currency = Balances; + type CreateOrigin = AsEnsureOriginWithArg>; + type ForceOrigin = EnsureRoot; + type CollectionDeposit = ConstU128<1_000>; + type ItemDeposit = ConstU128<1_000>; + type MetadataDepositBase = ConstU128<1_000>; + type AttributeDepositBase = ConstU128<1_000>; + type DepositPerByte = ConstU128<1>; + type StringLimit = ConstU32<64>; + type KeyLimit = ConstU32<64>; + type ValueLimit = ConstU32<128>; + type Locker = (); + type WeightInfo = (); + #[cfg(feature = "runtime-benchmarks")] + type Helper = (); +} + +parameter_types! { + pub const ReservedXcmpWeight: Weight = Weight::from_parts(WEIGHT_REF_TIME_PER_SECOND.saturating_div(4), 0); + pub const ReservedDmpWeight: Weight = Weight::from_parts(WEIGHT_REF_TIME_PER_SECOND.saturating_div(4), 0); +} + +parameter_types! { + pub const KsmLocation: MultiLocation = MultiLocation::parent(); + pub const TokenLocation: MultiLocation = Here.into_location(); + pub const RelayNetwork: NetworkId = ByGenesis([0; 32]); + pub UniversalLocation: InteriorMultiLocation = Parachain(MsgQueue::parachain_id().into()).into(); +} + +pub type XcmOriginToCallOrigin = ( + SovereignSignedViaLocation, + ParentAsSuperuser, + SignedAccountId32AsNative, + XcmPassthrough, +); + +parameter_types! { + pub const UnitWeightCost: Weight = Weight::from_parts(1, 1); + pub RatePerSecondPerByte: (AssetId, u128, u128) = (Concrete(Parent.into()), 1, 1); + pub const MaxInstructions: u32 = 100; + pub const MaxAssetsIntoHolding: u32 = 64; + pub ForeignPrefix: MultiLocation = (Parent,).into(); + pub CheckingAccount: AccountId = PolkadotXcm::check_account(); + pub TrustedLockPairs: (MultiLocation, MultiAssetFilter) = + (Parent.into(), Wild(AllOf { id: Concrete(Parent.into()), fun: WildFungible })); +} + +pub type LocalBalancesTransactor = + XcmCurrencyAdapter, SovereignAccountOf, AccountId, ()>; + +pub struct FromNativeAssetToFungible( + core::marker::PhantomData<(MultiLocation, AssetId)>, +); +impl Convert + for FromNativeAssetToFungible +{ + fn convert(value: MultiLocation) -> Result { + match value { + MultiLocation { parents: 1, interior: Here } => Ok(1 as AssetIdForAssets), + _ => Err(value), + } + } +} + +pub type ForeignAssetsTransactor = FungiblesAdapter< + Assets, + ConvertedConcreteId< + AssetIdForAssets, + Balance, + FromNativeAssetToFungible, + JustTry, + >, + SovereignAccountOf, + AccountId, + NoChecking, + CheckingAccount, +>; + +pub type ForeignUniquesTransactor = NonFungiblesAdapter< + ForeignUniques, + ConvertedConcreteId, JustTry>, + SovereignAccountOf, + AccountId, + NoChecking, + (), +>; + +/// Means for transacting assets on this chain +pub type AssetTransactors = + (LocalBalancesTransactor, ForeignAssetsTransactor, ForeignUniquesTransactor); + +pub type XcmRouter = super::ParachainXcmRouter; +pub type Barrier = AllowUnpaidExecutionFrom; + +parameter_types! { + pub NftCollectionOne: MultiAssetFilter + = Wild(AllOf { fun: WildNonFungible, id: Concrete((Parent, GeneralIndex(1)).into()) }); + pub NftCollectionOneForRelay: (MultiAssetFilter, MultiLocation) + = (NftCollectionOne::get(), Parent.into()); + pub RelayNativeAsset: MultiAssetFilter = Wild(AllOf { fun: WildFungible, id: Concrete((Parent, Here).into()) }); + pub RelayNativeAssetForRelay: (MultiAssetFilter, MultiLocation) = (RelayNativeAsset::get(), Parent.into()); +} +pub type TrustedTeleporters = + (xcm_builder::Case, xcm_builder::Case); +pub type TrustedReserves = EverythingBut>; + +thread_local! { + pub static EXCHANGE_ASSETS: RefCell = RefCell::new(HoldingAssets::new()); +} +pub fn set_exchange_assets(assets: impl Into) { + EXCHANGE_ASSETS.with(|a| a.replace(assets.into().into())); +} +pub fn exchange_assets() -> MultiAssets { + EXCHANGE_ASSETS.with(|a| a.borrow().clone().into()) +} +/// Simple implementation of AssetExchange. +/// If maximal is true we take all assets in the exchange +/// for the assets we want to give. +/// If maximal is false, we take exactly what we want in return for all assets in give. +pub struct TestAssetExchange; +impl AssetExchange for TestAssetExchange { + fn exchange_asset( + _origin: Option<&MultiLocation>, + give: HoldingAssets, + want: &MultiAssets, + maximal: bool, + ) -> Result { + let mut have = EXCHANGE_ASSETS.with(|l| l.borrow().clone()); + ensure!(have.contains_assets(want), give); + let get = if maximal { + std::mem::replace(&mut have, HoldingAssets::new()) + } else { + have.saturating_take(want.clone().into()) + }; + have.subsume_assets(give); + EXCHANGE_ASSETS.with(|l| l.replace(have)); + Ok(get) + } +} + +pub struct XcmConfig; +impl Config for XcmConfig { + type RuntimeCall = RuntimeCall; + type XcmSender = XcmRouter; + type AssetTransactor = AssetTransactors; + type OriginConverter = XcmOriginToCallOrigin; + type IsReserve = (NativeAsset, TrustedReserves); + type IsTeleporter = TrustedTeleporters; + type UniversalLocation = UniversalLocation; + type Barrier = Barrier; + type Weigher = FixedWeightBounds; + type Trader = FixedRateOfFungible; + type ResponseHandler = (); + type AssetTrap = PolkadotXcm; + type AssetLocker = PolkadotXcm; + type AssetExchanger = TestAssetExchange; + type AssetClaims = PolkadotXcm; + type SubscriptionService = PolkadotXcm; + type PalletInstancesInfo = AllPalletsWithSystem; + type FeeManager = (); + type MaxAssetsIntoHolding = MaxAssetsIntoHolding; + type MessageExporter = (); + type UniversalAliases = Nothing; + type CallDispatcher = RuntimeCall; + type SafeCallFilter = Everything; +} + +#[frame_support::pallet] +pub mod mock_msg_queue { + use super::*; + use frame_support::pallet_prelude::*; + + #[pallet::config] + pub trait Config: frame_system::Config { + type RuntimeEvent: From> + IsType<::RuntimeEvent>; + type XcmExecutor: ExecuteXcm; + } + + #[pallet::call] + impl Pallet {} + + #[pallet::pallet] + #[pallet::without_storage_info] + pub struct Pallet(_); + + #[pallet::storage] + #[pallet::getter(fn parachain_id)] + pub(super) type ParachainId = StorageValue<_, ParaId, ValueQuery>; + + #[pallet::storage] + #[pallet::getter(fn received_dmp)] + /// A queue of received DMP messages + pub(super) type ReceivedDmp = StorageValue<_, Vec>, ValueQuery>; + + impl Get for Pallet { + fn get() -> ParaId { + Self::parachain_id() + } + } + + pub type MessageId = [u8; 32]; + + #[pallet::event] + #[pallet::generate_deposit(pub(super) fn deposit_event)] + pub enum Event { + // XCMP + /// Some XCM was executed OK. + Success(Option), + /// Some XCM failed. + Fail(Option, XcmError), + /// Bad XCM version used. + BadVersion(Option), + /// Bad XCM format used. + BadFormat(Option), + + // DMP + /// Downward message is invalid XCM. + InvalidFormat(MessageId), + /// Downward message is unsupported version of XCM. + UnsupportedVersion(MessageId), + /// Downward message executed with the given outcome. + ExecutedDownward(MessageId, Outcome), + } + + impl Pallet { + pub fn set_para_id(para_id: ParaId) { + ParachainId::::put(para_id); + } + + fn handle_xcmp_message( + sender: ParaId, + _sent_at: RelayBlockNumber, + xcm: VersionedXcm, + max_weight: Weight, + ) -> Result { + let hash = Encode::using_encoded(&xcm, T::Hashing::hash); + let message_hash = Encode::using_encoded(&xcm, sp_io::hashing::blake2_256); + let (result, event) = match Xcm::::try_from(xcm) { + Ok(xcm) => { + let location = (Parent, Parachain(sender.into())); + match T::XcmExecutor::execute_xcm(location, xcm, message_hash, max_weight) { + Outcome::Error(e) => (Err(e.clone()), Event::Fail(Some(hash), e)), + Outcome::Complete(w) => (Ok(w), Event::Success(Some(hash))), + // As far as the caller is concerned, this was dispatched without error, so + // we just report the weight used. + Outcome::Incomplete(w, e) => (Ok(w), Event::Fail(Some(hash), e)), + } + }, + Err(()) => (Err(XcmError::UnhandledXcmVersion), Event::BadVersion(Some(hash))), + }; + Self::deposit_event(event); + result + } + } + + impl XcmpMessageHandler for Pallet { + fn handle_xcmp_messages<'a, I: Iterator>( + iter: I, + max_weight: Weight, + ) -> Weight { + for (sender, sent_at, data) in iter { + let mut data_ref = data; + let _ = XcmpMessageFormat::decode(&mut data_ref) + .expect("Simulator encodes with versioned xcm format; qed"); + + let mut remaining_fragments = &data_ref[..]; + while !remaining_fragments.is_empty() { + if let Ok(xcm) = + VersionedXcm::::decode(&mut remaining_fragments) + { + let _ = Self::handle_xcmp_message(sender, sent_at, xcm, max_weight); + } else { + debug_assert!(false, "Invalid incoming XCMP message data"); + } + } + } + max_weight + } + } + + impl DmpMessageHandler for Pallet { + fn handle_dmp_messages( + iter: impl Iterator)>, + limit: Weight, + ) -> Weight { + for (_i, (_sent_at, data)) in iter.enumerate() { + let id = sp_io::hashing::blake2_256(&data[..]); + let maybe_versioned = VersionedXcm::::decode(&mut &data[..]); + match maybe_versioned { + Err(_) => { + Self::deposit_event(Event::InvalidFormat(id)); + }, + Ok(versioned) => match Xcm::try_from(versioned) { + Err(()) => Self::deposit_event(Event::UnsupportedVersion(id)), + Ok(x) => { + let outcome = T::XcmExecutor::execute_xcm(Parent, x.clone(), id, limit); + >::append(x); + Self::deposit_event(Event::ExecutedDownward(id, outcome)); + }, + }, + } + } + limit + } + } +} + +impl mock_msg_queue::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type XcmExecutor = XcmExecutor; +} + +pub type LocalOriginToLocation = SignedToAccountId32; + +#[cfg(feature = "runtime-benchmarks")] +parameter_types! { + pub ReachableDest: Option = Some(Parent.into()); +} + +pub struct TrustedLockerCase(PhantomData); +impl> ContainsPair + for TrustedLockerCase +{ + fn contains(origin: &MultiLocation, asset: &MultiAsset) -> bool { + let (o, a) = T::get(); + a.matches(asset) && &o == origin + } +} + +impl pallet_xcm::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type SendXcmOrigin = EnsureXcmOrigin; + type XcmRouter = XcmRouter; + type ExecuteXcmOrigin = EnsureXcmOrigin; + type XcmExecuteFilter = Everything; + type XcmExecutor = XcmExecutor; + type XcmTeleportFilter = Nothing; + type XcmReserveTransferFilter = Everything; + type Weigher = FixedWeightBounds; + type UniversalLocation = UniversalLocation; + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + const VERSION_DISCOVERY_QUEUE_SIZE: u32 = 100; + type AdvertisedXcmVersion = pallet_xcm::CurrentXcmVersion; + type Currency = Balances; + type CurrencyMatcher = IsConcrete; + type TrustedLockers = TrustedLockerCase; + type SovereignAccountOf = SovereignAccountOf; + type MaxLockers = ConstU32<8>; + type WeightInfo = pallet_xcm::TestWeightInfo; + #[cfg(feature = "runtime-benchmarks")] + type ReachableDest = ReachableDest; +} + +type UncheckedExtrinsic = frame_system::mocking::MockUncheckedExtrinsic; +type Block = frame_system::mocking::MockBlock; + +construct_runtime!( + pub enum Runtime where + Block = Block, + NodeBlock = Block, + UncheckedExtrinsic = UncheckedExtrinsic, + { + System: frame_system::{Pallet, Call, Storage, Config, Event}, + Balances: pallet_balances::{Pallet, Call, Storage, Config, Event}, + MsgQueue: mock_msg_queue::{Pallet, Storage, Event}, + PolkadotXcm: pallet_xcm::{Pallet, Call, Event, Origin}, + Assets: pallet_assets, + ForeignUniques: pallet_uniques, + } +); diff --git a/examples/src/simple_test_net/relay_chain.rs b/examples/src/simple_test_net/relay_chain.rs new file mode 100644 index 0000000..84552c6 --- /dev/null +++ b/examples/src/simple_test_net/relay_chain.rs @@ -0,0 +1,256 @@ +// Copyright 2021 Parity Technologies (UK) Ltd. +// This file is part of Polkadot. + +// Polkadot is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. + +// Polkadot is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. + +// You should have received a copy of the GNU General Public License +// along with Polkadot. If not, see . + +//! Relay chain runtime mock. + +use frame_support::{ + construct_runtime, parameter_types, + traits::{AsEnsureOriginWithArg, Everything, Nothing}, + weights::Weight, +}; + +use frame_system::EnsureRoot; +use sp_core::{ConstU128, ConstU32, H256}; +use sp_runtime::{testing::Header, traits::IdentityLookup, AccountId32}; + +use polkadot_parachain::primitives::Id as ParaId; +use polkadot_runtime_parachains::{configuration, origin, shared, ump}; +use xcm::latest::prelude::*; +use xcm_builder::{ + AccountId32Aliases, AllowUnpaidExecutionFrom, AsPrefixedGeneralIndex, ChildParachainAsNative, + ChildParachainConvertsVia, ChildSystemParachainAsSuperuser, ConvertedConcreteId, + CurrencyAdapter as XcmCurrencyAdapter, FixedRateOfFungible, FixedWeightBounds, IsConcrete, + NoChecking, NonFungiblesAdapter, SiblingParachainConvertsVia, SignedAccountId32AsNative, + SignedToAccountId32, SovereignSignedViaLocation, +}; +use xcm_executor::{traits::JustTry, Config, XcmExecutor}; + +use super::Balance; + +pub type AccountId = AccountId32; + +parameter_types! { + pub const BlockHashCount: u64 = 250; +} + +impl frame_system::Config for Runtime { + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + type Index = u64; + type BlockNumber = u64; + type Hash = H256; + type Hashing = ::sp_runtime::traits::BlakeTwo256; + type AccountId = AccountId; + type Lookup = IdentityLookup; + type Header = Header; + type RuntimeEvent = RuntimeEvent; + type BlockHashCount = BlockHashCount; + type BlockWeights = (); + type BlockLength = (); + type Version = (); + type PalletInfo = PalletInfo; + type AccountData = pallet_balances::AccountData; + type OnNewAccount = (); + type OnKilledAccount = (); + type DbWeight = (); + type BaseCallFilter = Everything; + type SystemWeightInfo = (); + type SS58Prefix = (); + type OnSetCode = (); + type MaxConsumers = ConstU32<16>; +} + +parameter_types! { + pub ExistentialDeposit: Balance = 1; + pub const MaxLocks: u32 = 50; + pub const MaxReserves: u32 = 50; +} + +impl pallet_balances::Config for Runtime { + type MaxLocks = MaxLocks; + type Balance = Balance; + type RuntimeEvent = RuntimeEvent; + type DustRemoval = (); + type ExistentialDeposit = ExistentialDeposit; + type AccountStore = System; + type WeightInfo = (); + type MaxReserves = MaxReserves; + type ReserveIdentifier = [u8; 8]; +} + +impl pallet_uniques::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type CollectionId = u32; + type ItemId = u32; + type Currency = Balances; + type CreateOrigin = AsEnsureOriginWithArg>; + type ForceOrigin = EnsureRoot; + type CollectionDeposit = ConstU128<1_000>; + type ItemDeposit = ConstU128<1_000>; + type MetadataDepositBase = ConstU128<1_000>; + type AttributeDepositBase = ConstU128<1_000>; + type DepositPerByte = ConstU128<1>; + type StringLimit = ConstU32<64>; + type KeyLimit = ConstU32<64>; + type ValueLimit = ConstU32<128>; + type Locker = (); + type WeightInfo = (); + #[cfg(feature = "runtime-benchmarks")] + type Helper = (); +} + +impl shared::Config for Runtime {} + +impl configuration::Config for Runtime { + type WeightInfo = configuration::TestWeightInfo; +} + +parameter_types! { + pub RelayNetwork: NetworkId = ByGenesis([0; 32]); + pub const TokenLocation: MultiLocation = Here.into_location(); + pub UniversalLocation: InteriorMultiLocation = Here; + pub UnitWeightCost: u64 = 1_000; +} + +pub type SovereignAccountOf = ( + AccountId32Aliases, + ChildParachainConvertsVia, + SiblingParachainConvertsVia, +); + +pub type LocalBalancesTransactor = + XcmCurrencyAdapter, SovereignAccountOf, AccountId, ()>; + +pub type LocalUniquesTransactor = NonFungiblesAdapter< + Uniques, + ConvertedConcreteId, JustTry>, + SovereignAccountOf, + AccountId, + NoChecking, + (), +>; + +pub type AssetTransactors = (LocalBalancesTransactor, LocalUniquesTransactor); + +type LocalOriginConverter = ( + SovereignSignedViaLocation, + ChildParachainAsNative, + SignedAccountId32AsNative, + ChildSystemParachainAsSuperuser, +); + +parameter_types! { + pub const BaseXcmWeight: Weight = Weight::from_parts(1_000, 1_000); + pub TokensPerSecondPerByte: (AssetId, u128, u128) = + (Concrete(TokenLocation::get()), 1_000_000_000_000, 1024 * 1024); + pub const MaxInstructions: u32 = 100; + pub const MaxAssetsIntoHolding: u32 = 64; +} + +pub type XcmRouter = super::RelayChainXcmRouter; +pub type Barrier = AllowUnpaidExecutionFrom; + +pub struct XcmConfig; +impl Config for XcmConfig { + type RuntimeCall = RuntimeCall; + type XcmSender = XcmRouter; + type AssetTransactor = AssetTransactors; + type OriginConverter = LocalOriginConverter; + type IsReserve = (); + type IsTeleporter = (); + type UniversalLocation = UniversalLocation; + type Barrier = Barrier; + type Weigher = FixedWeightBounds; + type Trader = FixedRateOfFungible; + type ResponseHandler = XcmPallet; + type AssetTrap = XcmPallet; + type AssetLocker = XcmPallet; + type AssetExchanger = (); + type AssetClaims = XcmPallet; + type SubscriptionService = XcmPallet; + type PalletInstancesInfo = AllPalletsWithSystem; + type FeeManager = (); + type MaxAssetsIntoHolding = MaxAssetsIntoHolding; + type MessageExporter = (); + type UniversalAliases = Nothing; + type CallDispatcher = RuntimeCall; + type SafeCallFilter = Everything; +} + +pub type LocalOriginToLocation = SignedToAccountId32; + +#[cfg(feature = "runtime-benchmarks")] +parameter_types! { + pub ReachableDest: Option = Some(Parachain(1).into()); +} + +impl pallet_xcm::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type SendXcmOrigin = xcm_builder::EnsureXcmOrigin; + type XcmRouter = XcmRouter; + // Anyone can execute XCM messages locally... + type ExecuteXcmOrigin = xcm_builder::EnsureXcmOrigin; + type XcmExecuteFilter = Everything; + type XcmExecutor = XcmExecutor; + type XcmTeleportFilter = Everything; + type XcmReserveTransferFilter = Everything; + type Weigher = FixedWeightBounds; + type UniversalLocation = UniversalLocation; + type RuntimeOrigin = RuntimeOrigin; + type RuntimeCall = RuntimeCall; + const VERSION_DISCOVERY_QUEUE_SIZE: u32 = 100; + type AdvertisedXcmVersion = pallet_xcm::CurrentXcmVersion; + type Currency = Balances; + type CurrencyMatcher = IsConcrete; + type TrustedLockers = (); + type SovereignAccountOf = SovereignAccountOf; + type MaxLockers = ConstU32<8>; + type WeightInfo = pallet_xcm::TestWeightInfo; + #[cfg(feature = "runtime-benchmarks")] + type ReachableDest = ReachableDest; +} + +parameter_types! { + pub const FirstMessageFactorPercent: u64 = 100; +} + +impl ump::Config for Runtime { + type RuntimeEvent = RuntimeEvent; + type UmpSink = ump::XcmSink, Runtime>; + type FirstMessageFactorPercent = FirstMessageFactorPercent; + type ExecuteOverweightOrigin = frame_system::EnsureRoot; + type WeightInfo = ump::TestWeightInfo; +} + +impl origin::Config for Runtime {} + +type UncheckedExtrinsic = frame_system::mocking::MockUncheckedExtrinsic; +type Block = frame_system::mocking::MockBlock; + +construct_runtime!( + pub enum Runtime where + Block = Block, + NodeBlock = Block, + UncheckedExtrinsic = UncheckedExtrinsic, + { + System: frame_system::{Pallet, Call, Storage, Config, Event}, + Balances: pallet_balances::{Pallet, Call, Storage, Config, Event}, + Uniques: pallet_uniques, + ParasOrigin: origin::{Pallet, Origin}, + ParasUmp: ump::{Pallet, Call, Storage, Event}, + XcmPallet: pallet_xcm::{Pallet, Call, Storage, Event, Origin}, + } +); diff --git a/examples/src/transact/mod.rs b/examples/src/transact/mod.rs new file mode 100644 index 0000000..b1b9841 --- /dev/null +++ b/examples/src/transact/mod.rs @@ -0,0 +1,95 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use codec::Encode; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + const AMOUNT: u128 = 1 * CENTS; + + /// Scenario: + /// Relay chain sets the balance of Alice on Parachain(1). + /// The relay chain is able to do this, because Parachain(1) trusts the relay chain to execute runtime calls as root. + #[test] + fn transact_set_balance() { + MockNet::reset(); + // Runtime call dispatched by the Transact instruction. + // set_balance requires root origin. + let call = parachain::RuntimeCall::Balances( + pallet_balances::Call::::set_balance { + who: ALICE, + new_free: 5 * AMOUNT, + new_reserved: 0, + }, + ); + + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + Transact { + origin_kind: OriginKind::Superuser, + require_weight_at_most: Weight::from_parts(1_000_000_000, 1024 * 1024), + call: call.encode().into(), + }, + ]); + + Relay::execute_with(|| { + assert_ok!(RelaychainPalletXcm::send_xcm(Here, Parachain(1), message.clone(),)); + }); + + ParaA::execute_with(|| { + assert_eq!(ParachainBalances::free_balance(ALICE), 5 * AMOUNT); + }) + } + + /// Scenario: + /// Parachain A sends two transact instructions to the relay chain. + /// The first instruction creates a NFT collection with as admin Parachain A. + /// The second instruction mints a NFT for the collection with as Owner ALICE. + #[test] + fn transact_mint_nft() { + MockNet::reset(); + let create_collection = relay_chain::RuntimeCall::Uniques(pallet_uniques::Call::< + relay_chain::Runtime, + >::create { + collection: 1u32, + admin: parachain_sovereign_account_id(1), + }); + + let mint = + relay_chain::RuntimeCall::Uniques(pallet_uniques::Call::::mint { + collection: 1u32, + item: 1u32, + owner: ALICE, + }); + + let message = Xcm(vec![ + WithdrawAsset((Here, AMOUNT).into()), + BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, + Transact { + origin_kind: OriginKind::SovereignAccount, + require_weight_at_most: Weight::from_parts(INITIAL_BALANCE as u64, 1024 * 1024), + call: create_collection.encode().into(), + }, + Transact { + origin_kind: OriginKind::SovereignAccount, + require_weight_at_most: Weight::from_parts(INITIAL_BALANCE as u64, 1024 * 1024), + call: mint.encode().into(), + }, + ]); + + // Create collection with Alice as owner. + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + Relay::execute_with(|| { + assert_eq!( + relay_chain::Uniques::collection_owner(1u32), + Some(parachain_sovereign_account_id(1)) + ); + assert_eq!(relay_chain::Uniques::owner(1u32, 1u32), Some(ALICE)); + }); + } +} diff --git a/examples/src/transfers/mod.rs b/examples/src/transfers/mod.rs new file mode 100644 index 0000000..ff5e7ce --- /dev/null +++ b/examples/src/transfers/mod.rs @@ -0,0 +1,2 @@ +mod reserve; +mod teleport; diff --git a/examples/src/transfers/reserve.rs b/examples/src/transfers/reserve.rs new file mode 100644 index 0000000..36bd7ac --- /dev/null +++ b/examples/src/transfers/reserve.rs @@ -0,0 +1,108 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::assert_ok; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + /// Scenario: + /// ALICE transfers her FDOT from parachain A to parachain B. + #[test] + fn reserve_backed_transfer_para_to_para() { + MockNet::reset(); + + let withdraw_amount = 50 * CENTS; + + let message: Xcm = Xcm(vec![ + WithdrawAsset((Parent, withdraw_amount).into()), + InitiateReserveWithdraw { + assets: All.into(), + reserve: Parent.into(), + xcm: Xcm(vec![ + BuyExecution { + fees: (Here, withdraw_amount).into(), + weight_limit: WeightLimit::Unlimited, + }, + DepositReserveAsset { + assets: All.into(), + dest: Parachain(2).into(), + xcm: Xcm(vec![DepositAsset { + assets: All.into(), + beneficiary: Junction::AccountId32 { id: ALICE.into(), network: None } + .into(), + }]), + }, + ]), + }, + ]); + + ParaA::execute_with(|| { + assert_ok!(parachain::PolkadotXcm::execute( + parachain::RuntimeOrigin::signed(ALICE), + Box::new(xcm::VersionedXcm::V3(message.into())), + (100_000_000_000, 100_000_000_000).into(), + )); + + assert_eq!(parachain::Assets::balance(1, &ALICE), INITIAL_BALANCE - withdraw_amount); + }); + + Relay::execute_with(|| { + assert_eq!( + relay_chain::Balances::free_balance(¶chain_sovereign_account_id(2)), + INITIAL_BALANCE + withdraw_amount + ); + }); + + ParaB::execute_with(|| { + assert_eq!(parachain::Assets::balance(1, &ALICE), INITIAL_BALANCE + withdraw_amount); + }); + } + + /// Scenario: + /// ALICE transfers her FDOT from relay to parachain B. + #[test] + fn reserve_backed_transfer_relay_to_para() { + MockNet::reset(); + + let withdraw_amount = 50 * CENTS; + + let message: Xcm = Xcm(vec![TransferReserveAsset { + assets: (Here, withdraw_amount).into(), + dest: Parachain(2).into(), + xcm: Xcm(vec![ + BuyExecution { + fees: (Here, withdraw_amount).into(), + weight_limit: WeightLimit::Unlimited, + }, + DepositAsset { + assets: All.into(), + beneficiary: Junction::AccountId32 { id: ALICE.into(), network: None }.into(), + }, + ]), + }]); + + Relay::execute_with(|| { + assert_ok!(relay_chain::XcmPallet::execute( + relay_chain::RuntimeOrigin::signed(ALICE), + Box::new(xcm::VersionedXcm::V3(message.into())), + (100_000_000_000, 100_000_000_000).into(), + )); + + // ALICE's balance in the relay chain decreases + assert_eq!( + relay_chain::Balances::free_balance(&ALICE), + INITIAL_BALANCE - withdraw_amount + ); + + // Parachain(2)'s sovereign account's balance increases + assert_eq!( + relay_chain::Balances::free_balance(¶chain_sovereign_account_id(2)), + INITIAL_BALANCE + withdraw_amount + ); + }); + + ParaB::execute_with(|| { + assert_eq!(parachain::Assets::balance(1, &ALICE), INITIAL_BALANCE + withdraw_amount); + }); + } +} diff --git a/examples/src/transfers/teleport.rs b/examples/src/transfers/teleport.rs new file mode 100644 index 0000000..0cc18d0 --- /dev/null +++ b/examples/src/transfers/teleport.rs @@ -0,0 +1,125 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::assert_ok; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + /// Scenario: + /// ALICE teleports her native assets from the relay chain to parachain A. + #[test] + fn teleport_fungible() { + MockNet::reset(); + + let teleport_amount = 50 * CENTS; + let message: Xcm = Xcm(vec![ + WithdrawAsset((Here, teleport_amount).into()), + InitiateTeleport { + assets: AllCounted(1).into(), + dest: Parachain(1).into(), + xcm: Xcm(vec![DepositAsset { + assets: AllCounted(1).into(), + beneficiary: Junction::AccountId32 { network: None, id: ALICE.into() }.into(), + }]), + }, + ]); + + Relay::execute_with(|| { + assert_ok!(relay_chain::XcmPallet::execute( + relay_chain::RuntimeOrigin::signed(ALICE), + Box::new(xcm::VersionedXcm::V3(message.into())), + (100_000_000_000, 100_000_000_000).into() + )); + + assert_eq!( + relay_chain::Balances::free_balance(ALICE), + INITIAL_BALANCE - teleport_amount + ); + }); + + ParaA::execute_with(|| { + let expected_message_received: Xcm = Xcm(vec![ + ReceiveTeleportedAsset(vec![(Parent, teleport_amount).into()].into()), + ClearOrigin, + DepositAsset { + assets: AllCounted(1).into(), + beneficiary: Junction::AccountId32 { network: None, id: ALICE.into() }.into(), + }, + ]); + + assert_eq!(parachain::MsgQueue::received_dmp(), vec![expected_message_received]); + + assert_eq!(parachain::Assets::balance(1, &ALICE), INITIAL_BALANCE + teleport_amount); + }); + } + + /// Scenario: + /// ALICE teleports her nft from the relay chain to parachain A + #[test] + fn teleport_nft() { + MockNet::reset(); + + Relay::execute_with(|| { + // Mint NFT for Alice on Relay chain + assert_ok!(relay_chain::Uniques::force_create( + relay_chain::RuntimeOrigin::root(), + 1, + ALICE, + true + )); + assert_ok!(relay_chain::Uniques::mint( + relay_chain::RuntimeOrigin::signed(ALICE), + 1, + 42, + ALICE + )); + + assert_eq!(relay_chain::Uniques::owner(1, 42), Some(ALICE)); + }); + + ParaA::execute_with(|| { + // Create NFT collection representing the relay chain one + assert_ok!(parachain::ForeignUniques::force_create( + parachain::RuntimeOrigin::root(), + 1u32, + ALICE, + false + )); + + // Alice is Collection Owner. + assert_eq!(parachain::ForeignUniques::collection_owner(1u32), Some(ALICE)); + // Alice does not own Collection Item 42 yet. + assert_eq!(parachain::ForeignUniques::owner(1u32, 42u32.into()), None); + assert_eq!(parachain::Balances::reserved_balance(&ALICE), 0); + }); + + let message: Xcm = Xcm(vec![ + WithdrawAsset((GeneralIndex(1), 42u64).into()), + InitiateTeleport { + assets: AllCounted(1).into(), + dest: Parachain(1).into(), + xcm: Xcm(vec![DepositAsset { + assets: AllCounted(1).into(), + beneficiary: Junction::AccountId32 { id: ALICE.into(), network: None }.into(), + }]), + }, + ]); + + Relay::execute_with(|| { + assert_ok!(relay_chain::XcmPallet::execute( + relay_chain::RuntimeOrigin::signed(ALICE), + Box::new(xcm::VersionedXcm::V3(message.into())), + (100_000_000_000, 100_000_000_000).into(), + )); + }); + + ParaA::execute_with(|| { + assert_eq!(parachain::ForeignUniques::owner(1u32, 42u32.into()), Some(ALICE)); + assert_eq!(parachain::Balances::reserved_balance(&ALICE), 1000); + }); + + Relay::execute_with(|| { + assert_eq!(relay_chain::Uniques::owner(1, 42), None); + }); + } +} diff --git a/examples/src/trap_and_claim/mod.rs b/examples/src/trap_and_claim/mod.rs new file mode 100644 index 0000000..1651b00 --- /dev/null +++ b/examples/src/trap_and_claim/mod.rs @@ -0,0 +1,74 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + const QUERY_ID: u64 = 1234; + + /// Scenario: + /// Parachain A withdraws funds from its sovereign account on the relay chain. + /// The assets are trapped because an error is thrown and the execution is halted. + /// Parachain A claims the trapped assets and receives a report of the holding register. + /// It then deposits the assets in the account of ALICE. + #[test] + fn trap_and_claim_assets() { + let message = Xcm(vec![ + WithdrawAsset((Here, 10 * CENTS).into()), + BuyExecution { fees: (Here, CENTS).into(), weight_limit: WeightLimit::Unlimited }, + Trap(0), // <-- Errors + DepositAsset { + // <-- Not executed because of error. + assets: All.into(), + beneficiary: AccountId32 { + network: Some(parachain::RelayNetwork::get()), + id: ALICE.into(), + } + .into(), + }, + ]); + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + let claim_message = Xcm(vec![ + ClaimAsset { assets: (Here, 10 * CENTS).into(), ticket: Here.into() }, + ReportHolding { + response_info: QueryResponseInfo { + destination: Parachain(1).into(), + query_id: QUERY_ID, + max_weight: Weight::from_parts(1_000_000_000, 64 * 64), + }, + assets: All.into(), + }, + DepositAsset { + assets: All.into(), + beneficiary: AccountId32 { + network: Some(parachain::RelayNetwork::get()), + id: ALICE.into(), + } + .into(), + }, + ]); + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, claim_message.clone())); + }); + + Relay::execute_with(|| { + assert_eq!(RelaychainBalances::free_balance(ALICE), INITIAL_BALANCE + 10 * CENTS); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: QUERY_ID, + response: Response::Assets((Parent, 10 * CENTS).into()), + max_weight: Weight::from_parts(1_000_000_000, 64 * 64), + querier: Some(Here.into()), + }])], + ) + }); + } +} diff --git a/examples/src/version_subscription/mod.rs b/examples/src/version_subscription/mod.rs new file mode 100644 index 0000000..c48e5ff --- /dev/null +++ b/examples/src/version_subscription/mod.rs @@ -0,0 +1,42 @@ +#[cfg(test)] +mod tests { + use crate::simple_test_net::*; + use frame_support::{assert_ok, pallet_prelude::Weight}; + use xcm::latest::prelude::*; + use xcm_simulator::TestExt; + + /// Scenario: + /// Parachain A wants to know which version of Xcm the relay chain uses. + /// It sends the `SubscribeVersion` instruction to get the Xcm version of the relay chain + /// and to receive updates if the version changes. + /// When the parachain receives the version it unsubscribes from version updates. + #[test] + fn subscribe_and_unsubscribe_version() { + MockNet::reset(); + + let query_id_set = 1234; + let message = Xcm(vec![SubscribeVersion { + query_id: query_id_set, + max_response_weight: Weight::from_all(0), + }]); + + ParaA::execute_with(|| { + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, message.clone())); + }); + + ParaA::execute_with(|| { + assert_eq!( + parachain::MsgQueue::received_dmp(), + vec![Xcm(vec![QueryResponse { + query_id: query_id_set, + response: Response::Version(3), + max_weight: Weight::from_all(0), + querier: None, + }])], + ); + + let unsub_message = Xcm(vec![UnsubscribeVersion]); + assert_ok!(ParachainPalletXcm::send_xcm(Here, Parent, unsub_message)); + }); + } +} diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 77e9dee..843e1b0 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -34,12 +34,12 @@ - [Channels and Bridges](journey/channels-and-bridges.md) - [Misc]() - [Config Deep Dive](executor_config/README.md) -- [Testing]() +- [Testing](testing/README.md) - [Separation of concerns]() - [Simulating message execution]() - [How to test my own configuration]() - [Testing the full XCM Journey]() -- [Transport Protocols]() +- [Transport Protocols](transport_protocols/README.md) - [VMP]() - [HRMP]() - [XCMP]() diff --git a/src/fundamentals/README.md b/src/fundamentals/README.md index 5d6b6bd..e0ff4e5 100644 --- a/src/fundamentals/README.md +++ b/src/fundamentals/README.md @@ -1,6 +1,2 @@ # Fundamentals -In this chapter we explore all the fundamentals that you should understand before diving deeper into XCM: -- [MultiLocation](./multilocation/index.md) -- [MultiAsset](./multiasset.md) -- [Responses](./responses.md) -- [Fees](./fees.md) \ No newline at end of file +In this chapter we explore all the fundamentals that you should understand before diving deeper into XCM. diff --git a/src/fundamentals/xcvm.md b/src/fundamentals/xcvm.md index bbdf083..83216ff 100644 --- a/src/fundamentals/xcvm.md +++ b/src/fundamentals/xcvm.md @@ -1 +1,8 @@ # XCVM + +We've already seen an overview of the XCVM. +In this section, we'll dive deeper into how it works. + +## Coming soon + +This chapter is still being worked on. diff --git a/src/journey/expects.md b/src/journey/expects.md index efa8929..3cf45f8 100644 --- a/src/journey/expects.md +++ b/src/journey/expects.md @@ -17,7 +17,9 @@ ExpectAsset(MultiAssets) ``` ### Example -For the full example, check [here](TODO). + +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). + ```rust, noplayground WithdrawAsset((Here, AMOUNT).into()), BuyExecution { fees: (Here, AMOUNT).into(), weight_limit: WeightLimit::Unlimited }, @@ -42,7 +44,8 @@ ExpectOrigin(Option) ``` ### Example -For the full example, check [here](TODO). + +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). The `ExpectOrigin` instruction errors because the `ClearOrigin` clears the origin register and we expect it to be equal to `Parachain(1)`. ```rust,noplayground // Set the instructions that are executed when ExpectOrigin does not pass. @@ -78,7 +81,7 @@ ExpectPallet { ``` ### Example -For the full example, check [here](TODO). +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). ```rust, noplayground // Set the instructions that are executed when ExpectPallet does not pass. // In this case, reporting back an error to the Parachain. @@ -108,7 +111,9 @@ The `ExpectError` instruction allows to only execute the instructions in the err ``` ### Example -For the full example, check [here](TODO). + +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). + ```rust,noplayground SetErrorHandler(Xcm(vec![ ExpectError(Some((1, XcmError::VersionIncompatible))), @@ -143,8 +148,10 @@ pub enum MaybeErrorCode { ``` ### Example -For the full example, check [here](TODO). + +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). The transact status is reported to `Parachain(1)` if the call in the `Transact` errors. + ```rust,noplayground SetErrorHandler(Xcm(vec![ReportTransactStatus(QueryResponseInfo { destination: Parachain(1).into(), diff --git a/src/journey/fees/README.md b/src/journey/fees/README.md index 73ae80f..12e2f4b 100644 --- a/src/journey/fees/README.md +++ b/src/journey/fees/README.md @@ -11,7 +11,7 @@ BuyExecution { fees: MultiAsset, weight_limit: WeightLimit } This instruction is used to buy weight using fees. While in some cases there's no need to pay for execution (if you control both systems for example), in most cases you'll need to add this instruction. -There's a predefined [barrier](../../config/barrier.md), `AllowTopLevelPaidExecutionFrom`, that explicitly drops messages that do not include this instruction. +There's a predefined [barrier](../../executor_config/index.md), `AllowTopLevelPaidExecutionFrom`, that explicitly drops messages that do not include this instruction. Let's grab the teleport message from the [transfers chapter](../transfers/teleports.md) and add fee payment. @@ -67,7 +67,7 @@ UnpaidExecution { weight_limit: WeightLimit, check_origin: Option This instruction is used for explicitly stating this message shouldn't be paid for. It can be used as a way of identifying certain priviledged messages that don't pay fees, coming from a particular system. -This instruction can be searched for in [barriers](TODO:add_link) to allow this. +This instruction can be searched for in [barriers](../../executor_config/index.md) to allow this. Make sure you trust the origin system because it won't be paying fees. There's already a predefined barrier in xcm-builder, `AllowExplicitUnpaidExecutionFrom`, that makes sure this is the first instruction in the message. As always, you can build your own for your own use-cases. @@ -85,7 +85,7 @@ Refunds any surplus weight previously bought with `BuyExecution`. This is useful in many cases: - When you pay for execution of your whole message, but there's an error and not all instructions get executed - When you set an error handler, buy weight for it, but in the end there's no error so it doesn't get called -- When you use the [`Transact` instruction]() and the call takes less weight than expected +- When you use the [`Transact` instruction](../transact.md) and the call takes less weight than expected ### Example @@ -109,4 +109,4 @@ let message = Xcm(vec![ In this example, we pay upfront for all the transactions we do later with the `DepositAsset` instructions. If any transaction throws an error (for example, due to lack of funds), the error handler will be called and the weight for all the instructions that weren't executed is refunded. -For the full example, check our [examples repo](TODO:add_link). +For the full example, check our [repo](/~https://github.com/paritytech/xcm-docs). diff --git a/src/journey/holding-modifiers.md b/src/journey/holding-modifiers.md index 78cef6f..940ba1f 100644 --- a/src/journey/holding-modifiers.md +++ b/src/journey/holding-modifiers.md @@ -11,7 +11,7 @@ BurnAsset(MultiAssets) The `BurnAsset` instruction allows for the reduction of assets in the Holding Register by up to the specified assets. The execution of the instruction does not throw an error if the Holding Register does not contain the assets (to make this an error, use `ExpectAsset` prior). ### Example -For the full example, check [here](TODO). +For the full example, check [the repo](/~https://github.com/paritytech/xcm-docs). The Scenario of the example is as follows: Parachain A withdraws 10 units from its sovereign account on the relay chain and burns 4 of them. The relay chain then reports back the status of the Holding Register to Parachain A. We expect the Holding Register to hold 6 units. @@ -53,7 +53,7 @@ and receive accordingly more assets then stated in `want`. If the `maximal` fiel order to receive as little as possible while receiving at least `want`. ### Example -The full example can be found [here](TODO). +The full example can be found in [the repo](/~https://github.com/paritytech/xcm-docs). The scenario for the example is this: Scenario: diff --git a/src/journey/locks/locks.md b/src/journey/locks/locks.md index 32a031f..9cdac59 100644 --- a/src/journey/locks/locks.md +++ b/src/journey/locks/locks.md @@ -63,7 +63,7 @@ This principle becomes more clear in the second example. ### Example 1 -Check out the full [example code](TODO). +Check out the full [example code](/~https://github.com/paritytech/xcm-docs). The scenario of this example is as follows: Parachain A locks 5 Cents of relay chain native assets of its Sovereign account on the relay chain and assigns Parachain B as unlocker. @@ -113,7 +113,7 @@ assert_eq!( ### Example 2 -Check out the full [example code](TODO). +Check out the full [example code](/~https://github.com/paritytech/xcm-docs). The scenario of this example is as follows: Parachain A sets two locks on the relay chain with as unlockers Parachain B and Parachain C. diff --git a/src/journey/origins.md b/src/journey/origins.md index 9723947..26ca91c 100644 --- a/src/journey/origins.md +++ b/src/journey/origins.md @@ -1,4 +1,5 @@ -# Origins +# Origin manipulation + An XCVM contains contextual information while executing XCM instructions. It uses the `XcmContext` struct to provide them. `XcmContext` contains information such as the origin of the corresponding XCM, the hash of the message, and the topic of the XCM. diff --git a/src/journey/queries.md b/src/journey/queries.md index 723b635..a32db8a 100644 --- a/src/journey/queries.md +++ b/src/journey/queries.md @@ -65,7 +65,9 @@ ReportHolding { response_info: QueryResponseInfo, assets: MultiAssetFilter } The `ReportHolding` instruction reports to the given destination the contents of the Holding Register. The `assets` field is a filter for the assets that should be reported back. The assets reported back will be, asset-wise, *the lesser of this value and the holding register*. For example, if the holding register contains 10 units of some fungible asset and the `assets` field specifies 15 units of the same asset, the result will return 10 units of that asset. Wild cards can be used to describe which assets in the holding register to report, but the response always contains assets and no wild cards. ### Example -For the full example, check [here](TODO). Assets are withdrawn from the account of parachain 1 on the relay chain and partly deposited in the account of parachain 2. The remaining assets are reported back to parachain 1. + +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). Assets are withdrawn from the account of parachain 1 on the relay chain and partly deposited in the account of parachain 2. The remaining assets are reported back to parachain 1. + ```rust, noplayground Xcm(vec![ WithdrawAsset((Here, AMOUNT).into()), @@ -107,7 +109,7 @@ pub struct PalletInfo { ``` ### Example -For the full example, check [here](TODO). It queries for all instances of pallet_balances and sends the result back to parachain 1. +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). It queries for all instances of pallet_balances and sends the result back to parachain 1. ```rust, noplayground Xcm(vec![ @@ -131,7 +133,7 @@ ReportError(QueryResponseInfo) ``` ### Example -For the full example, check [here](TODO). The message sets the error handler to report back any error that is thrown during execution of the instructions using the `ReportError` instruction. +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). The message sets the error handler to report back any error that is thrown during execution of the instructions using the `ReportError` instruction. ```rust, noplayground Xcm(vec![ // Set the Error Handler to report back status of Error register. @@ -154,8 +156,10 @@ ReportTransactStatus(QueryResponseInfo) ``` ### Example -For the full example, check [here](TODO). + +For the full example, check [here](/~https://github.com/paritytech/xcm-docs). Dispatches a call on the consensus system receiving this Xcm and reports back the status of the Transact Status Register. + ```rust,noplayground Xcm(vec![ Transact { diff --git a/src/journey/register-modifiers.md b/src/journey/register-modifiers.md index 20b46b2..7622a5f 100644 --- a/src/journey/register-modifiers.md +++ b/src/journey/register-modifiers.md @@ -11,13 +11,13 @@ In the previous chapters we already saw instructions that modified the XCVM regi ```rust SetErrorHandler(Xcm) ``` -The `SetErrorHandler` instructions is used to set the Error Handler Register. As discussed in the [XCVM chapter](TODO), the Error Handler is executed when an error is thrown during the regular instruction execution. +The `SetErrorHandler` instructions is used to set the Error Handler Register. As discussed in the [XCVM chapter](../fundamentals/xcvm.md), the Error Handler is executed when an error is thrown during the regular instruction execution. ## SetAppendix ```rust SetAppendix(Xcm) ``` -The `SetAppendix` instruction is used to set the Appendix Register. As discussed in the [XCVM chapter](TODO), the Appendix instructions are executed after the regular and error handler instruction are executed. These instructions are executed regardless of whether an error occurred. +The `SetAppendix` instruction is used to set the Appendix Register. As discussed in the [XCVM chapter](../fundamentals/xcvm.md), the Appendix instructions are executed after the regular and error handler instruction are executed. These instructions are executed regardless of whether an error occurred. ## ClearError ```rust diff --git a/src/journey/transact.md b/src/journey/transact.md index 80bb265..366c8d4 100644 --- a/src/journey/transact.md +++ b/src/journey/transact.md @@ -1,4 +1,5 @@ # Transact + XCM contains an instruction that allows for the execution of calls (from a `RuntimeCall` in a FRAME-based system, to a smart contract function call in an EVM-based system) in a consensus system. It is the `Transact` instruction and it looks like this: @@ -15,7 +16,7 @@ The `origin_kind` is of type [OriginKind](https://paritytech.github.io/polkadot/ In the xcm-executor, the `origin_kind` is used to determine how to convert a `MultiLocation` origin into a `RuntimeOrigin`. For more information, check out the [xcm-executor config docs](../executor_config/index.html). -The `require_weight_at_most` field tells the XCVM executing the call how much [weight](../fundamentals/fees.md) it can use. +The `require_weight_at_most` field tells the XCVM executing the call how much [weight](../fundamentals/weight_and_fees.md) it can use. If the call uses more weight than the specified `require_weight_at_most`, the execution of the call fails. The `call` field is of type `DoubleEncoded`. @@ -52,7 +53,7 @@ It executes, among other things, the following steps: ## Example 1 -For the full example, check [here](TODO). +For the full example, check [the repo](/~https://github.com/paritytech/xcm-docs). In this example, the relay chain executes the `set_balance` function of `pallet_balances` on `Parachain(1)`. This function requires the origin to be root. We enable the root origin for the relay chain by setting `ParentAsSuperuser` for the `OriginConverter` config type. @@ -77,7 +78,7 @@ let message = Xcm(vec![ ``` ## Example 2 -For the full example, check [here](TODO). +For the full example, check [the repo](/~https://github.com/paritytech/xcm-docs). In this example, as Parachain(1), we create an NFT collection on the relay chain and we then mint an NFT with ID 1. The admin for the nft collection is parachain(1). The call looks as follows: diff --git a/src/journey/transfers/README.md b/src/journey/transfers/README.md index f7d2284..536f5db 100644 --- a/src/journey/transfers/README.md +++ b/src/journey/transfers/README.md @@ -1,8 +1,8 @@ # Transfers The first feature you'll be interested in when dealing with XCM is being able to transfer assets between consensus systems. -In the [Quickstart](../../overview/README.md) section, we saw a simple XCM that when executed, would send assets between two accounts on the same consensus system. -Now that we've learnt the [fundamentals](../../fundamentals/README.md), let's go over those same instructions. +In the [quickstart](../../quickstart/index.md) chapter, we saw a simple XCM that when executed, would send assets between two accounts on the same consensus system. +Now that we've learnt the [fundamentals](../../fundamentals/index.md), let's go over those same instructions once again. ## WithdrawAsset @@ -22,7 +22,7 @@ BuyExecution { fees: MultiAssets, weight_limit: WeightLimit }, Because XCM is designed to be agnostic to the underlying consensus system, it doesn't have fee payment baked in. This instruction lets you pay for the execution of the XCM using the assets in the holding register. -Most XCMs are not allowed to be executed (blocked by the [barrier](TODO:link)) if they don't contain this instruction as one of the first ones to pay for all future ones. +Most XCMs are not allowed to be executed (blocked by the [barrier](../../executor_config/index.md)) if they don't contain this instruction as one of the first ones to pay for all future ones. ## DepositAsset @@ -47,7 +47,7 @@ let message = Xcm(vec![ ``` As we've seen, the above message results in withdrawing assets from the origin of the message, paying for execution and depositing the rest to another account on the same system. -The full example can be seen in [the examples repo](TODO:add_link). +The full example can be seen in [the repo](/~https://github.com/paritytech/xcm-docs). ## Transferring between systems diff --git a/src/journey/transfers/reserve.md b/src/journey/transfers/reserve.md index c9a6817..d6b80c2 100644 --- a/src/journey/transfers/reserve.md +++ b/src/journey/transfers/reserve.md @@ -115,7 +115,7 @@ ReserveAssetDeposited(MultiAssets) Parachain 2 receives the XCM, mints new derivative tokens and deposit them locally to the beneficiary account. `ReserveAssetDeposited` is a *trusted indication*. As is the case with teleporting, you need to trust the reserve to have actually put the specified amount of assets in the sovereign account of this system. -You can specify which systems you trust as reserves for which assets by configuring the [IsReserve](TODO:add_link) type in the executor. +You can specify which systems you trust as reserves for which assets by configuring the [IsReserve](../../executor_config/index.md) type in the executor. In our example, both parachains trust the relay chain as a reserve for its own native token. ## Another example diff --git a/src/journey/transfers/teleports.md b/src/journey/transfers/teleports.md index efedf45..3722a1d 100644 --- a/src/journey/transfers/teleports.md +++ b/src/journey/transfers/teleports.md @@ -81,7 +81,7 @@ This instruction is a *trusted indication*. It should only be executed if the or This level of care must be taken because this instruction will *put assets into the circulating supply*, usually minting them. As specified earlier, this can result in an increase/decrease in circulating supply of an asset, or a duplication/loss of an NFT, if the source is not trusted for this purpose. -You can set which origins are allowed (act as teleporters) by configuring the [IsTeleporter](TODO:add_link) type in the XCM executor. +You can set which origins are allowed (act as teleporters) by configuring the [IsTeleporter](../../executor_config/index.md) type in the XCM executor. If the origin is not allowed to teleport assets to this system, an `UntrustedTeleportLocation` error is returned. This instruction will populate the holding register with the teleported assets, which can be used by further instructions. diff --git a/src/journey/version.md b/src/journey/version.md index ff8e5e3..de3c31c 100644 --- a/src/journey/version.md +++ b/src/journey/version.md @@ -4,7 +4,7 @@ XCM is a versioned messaging format. One version may contain more or different i - `UnsubscribeVersion` The version subscription model can differ per XCVM implementation. -The `xcm-executor` has a `SubscriptionService` [config item](../executor_config/README.md). +The `xcm-executor` has a `SubscriptionService` [config item](../executor_config/index.md). Any type specified as the `SubscriptionService` must implement the `VersionChangeNotifier` trait. The XCM pallet is one such implementor. When the `SubscribeVersion` instruction is sent to a consensus system that uses the XCM pallet as the `SubscriptionService` in the XCM executor, the system will send back its currently `AdvertisedVersion` and will keep the subscribed location up to date when the version changes. @@ -20,6 +20,4 @@ SubscribeVersion { UnsubscribeVersion ``` -Check out the [example](TODO). - - +Check out the [example](/~https://github.com/paritytech/xcm-docs). diff --git a/src/overview/README.md b/src/overview/README.md index 0223581..4bd40f6 100644 --- a/src/overview/README.md +++ b/src/overview/README.md @@ -4,13 +4,18 @@ XCM allows for different consensus systems to communicate with each other. This allows things like: - Sending tokens from one chain to another - Locking assets on one chain in order to gain some benefit on a smart contract on another chain -- Calling extrinsics on another chain +- Calling functions (extrinsics) on another chain But that's just the beginning. The true power of XCM comes from its composability. Once you can communicate with other consensus systems, you can get creative and implement whatever use case you need. This is especially true in the context of an ecosystem of highly specialized chains, like Polkadot. +Decentralized distributed systems are very complex, so when building interactions between them, it's easy to make mistakes. +Because of that, the end-user is not expected to write custom XCMs from scratch for all the interactions they want to achieve. +Instead, builders will use XCM to create enticing products that provide a good and safe user experience. +This is usually done by carefully thinking and testing the interaction, then packaging it into your system's runtime logic (via an extrinsic or smart contract for example), and exposing that functionality to users. + In this chapter, we will cover what XCM is, what it isn't, why it matters, and delve into the different components that make up the XCM ecosystem. Let's begin. diff --git a/src/overview/architecture.md b/src/overview/architecture.md index bf435ce..8f45b3b 100644 --- a/src/overview/architecture.md +++ b/src/overview/architecture.md @@ -23,14 +23,17 @@ The XCM executor follows the Cross-Consensus Virtual Machine (XCVM) specificatio The XCM executor is highly configurable. XCM builder provides building blocks people can use to configure their executor according to their needs. +Many of these building blocks will be explained in the [Config Deep Dive](../executor_config/index.md) chapter. +They cover common use-cases but are not meant to be exhaustive. +It's very easy to build your own building blocks for your specific configuration when needed, using these as examples. ## Pallet -The XCM pallet is a FRAME pallet that can be used to execute XCMs locally or send them to a different system. +The XCM pallet is a [FRAME](https://docs.substrate.io/quick-start/substrate-at-a-glance/) pallet that can be used to execute XCMs locally or send them to a different system. It also has extrinsics for specific use cases such as teleporting assets or doing reserve asset transfers, which we'll talk about later. It's the glue between XCM and FRAME, which is highly used in the Polkadot ecosystem. ## Simulator The simulator allows for testing XCMs fast, without needing to boot up several different nodes in a network, or test in production. -It's a very useful tool which we'll use later to build and test different XCMs. +It's a very useful tool which we'll use throughout this document to build and test different XCMs. diff --git a/src/overview/format.md b/src/overview/format.md index d980703..da3ce0e 100644 --- a/src/overview/format.md +++ b/src/overview/format.md @@ -3,7 +3,9 @@ It's essential to understand that XCM is a format, not a protocol. It describes how messages should be structured and contains instructions relevant to the on-chain actions the message intends to perform. However, XCM does not dictate how messages are delivered. -That responsibility falls on [transport layer protocols](TODO:link) such as XCMP (Cross Chain Message Passing) and VMP (Vertical Message Passing) in the Polkadot ecosystem, or any others to come. +That responsibility falls on [transport layer protocols](../transport_protocols/index.md) such as XCMP (Cross Chain Message Passing) and VMP (Vertical Message Passing) in the Polkadot ecosystem, or any others to come. + +This separation of concerns is useful, since it allows us to think of the interactions we want to build between systems without having to think about how the messages involved are actually routed. XCM is similar to how RESTful services use REST as an architectural style of development, where HTTP requests contain specific parameters to perform some action. Similar to UDP, out of the box XCM is a "fire and forget" model, unless there is a separate XCM message designed to be a response message which can be sent from the recipient to the sender. All error handling should also be done on the recipient side. diff --git a/src/overview/interoperability.md b/src/overview/interoperability.md index 7b8ed15..3760425 100644 --- a/src/overview/interoperability.md +++ b/src/overview/interoperability.md @@ -1,7 +1,7 @@ # Introduction XCM is a messaging format, a language, designed to enable seamless communication between different consensus systems, for example blockchains and smart contracts. -XCM was originally developed for the [Polkadot](https://polkadot.network/) ecosystem, but was designed to provide a common language for cross-consensus communication that can be used anywhere. +XCM was originally developed for the [Polkadot](https://polkadot.network/) ecosystem, but was designed to be general enough to provide a common language for cross-consensus communication that can be used anywhere. XCM is a language in which interactions (programs) can be written. It aims to provide better interoperability between consensus systems, both more features and a better user and developer experience. diff --git a/src/overview/xcvm.md b/src/overview/xcvm.md index ec89f96..230ffed 100644 --- a/src/overview/xcvm.md +++ b/src/overview/xcvm.md @@ -7,17 +7,20 @@ During execution, state is tracked in domain-specific registers, and is constant Most of the XCM format comprises these registers and the instructions used to compose XCVM programs. Like XCM, the XCVM is also a specification. -The first implementation is [xcm-executor](/~https://github.com/paritytech/polkadot/tree/master/xcm/xcm-executor), provided by Parity. +The implementation that will be used in this documentation is the [xcm-executor](/~https://github.com/paritytech/polkadot/tree/master/xcm/xcm-executor), built in Rust, provided by Parity. It's built to be highly configurable, with its building blocks available in [xcm-builder](/~https://github.com/paritytech/polkadot/tree/master/xcm/xcm-builder). -Configuring the executor is an important and extensive topic, one we will dive into further in [Config Deep Dive](TODO:link). -It's entirely possible to create another implementation of the XCVM if desired. +Configuring the executor is an important and extensive topic, one we will dive into further in the [Config Deep Dive](../executor_config/index.md) chapter. + +Anyone is free to make an implementation of the XCVM. +As long as they follow the standard, they'll be able to send XCMs to systems using other implementations. +Implementations in different programming languages will need to be used to bring XCM to other ecosystems. Typically, an XCM takes the following path through the XCVM: - Instructions within an XCM are read one-by-one by the XCVM. An XCM may contain one or more instructions. - The instruction is executed. This means that the current values of the XCVM registers, the instruction type, and the instruction operands are all used to execute some operation, which might result in some registers changing their value, or in an error being thrown, which would halt execution. - Each subsequent instruction within the XCM is read until the end of the message has been reached. -The XCVM register you will hear most about is the `Holding` register. +The XCVM register you will hear most about is the `holding` register. An XCVM program that handles assets (which means most of them) will be putting them in and taking them out of this register. Instructions we'll see later like `DepositAsset`, `WithdrawAsset` and many more, make use of this register. You can see all registers in the [All XCVM Registers](TODO:link) section. diff --git a/src/quickstart/README.md b/src/quickstart/README.md index 259fe46..67839c3 100644 --- a/src/quickstart/README.md +++ b/src/quickstart/README.md @@ -3,15 +3,16 @@ The XCM code can be found in [polkadot repository](/~https://github.com/paritytech/polkadot/tree/master/xcm). ## Rust & Cargo -A pre-requisite for using XCM is to have a stable Rust version and Cargo installed. Here's an [installation guide](https://docs.substrate.io/install/) on how to install rust and cargo. +A pre-requisite for using XCM is to have a stable Rust version and Cargo installed. Here's an [installation guide](https://docs.substrate.io/install/). ## Running the Examples -All examples in the documentation are located in the [examples repository](). Follow these steps to run the `first-look` example. First clone the repository: +All examples in the documentation are located in the [repository](/~https://github.com/paritytech/xcm-docs). Follow these steps to run the `first-look` example. +First clone the repository: ```shell -git clone git@github.com:vstam1/xcm-examples.git -cd xcm-examples +git clone git@github.com:paritytech/xcm-docs.git +cd xcm-docs/examples ``` To run the first-look example, run the following line: diff --git a/src/quickstart/first-look.md b/src/quickstart/first-look.md index 98d4471..cecae90 100644 --- a/src/quickstart/first-look.md +++ b/src/quickstart/first-look.md @@ -1,5 +1,6 @@ # First Look -In this section, we take you through a simple example of an XCM. In this example, we withdraw the native token from the account of Alice and deposit this token in the account of Bob. This message simulates a transfer between two accounts in the same consensus system (`ParaA`). Find here the [code example](). +In this section, we take you through a simple example of an XCM. In this example, we withdraw the native token from the account of Alice and deposit this token in the account of Bob. This message simulates a transfer between two accounts in the same consensus system (`ParaA`). You can find the complete code example [in the repo](/~https://github.com/paritytech/xcm-docs). + ## Message ```rust,noplayground let message = Xcm(vec![ @@ -17,21 +18,29 @@ In this section, we take you through a simple example of an XCM. In this example } ]); ``` -The message consists of three instructions: WithdrawAsset, BuyExecution, and DepositAsset. In the following sections we will go over each of these instructions. + +The message consists of three instructions: `WithdrawAsset`, `BuyExecution`, and `DepositAsset`. +In the following sections we will go over each instruction. ### WithdrawAsset ```rust WithdrawAsset((Here, amount).into()) ``` -The first instruction takes as an input the [MultiAsset]() that should be withdrawn. The MultiAsset describes the native parachain token with the `Here` keyword. The `amount` parameter is the number of tokens that are transferred. The withdrawal account depends on the Origin of the message. In this example the Origin of the message is Alice. -The WithdrawAsset instruction moves `amount` number of native tokens from Alice's account into the `Holding register`. +The first instruction takes as an input the [MultiAsset]() that should be withdrawn. The MultiAsset describes the native parachain token with the `Here` keyword. The `amount` parameter is the number of tokens that are transferred. The withdrawal account depends on the origin of the message. In this example the origin of the message is Alice. +The WithdrawAsset instruction moves `amount` number of native tokens from Alice's account into the _holding register_. ### BuyExecution ```rust BuyExecution{fees: (Here, amount).into(), weight_limit: WeightLimit::Unlimited} ``` -To execute XCM instructions, weight (some kind of resources) has to be bought. The amount of weight depends on the number and type of instructions in the XCM. The `BuyExecution` instruction pays for the weight using the `fees`. The `fees` parameter describes the asset in the `Holding register` that should be used for paying for the weight. The `weight_limit` defines the maximum amount of fees that can be used for buying weight. There are special occasions where it is not necessary to buy weight. See [fees]() for more information about the fees in XCM. +To execute XCM instructions, weight (some amount of resources) has to be bought. +The amount of weight needed to execute an XCM depends on the number and type of instructions in the XCM. +The `BuyExecution` instruction pays for the weight using the `fees`. +The `fees` parameter describes the asset in the _holding register_ that should be used for paying for the weight. +The `weight_limit` parameter defines the maximum amount of fees that can be used for buying weight. +There are special occasions where it is not necessary to buy weight. +See the chapter on [weight and fees](../fundamentals/weight_and_fees.md) for more information about the fees in XCM. ### DepositAsset ```rust @@ -46,13 +55,17 @@ DepositAsset { }.into() } ``` -The DepositAsset instruction is used to deposit funds from the holding register into the account of the `beneficiary`. We don’t actually know how much is remaining in the Holding Register after the BuyExecution instruction, but that doesn’t matter since we specify a wildcard for the asset(s) which should be deposited. In this case, the wildcard is `All`, meaning that all assets in the Holding register should be deposited. The `beneficiary` in this case is the account of Bob in the current consensus system. - -When the three instructions are combined, we withdraw `amount` native tokens from the account of Alice, pay for the execution of the instructions, and deposit the remaining tokens in the account of Bob. +The DepositAsset instruction is used to deposit funds from the holding register into the account of the _beneficiary_. +We don’t actually know how much is remaining in the holding register after the `BuyExecution` instruction, but that doesn’t matter since we specify a wildcard for the asset(s) which should be deposited. +In this case, the wildcard is `All`, meaning that all assets in the holding register at that point in the execution should be deposited. +The _beneficiary_ in this case is the account of Bob in the current consensus system. +When the three instructions are combined, we withdraw `amount` native tokens from the account of Alice, pay for the execution of these instructions, and deposit the remaining tokens in the account of Bob. ## What next? -Now that we have taken a first look at an XCM, we can dive deeper into all the XCM instructions. -For an overview of the instructions check out the [xcm-format](/~https://github.com/paritytech/xcm-format#5-the-xcvm-instruction-set). -Or check out examples for each of the instruction in [A Journey through XCM](). -To get a better understanding about MultiLocations, MultiAssets, and other fundamental concepts in XCM, check out the [fundamentals chapter](fundamentals/README.md). + +Now that we have taken a first look at an XCM, we can dive deeper into all the XCM instructions, to be able to build more complex XCVM programs. +For an overview of the instructions check out the [xcm-format repo](/~https://github.com/paritytech/xcm-format#5-the-xcvm-instruction-set). +We'll show examples for every instruction in the [journey through XCM](../journey/index.md) chapter. +First, it's important to learn the fundamentals, `MultiLocation`, `MultiAsset`, and other concepts in XCM. +We'll talk about those next. diff --git a/src/quickstart/xcm-simulator.md b/src/quickstart/xcm-simulator.md index 178bb77..fbb6b1e 100644 --- a/src/quickstart/xcm-simulator.md +++ b/src/quickstart/xcm-simulator.md @@ -1,13 +1,11 @@ # XCM Simulator -Setting up a live network with multiple connected parachains for testing XCM is not straight forward. The `XCM-simulator` was created as a solution to this problem. The XCM-simulator is a network simulator specifically designed for testing and playing around with XCM. It uses mock relay chain and parachain runtime. - -For testing xcm configurations for live runtime environments we use the `XCM-emulator`. The XCM-emulator can use production relay chain and parachain runtimes. Users can plug in Kusama, Statemine, or their custom runtime etc. With up-to-date chain specs, it's able to verify if specific XCM messages work in live networks. The specific use cases will be further explained in the chapter on [testing](testing/README.md). - -In the next section we will take a first look at an XCM. The XCM-simulator is used for the example code. - -[Next: First Look at an XCM](first-look.md) - - - +Setting up a live network with multiple connected parachains for testing XCM is not straight forward. +The `xcm-simulator` was created as a solution to this problem. +It's a network simulator specifically designed for testing and tinkering with XCM. +It uses mock runtimes for a relay chain and parachains. +Although it's a great tool to learn and test XCMs, it shouldn't be the only thing you use to actually test your XCM-powered solution. +We'll get into tools and best practices for testing in the [testing](../testing/index.md) chapter. +We'll use the simulator throughout the documentation to show different XCMs in action. +In the next section we will take a first look at an XCM. diff --git a/src/testing/README.md b/src/testing/README.md new file mode 100644 index 0000000..1c05856 --- /dev/null +++ b/src/testing/README.md @@ -0,0 +1,13 @@ +# Testing + +Before deploying your XCM-powered solution to production, it's paramount to test it thoroughly. +There are different levels for testing, which should be tackled sequentially: +- Message: Making sure your message works properly, according to the XCVM spec. +- Configuration: Making sure your executor's configuration is as expected. +- End-to-end: Making sure the whole flow works, in an environment as similar to production as possible. + +We'll discuss tools and best practices for each of these levels. + +## Coming soon + +This chapter is still being worked on. diff --git a/src/transport_protocols/README.md b/src/transport_protocols/README.md new file mode 100644 index 0000000..97a5a22 --- /dev/null +++ b/src/transport_protocols/README.md @@ -0,0 +1,8 @@ +# Transport Protocols + +When building a tool or product using XCM, you usually don't need to concern yourself with the transport protocols used to actually route the messages between systems. +However, if you need to learn about them or are just curious about how they work, we'll detail the existing ones in the Dotsama ecosystem. + +## Coming soon + +This chapter is still being worked on. diff --git a/src/xcm.md b/src/xcm.md index fd5f0e9..c32eee3 100644 --- a/src/xcm.md +++ b/src/xcm.md @@ -1,9 +1,10 @@ # XCM: Cross-Consensus Messaging -This is the place where we will brainstorm XCM documentation and tutorial ideas. -It will eventually be in a public centralized place for everyone to find and use. +Welcome to the XCM documentation! +Whether you're a developer, a blockchain enthusiast, or just interested in Polkadot, this guide aims to provide you with an easy-to-understand and comprehensive introduction to XCM. -## Draft intro +## Still under development -Welcome to the Cross-Consensus Message Format (XCM) documentation! -Whether you're a developer, a blockchain enthusiast, or just interested in Polkadot, this guide aims to provide you with an easy-to-understand and comprehensive introduction to XCM. +Keep in mind this documentation is still a work in progress. +We'll be polishing it and adding more content. +If there's anything in particular you'd like to see, or any pressing concern, please [open an issue](/~https://github.com/paritytech/xcm-docs/issues).