Added Api and AppBuilder::with_api documentation (#242)

CosmWasm · Feb 3, 2025 · 82514f0 · 82514f0
2 parents 8428832 + b6ce917
commit 82514f0
Show file tree

Hide file tree

Showing 5 changed files with 199 additions and 8 deletions.
diff --git 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
@@ -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
@@ -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()
+);
+```
+
+<Callout>
+  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}`.
+</Callout>
 
 ## `with_bank`
 

diff --git 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.
diff --git a/src/pages/cw-multi-test/features.mdx b/src/pages/cw-multi-test/features.mdx
@@ -18,7 +18,7 @@ in the column **Feature&nbsp;flag**.
 | Feature                  | Default<br/>implementation                                                                                       | Feature<br/>flag | AppBuilder<br/>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.              |