mleku/wasmd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix minor typos. (#1938)

Browse Source
This commit is contained in:
Xavier Leprêtre
2024-07-22 15:11:51 +04:00
committed by GitHub
parent c7e5a97830
commit 41c217284e
1 changed files with 16 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
INTEGRATION.md
View File

@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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`.