From e7b6f75f815d6b654cfeb75936d69a3591408f04 Mon Sep 17 00:00:00 2001 From: Dariusz Depta Date: Fri, 31 Jan 2025 14:31:13 +0100 Subject: [PATCH 1/2] Added Api documentation. --- src/pages/cw-multi-test/_meta.js | 1 + src/pages/cw-multi-test/api.mdx | 86 ++++++++++++++++++ src/pages/cw-multi-test/app-builder.mdx | 114 ++++++++++++++++++++++-- src/pages/cw-multi-test/features.mdx | 2 +- 4 files changed, 197 insertions(+), 6 deletions(-) create mode 100644 src/pages/cw-multi-test/api.mdx diff --git a/src/pages/cw-multi-test/_meta.js b/src/pages/cw-multi-test/_meta.js index 20a531f6..f209929d 100644 --- a/src/pages/cw-multi-test/_meta.js +++ b/src/pages/cw-multi-test/_meta.js @@ -5,5 +5,6 @@ export default { app: "App", "app-builder": "AppBuilder", blocks: "Blocks", + api: "Api", addresses: "Addresses", }; diff --git a/src/pages/cw-multi-test/api.mdx b/src/pages/cw-multi-test/api.mdx new file mode 100644 index 00000000..53a2dbe6 --- /dev/null +++ b/src/pages/cw-multi-test/api.mdx @@ -0,0 +1,86 @@ +--- +tags: ["multitest", "Api"] +--- + +[Api]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html +[addr_canonicalize]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.addr_canonicalize +[addr_humanize]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.addr_humanize +[addr_validate]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.addr_validate +[secp256k1_verify]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.secp256k1_verify +[secp256k1_recover_pubkey]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.secp256k1_recover_pubkey +[secp256r1_verify]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.secp256r1_verify +[secp256r1_recover_pubkey]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.secp256r1_recover_pubkey +[ed25519_verify]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.ed25519_verify +[ed25519_batch_verify]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.ed25519_batch_verify +[bls12_381_aggregate_g1]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.bls12_381_aggregate_g1 +[bls12_381_aggregate_g2]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.bls12_381_aggregate_g2 +[bls12_381_pairing_equality]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.bls12_381_pairing_equality +[bls12_381_hash_to_g1]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.bls12_381_hash_to_g1 +[bls12_381_hash_to_g2]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#method.bls12_381_hash_to_g2 +[debug]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html#tymethod.debug +[MockApi]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html +[MockApiBech32]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.MockApiBech32.html +[MockApiBech32m]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.MockApiBech32m.html + +# Api + +**`MultiTest`** provides three implementations of the [Api][Api] trait: + +- [`cosmwasm_std::testing::MockApi{:rust}`][MockApi], +- [`cw_multi_test::MockApiBech32{:rust}`][MockApiBech32], +- [`cw_multi_test::MockApiBech32m{:rust}`][MockApiBech32m]. + +Additionally, [`MockApi{:rust}`][MockApi], [`MockApiBech32{:rust}`][MockApiBech32] and +[`MockApiBech32m{:rust}`][MockApiBech32m] implement `addr_make{:rust}` method, allowing for +convenient creation of user addresses in tests. You can find multiple examples of `addr_make{:rust}` +method usage in the [Addresses](addresses/user-address#app) chapter. Depending on your needs, you +can use any implementation of the [Api][Api] trait in your tests by utilizing the +[`AppBuilder::with_api{:rust}`](app-builder#with_api) method to create a chain simulator. + +## `Api` trait + +The table below summarizes all methods of the [Api][Api] trait with short descriptions: + +| Methods of [Api][Api] trait | Description | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`addr_canonicalize{:rust}`][addr_canonicalize] | Converts a human-readable address into its canonical binary representation. | +| [`addr_humanize{:rust}`][addr_humanize] | Converts a canonical address into human-readable address. | +| [`addr_validate{:rust}`][addr_validate] | Checks if the human-readable address is valid. | +| [`secp256k1_verify{:rust}`][secp256k1_verify] | Verifies a message hash against a signature, with the public key of the signer, using the **secp256k1** elliptic curve digital signature algorithm. | +| [`secp256k1_recover_pubkey{:rust}`][secp256k1_recover_pubkey] | Recovers a public key from a message hash and a signature in compressed form, which can be used in `secp256k1_verify` directly. | +| [`secp256r1_verify{:rust}`][secp256r1_verify] | Verifies a message hash against a signature, with the public key of the signer, using the **secp256r1** elliptic curve digital signature algorithm. | +| [`secp256r1_recover_pubkey{:rust}`][secp256r1_recover_pubkey] | Recovers a public key from a message hash and a signature in compressed form, which can be used in `secp256r1_verify` directly. | +| [`ed25519_verify{:rust}`][ed25519_verify] | Verifies message against a signature, with the public key of the signer, using the **ed25519** elliptic curve digital signature algorithm. | +| [`ed25519_batch_verify{:rust}`][ed25519_batch_verify] | Performs batch **ed25519** signature verification. | +| [`bls12_381_aggregate_g1{:rust}`][bls12_381_aggregate_g1] | Takes a list of points in G1 (48 bytes each) and aggregates them. | +| [`bls12_381_aggregate_g2{:rust}`][bls12_381_aggregate_g2] | Takes a list of points in G2 (96 bytes each) and aggregates them. | +| [`bls12_381_pairing_equality{:rust}`][bls12_381_pairing_equality] | (description needed, see [\#2368](https://github.com/CosmWasm/cosmwasm/issues/2368)) | +| [`bls12_381_hash_to_g1{:rust}`][bls12_381_hash_to_g1] | (description needed, see [\#2368](https://github.com/CosmWasm/cosmwasm/issues/2368)) | +| [`bls12_381_hash_to_g2{:rust}`][bls12_381_hash_to_g2] | (description needed, see [\#2368](https://github.com/CosmWasm/cosmwasm/issues/2368)) | +| [`debug{:rust}`][debug] | Emits a debugging message. | + +## `Api` trait implementations + +A concise comparison of different [Api][Api] trait implementations is shown in the table below: + +| | MockApi | MockApiBech32 | MockApiBech32m | +| ------------------------------------------ | :--------: | :-----------: | :------------: | +| Implements [Api][Api] trait | Yes | Yes | Yes | +| Implements **`addr_make{:rust}`** function | Yes | Yes | Yes | +| Address format | Bech32 | Bech32 | Bech32m | +| Default prefix (HRP) | `cosmwasm` | No | No | +| Supports custom prefixes | Yes | Yes | Yes | diff --git a/src/pages/cw-multi-test/app-builder.mdx b/src/pages/cw-multi-test/app-builder.mdx index 71f361a6..e7c9e64a 100644 --- a/src/pages/cw-multi-test/app-builder.mdx +++ b/src/pages/cw-multi-test/app-builder.mdx @@ -4,18 +4,26 @@ tags: ["multitest", "AppBuilder"] import { Callout } from "nextra/components"; +[Api]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/trait.Api.html [App]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html [AppBuilder]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html +[build]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.build [Builder Pattern]: https://en.wikipedia.org/wiki/Builder_pattern [BlockInfo]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.BlockInfo.html +[GovAcceptingModule]: + https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovAcceptingModule.html +[GovFailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovFailingModule.html +[MockApi]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html +[MockApiBech32]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.MockApiBech32.html +[MockApiBech32m]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.MockApiBech32m.html +[with_api]: + https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_api [with_block]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_block [with_gov]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_gov -[build]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.build -[GovAcceptingModule]: - https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovAcceptingModule.html -[GovFailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovFailingModule.html +[addr_make]: + https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html#method.addr_make # `AppBuilder` @@ -71,7 +79,103 @@ assert!(sender_addr.as_str().starts_with("cosmwasm1")); ## `with_api` -(WIP) +The default [`Api{:rust}`][Api] trait implementation used in [`AppBuilder{:rust}`][AppBuilder] is +[`cosmwasm_std::testing::MockApi{:rust}`][MockApi] provided by CosmWasm library. Besides other +functionalities described in detail in the [API](api) chapter, the [`MockApi{:rust}`][MockApi] +provides a function [`addr_make{:rust}`][addr_make] for generating user addresses in **Bech32** +format with the `cosmwasm` prefix. An example usage is shown below. + +```rust showLineNumbers copy {7} /api()/ /addr_make/ /cosmwasm/ +use cw_multi_test::{no_init, AppBuilder}; + +// Create the chain with default Api implementation. +let app = AppBuilder::default().build(no_init); + +// Create the address using default Api. +let sender_addr = app.api().addr_make("sender"); + +// Default Api generates Bech32 addresses with prefix 'cosmwasm'. +assert_eq!( + "cosmwasm1pgm8hyk0pvphmlvfjc8wsvk4daluz5tgrw6pu5mfpemk74uxnx9qlm3aqg", + sender_addr.as_str() +); +``` + +If you need to test contracts on your own chain that uses a specific Bech32 prefixes, you can easily +customize the default [`MockApi{:rust}`][MockApi] behavior using the +[`AppBuilder::with_api{:rust}`][with_api] method. An example of using `osmo` prefixes is shown in +the following code snippet. + +```rust showLineNumbers copy {1,6} /with_api/ /osmo/ +use cosmwasm_std::testing::MockApi; +use cw_multi_test::{no_init, AppBuilder}; + +// Create the chain with customized default Api implementation. +let app = AppBuilder::default() + .with_api(MockApi::default().with_prefix("osmo")) + .build(no_init); + +// Create the address using customized Api. +let sender_addr = app.api().addr_make("sender"); + +// This customized Api generates Bech32 addresses with prefix 'osmo'. +assert_eq!( + "osmo1pgm8hyk0pvphmlvfjc8wsvk4daluz5tgrw6pu5mfpemk74uxnx9qcrt3u2", + sender_addr.as_str() +); +``` + +**`MultiTest`** provides two additional implementations of the [`Api{:rust}`][Api] trait: +[`MockApiBech32{:rust}`][MockApiBech32] and [`MockApiBech32m{:rust}`][MockApiBech32m]. You can use +them in your tests by providing their instances to [`AppBuilder::with_api{:rust}`][with_api] method. + +An example of using [`MockApiBech32{:rust}`][MockApiBech32] with custom prefix: + +```rust showLineNumbers copy {1,6} /with_api/ /juno/ +use cw_multi_test::MockApiBech32; +use cw_multi_test::{no_init, AppBuilder}; + +// Create the chain with Bech32 Api implementation. +let app = AppBuilder::default() + .with_api(MockApiBech32::new("juno")) + .build(no_init); + +// Create the address using Bech32 Api. +let sender_addr = app.api().addr_make("sender"); + +// This Api generates Bech32 addresses with prefix 'juno'. +assert_eq!( + "juno1pgm8hyk0pvphmlvfjc8wsvk4daluz5tgrw6pu5mfpemk74uxnx9qwm56ug", + sender_addr.as_str() +); +``` + +An example of using [`MockApiBech32m{:rust}`][MockApiBech32m] with custom prefix: + +```rust showLineNumbers copy {1,6} /with_api/ /juno/ +use cw_multi_test::MockApiBech32m; +use cw_multi_test::{no_init, AppBuilder}; + +// Create the chain with Bech32m Api implementation. +let app = AppBuilder::default() + .with_api(MockApiBech32m::new("juno")) + .build(no_init); + +// Create the address using Bech32m Api. +let sender_addr = app.api().addr_make("sender"); + +// This Api generates Bech32m addresses with prefix 'juno'. +assert_eq!( + "juno1pgm8hyk0pvphmlvfjc8wsvk4daluz5tgrw6pu5mfpemk74uxnx9qm8yke2", + sender_addr.as_str() +); +``` + + + More details about the available [`Api{:rust}`][Api] implementations are in the [API](api) chapter. + If needed, you can provide your own implementation of the [`Api{:rust}`][Api] trait and + use it in your tests by utilizing the `with_api{:rust}` method of the `AppBuilder{:rust}`. + ## `with_bank` diff --git a/src/pages/cw-multi-test/features.mdx b/src/pages/cw-multi-test/features.mdx index fde01b49..d83ce591 100644 --- a/src/pages/cw-multi-test/features.mdx +++ b/src/pages/cw-multi-test/features.mdx @@ -18,7 +18,7 @@ in the column **Feature flag**. | Feature | Default
implementation | Feature
flag | AppBuilder
constructor | Functionality | | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | :--------------: | ---------------------------------------------------- | -------------------------------------------------- | | [Blocks](blocks) | [`mock_env().block{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/fn.mock_env.html) | | [`with_block`](app-builder#with_block) | Operations on blocks. | -| API | [`MockApi{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html) | | [`with_api`](app-builder#with_api) | Access to CosmWasm API. | +| [Api](api) | [`MockApi{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html) | | [`with_api`](app-builder#with_api) | Access to CosmWasm API. | | Storage | [`MockStorage{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html) | | [`with_storage`](app-builder#with_storage) | Access to storage. | | Bank | [`BankKeeper{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.BankKeeper.html) | | [`with_bank`](app-builder#with_bank) | Interactions with **Bank** module. | | Staking | [`StakeKeeper{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StakeKeeper.html) | `staking` | [`with_staking`](app-builder#with_staking) | Interactions with **Staking** module. | From b6ce917958484296a33d5ecf02f28b796de618fd Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Sat, 1 Feb 2025 11:50:39 +0000 Subject: [PATCH 2/2] [autofix.ci] apply automated fixes --- src/pages/cw-multi-test/blocks.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/cw-multi-test/blocks.mdx b/src/pages/cw-multi-test/blocks.mdx index 0f236dff..8ca561aa 100644 --- a/src/pages/cw-multi-test/blocks.mdx +++ b/src/pages/cw-multi-test/blocks.mdx @@ -218,7 +218,7 @@ assert_eq!("cosmos-testnet-14002", block.chain_id); In line 4, the default block is initialized during the chain start. Then in line 7, the [`update_block{:rust}`][update_block] method takes a custom closure as an argument. This closure increments the block height by **10000** and advances the block time by **6 days**. Similarly like -in previous examples, the new block metadata is retrieved and the current properties are checked. The -new block height should be `12345{:rust}` + `10000{:rust}` = `22345{:rust}`. The new block time +in previous examples, the new block metadata is retrieved and the current properties are checked. +The new block height should be `12345{:rust}` + `10000{:rust}` = `22345{:rust}`. The new block time should be `1572315819879305533{:rust}` -`1571797419879305533{:rust}` = `518400000000000{:rust}` = 518400 seconds = 8640 minutes = 144 hours = **6 days**. The chain identifier remains unchanged.