CosmWasm 1.2 updates in MIGRATING and cosmwasm-std usage

MIGRATING.md

@@ -4,6 +4,47 @@ This guide explains what is needed to upgrade contracts when migrating over
 major releases of `cosmwasm`. Note that you can also view the
 [complete CHANGELOG](./CHANGELOG.md) to understand the differences.
 
+## 1.1.x -> 1.2.0
+
+- Update `cosmwasm-*` dependencies in Cargo.toml (skip the ones you don't use):
+
+  ```
+  [dependencies]
+  cosmwasm-std = "1.2.0"
+  cosmwasm-storage = "1.2.0"
+  # ...
+
+  [dev-dependencies]
+  cosmwasm-schema = "1.2.0"
+  cosmwasm-vm = "1.2.0"
+  # ...
+  ```
+
+- If you want to use a fewture that os only available on CosmWasm 1.2+ chains,
+  use this feature:
+
+  ```diff
+  -cosmwasm-std = { version = "1.1.0", features = ["stargate"] }
+  +cosmwasm-std = { version = "1.1.0", features = ["stargate", "cosmwasm_1_2"] }
+  ```
+
+  Please note that `cosmwasm_1_2` implies `cosmwasm_1_1`, so there is no need to
+  set both.
+
+- If you use mixed type multiplication between `Uint{64,128,256}` and
+  `Decimal{,256}`, check out
+  `mul_floor`/`checked_mul_floor`/`mul_ceil`/`checked_mul_ceil`. Mixed type
+  arithmetic [will be removed](https://github.com/CosmWasm/cosmwasm/issues/1485)
+  at some point.
+
+  ```diff
+  let a = Uint128::new(123);
+  let b = Decimal::percent(150)
+
+  -let c = a * b;
+  +let c = a.mul_floor(b);
+  ```
+
 ## 1.0.0 -> 1.1.0
 
 - Update `cosmwasm-*` dependencies in Cargo.toml (skip the ones you don't use):

docs/USING_COSMWASM_STD.md

@@ -0,0 +1,89 @@
+# Using cosmwasm-std
+
+cosmwasm-std is the standard library for building contracts in CosmWasm. It is
+compiled as part of the contract to Wasm. When creating a dependency to
+cosmwasm-std, the required Wasm imports and exports are created implicitely via
+C interfaces, e.g.:
+
+```rust
+// Exports
+#[no_mangle]
+extern "C" fn interface_version_8() -> () { /* ... */ }
+#[no_mangle]
+extern "C" fn allocate(size: usize) -> u32 { /* ... */ }
+#[no_mangle]
+extern "C" fn deallocate(pointer: u32) { /* ... */ }
+
+// Imports
+extern "C" {
+    #[cfg(feature = "abort")]
+    fn abort(source_ptr: u32);
+
+    fn db_read(key: u32) -> u32;
+    fn db_write(key: u32, value: u32);
+    fn db_remove(key: u32);
+
+    /* ... */
+}
+```
+
+As those exports are not namespaced, only one version of cosmwasm-std must exist
+in the dependency tree. Otherwise conflicting C exports are created.
+
+## cosmwasm-std features
+
+The libarary comes with the following features:
+
+| Feature      | Enabled by default | Description                                                                |
+| ------------ | ------------------ | -------------------------------------------------------------------------- |
+| iterator     | x                  | Storage iterators                                                          |
+| abort        | x                  | A panic handler that aborts the contract execution with a helpfull message |
+| stargate     |                    | Cosmos SDK 0.40+ features and IBC                                          |
+| ibc3         |                    | New fields added in IBC v3                                                 |
+| staking      |                    | Access to the staking module                                               |
+| baktraces    |                    | Add backtraces to errors (for unit testing)                                |
+| cosmwasm_1_1 |                    | Features that require CosmWasm 1.1+ on the chain                           |
+| cosmwasm_1_2 |                    | Features that require CosmWasm 1.2+ on the chain                           |
+
+## The cosmwasm-std dependency for contract developers
+
+As a contract developer you can simply specify the dependency as follows in
+`Cargo.toml`:
+
+```toml
+cosmwasm-std = { version = "1.2.0" }
+```
+
+Please note that it is recommended to set all 3 version components and use the
+minimum version you are willing to accept in the contract. For contracts this
+would usually be the latest stable version.
+
+Most likely you also want to enable the `stargate`, which is pretty basic these
+days and maybe you know your chain supports CosmWasm 1.2 or higher. Then you add
+those features:
+
+```toml
+cosmwasm-std = { version = "1.2.0", features = ["stargate", "cosmwasm_1_2"] }
+```
+
+## The cosmwasm-std dependency for library developers
+
+When you are creating a library that uses cosmwasm-std, you should be incredibly
+careful with which features you require. The moment you add e.g. `cosmwasm_1_2`
+there it becomes impossible to use the contract in chains with lower CosmWasm
+versions. If you add `abort`, it becomes impossible for the contract developer
+to opt out of the abort feature due to your library. Since this affects the
+default features `abort` and `iterator`, you should always disable default
+features.
+
+Also libraries should define a loose version range that allows the contract
+developer to control which cosmwasm-std version they want to use in the final
+project. E.g. if your library does not work with 1.0.0 due to a bug fixed in
+1.0.1, your min version is 1.0.1 and not the latest stable.
+
+A typical dependency then looks like this:
+
+```toml
+# We really need `stargate` here as this is an IBC related library. `abort` and `iterator` are not needed.
+cosmwasm-std = { version = "1.0.1", default-features = false, features = ["stargate"] }
+```