Skip to content

Commit

Permalink
Fix minor typos. (CosmWasm#1938)
Browse files Browse the repository at this point in the history
  • Loading branch information
xavierlepretre authored Jul 22, 2024
1 parent c7e5a97 commit 41c2172
Showing 1 changed file with 16 additions and 14 deletions.
30 changes: 16 additions & 14 deletions INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

If you want to use Wasm in your own app, here is how you can get this working
quickly and easily.
First start with This [article](https://medium.com/cosmwasm/cosmwasm-for-ctos-iv-native-integrations-713140bf75fc)
First start with this [article](https://medium.com/cosmwasm/cosmwasm-for-ctos-iv-native-integrations-713140bf75fc)
in the "CosmWasm for CTOs" series that gives you a high level view.
Then check to make sure you fit the pre-requisites,
then integrate the `x/wasm` module as described below, and finally, you
Expand Down Expand Up @@ -41,14 +41,14 @@ hardware it runs on.

We currently only support Intel/AMD64 CPUs and OSX or Linux. For Linux, the standard build
commands work for `glibc` systems (Ubuntu, Debian, CentOS, etc). If you wish to compile
for a `muslc` based system (like alpine), you need to compile a static library wasmvm locally
for a `muslc` based system (like Alpine), you need to compile the static library `wasmvm` locally
and compile go with the `muslc` build tag. Or just use the [Dockerfile](./Dockerfile),
which builds a static go binary in an alpine system.
which builds a static go binary in an Alpine system.

This limit comes from the Rust dll we use to run the wasm code, which comes
from [`wasmvm`](https://github.com/CosmWasm/wasmvm). There are open issues
for adding [ARM support](https://github.com/CosmWasm/wasmvm/issues/53), and
adding [Windows support](https://github.com/CosmWasm/wasmvm/issues/28).
[Windows support](https://github.com/CosmWasm/wasmvm/issues/28).
However, these issues are not high on the roadmap and unless you are championing
them, please count on the current limits for the near future.

Expand All @@ -60,15 +60,15 @@ plenty that can be done there, and lots to learn.

Once you are happy with it and want to use a custom Cosmos SDK app,
you may consider simply forking `wasmd`. *I highly advise against this*.
You should try one of the methods below.
Instead you should try one of the methods below.

## Integrating wasmd

### As external module

The simplest way to use `wasmd` is just to import `x/wasm` and wire it up
in `app.go`. You now have access to the whole module and you custom modules
running side by side. (But the CosmWasm contracts will only have access
in `app.go`. You now have access to the whole module and your custom modules
running side by side. (But the CosmWasm contracts will still only have access
to `bank` and `staking`... more below on [customization](#Adding-Custom-Hooks)).

The requirement here is that you have imported the standard sdk modules
Expand Down Expand Up @@ -133,6 +133,8 @@ to check balances.
If you look at the unit tests in [`x/wasm/internal/keeper`](https://github.com/CosmWasm/wasmd/tree/master/x/wasm/internal/keeper),
it should be pretty straight forward.

<!-- TODO dead link above -->

### Extending the Contract Interface

If you want to let the contracts access your native modules, the first
Expand All @@ -141,7 +143,7 @@ and then add them as `CosmosMsg::Custom` and `QueryRequest::Custom`
variants. You can see an example of the [bindings for Terra](https://github.com/CosmWasm/terra-contracts/tree/master/packages/bindings).

Once you have those bindings, use them to build a
[simple contact using much of the API](https://github.com/CosmWasm/terra-contracts/tree/master/contracts/maker).
[simple contract using much of the API](https://github.com/CosmWasm/terra-contracts/tree/master/contracts/maker).
Don't worry too much about the details, this should be usable, but mainly
you will want to upload it to your chain and use for integration tests
with your native Cosmos SDK modules. Once that is solid, then add more
Expand All @@ -153,7 +155,7 @@ the contracts (provide static data for exchange rates when your contracts
query it). You can see an example of [mocks for Terra contracts](https://github.com/CosmWasm/terra-contracts/tree/master/packages/mocks).

What these three steps provide is basically a chain-specific extension to the CosmWasm contract SDK.
Any CosmWasm contract can import you library (bindings and mocks) and easily get started using
Any CosmWasm contract can import your library (bindings and mocks) and easily get started using
your custom, chain-specific extensions just as easily as using the standard CosmWasm interfaces.
What is left is actually wiring them up in your chain so they work as desired.

Expand All @@ -163,25 +165,25 @@ mean that only blockchain apps that explicitly declare their support for the `XY
(please rename XYZ to your project name) will allow the contract to be uploaded, and others
get error messages upon upload, not while running a critical feature later on.
You just need to add [a line like this](https://github.com/CosmWasm/terra-contracts/blob/master/packages/bindings/src/lib.rs#L13-L16)
to your binding library to add the requirement to any contract that imports your `bindings` lib.
to your bindings library to add the requirement to any contract that imports your `bindings` lib.

### Calling into the SDK

Before I show how this works, I want to remind you, if you have copied `x/wasm`,
please **do not make these changes to `x/wasm`**.

We will add a new module, eg. `x/contracts`, that will contain custom
We will add a new module, e.g. `x/contracts`, that will contain custom
bindings between CosmWasm contracts and your native modules. There are two entry points
for you to use. The first is
[`CustomQuerier`](https://github.com/CosmWasm/wasmd/blob/v0.8.0-rc1/x/wasm/internal/keeper/query_plugins.go#L35),
which allows you to handle your custom queries. The second is
[`CustomEncoder`](https://github.com/CosmWasm/wasmd/blob/v0.8.0-rc1/x/wasm/internal/keeper/handler_plugin.go#L30)
[`CustomEncoder`](https://github.com/CosmWasm/wasmd/blob/v0.8.0-rc1/x/wasm/internal/keeper/handler_plugin.go#L30),
which allows you to convert the `CosmosMsg::Custom(YourMessage)` types to `[]sdk.Msg` to be dispatched.

Writing stubs for these is rather simple. You can look at the `reflect_test.go` file to see this in action.
In particular, here [we define a `CustomQuerier`](https://github.com/CosmWasm/wasmd/blob/v0.8.0-rc1/x/wasm/internal/keeper/reflect_test.go#L355-L385),
and here [we define a `CustomHandler`](https://github.com/CosmWasm/wasmd/blob/v0.8.0-rc1/x/wasm/internal/keeper/reflect_test.go#L303-L353).
This code is responsible to take `json.RawMessage` from the raw bytes serialized from your custom types in rust and parse it into
This code is responsible to take `json.RawMessage` from the raw bytes serialized from your custom types in Rust and parse it into
Go structs. Then take these go structs and properly convert them for your custom SDK modules.

You can look at the implementations for the `staking` module to see how to build these for non-trivial
Expand All @@ -196,7 +198,7 @@ should properly name the JSON fields and use the `omitempty` keyword if Rust exp

### Wiring it all together

Once you have writen and tested these custom callbacks for your module, you need to enable it in your application.
Once you have written and tested these custom callbacks for your module, you need to enable it in your application.
The first step is to write an integration test with a contract compiled with your custom SDK to ensure it works properly,
then you need to configure this in `app.go`.

Expand Down

0 comments on commit 41c2172

Please sign in to comment.