cosmwasm / docs Goto Github PK

View Code? Open in Web Editor NEW

6.0 5.0 3.0 5.96 MB

Home Page: https://cosmwasm-docs.vercel.app

License: Apache License 2.0

JavaScript 5.01% MDX 89.93% Shell 0.20% CSS 0.49% TypeScript 0.03% Rust 1.76% Smarty 2.26% Nix 0.32%

docs's Introduction

The CosmWasm documentation platform

What is it?

A documentation-focused website for all CosmWasm-related technologies.

No matter if you need to integrate CosmWasm with a chain, create some smart contracts, or just have a look around to see what CosmWasm is about, here you'll be able to learn about CosmWasm's core, wasmd, storage, testing, IBC, CosmJS/InterchainJS, Sylvia framework, etc.

Where is it?

The website is hosted at https://cosmwasm-docs.vercel.app.

How is it made?

The deployed documentation is a Nextra project configured with the nextra-theme-docs package.

How can I run it locally?

You can just clone this repo and run the following commands, after making sure you use node v20:

npm install
npm run build
npm run start

You will now be able visit the locally served website at http://localhost:3000

How can I contribute?

After cloning this repo, make sure you use node v20 before running these commands:

npm install
npm run dev

The website will be available at http://localhost:3000 and the changes you make to the project will be reflected there instantaneously.

There's a hidden "How to doc" section that'll teach you how to write new entries. You can make this section visible by visiting http://localhost:3000/how-to-doc or with the CTRL + . (control plus period) keyboard shortcut.

After committing your changes to a new branch, push it to this repo and open a PR. This will automatically generate a Vercel preview link for the reviewers to check.

docs's People

Contributors

Stargazers

Watchers

Forkers

rtre84 pinosu tircimahmut

docs's Issues

Suggestion: add links to headers

For prior art, consider these doc frameworks which have a little link button when you hover over a section header

Github:

Rust docs:

Improvement ideas for Core

After reading through the entire Core part (which is great by the way!), I noted a few things that could be improved

Installation

Get rid of cargo-run-script

Entrypoints

Explain required and optional entry points (I think only instantiate is required at this point, not sure)
Show the typical message format for instantiate, migrate and execute. Highlight the use of an enum in execute

Actor Model

Worth mentioning that this plays nicely with Cosmos SDK messages. E.g. you don’t have access to the bank keeper to directly manipulate messages but emit a MsgSend instead.

Events

The structure of an event missing, i.e. a type fiels plus a list of attributes. The event itself has no keys, which is unclear from the text.

Pinning

Explain how to get hit stats for pinned contracts in CosmWasm 2.1 and above

Standard Library/Math

Add conversion table (https://drive.google.com/file/d/17NQHkUTOgmFcxE8_DcH3yFlAw-mQjyG8/view?usp=sharing)

Davids comments to be reviewed

David did a solid read through entire docs, and left lots of comments - we should make sure all of them are at least considered: https://vercel.com/confio/cosmwasm-docs/BxVktxpvCBtUmh2rjGKb5G5scUYX.

Feedback for “Index”

As a new cosmwasm developer, I want a graphical "anatomy of a cosmwasm program" so that I can quickly build a mental model of how it all comes together.

doing the workshop yesterday, I was able to get there, but I would have benefited from seeing some diagram of sorts.

Rewrite `Map`

Move toward more use-case-driven docs, probably!

document compound keys being wonky when it comes to iteration, bounds, etc
- link to the "wonkiness" documentation in IndexedMap docs

Suggestion: document high-level "working with custom app-chains"

There are several things that come up in this scenario:

cosmwasm_std:

QueryRequest::Custom

One example I'm aware of in the wild is Sei https://github.com/sei-protocol/sei-cosmwasm/blob/2d416bfc8ad48ef1190c78bf503bdafb38c6d8d3/packages/sei-cosmwasm/src/querier.rs#L17
Another is Osmosis: https://github.com/osmosis-labs/osmosis-rust/blob/31fa382125033c37f3adc784a977991c0f85d462/packages/osmosis-std/src/types/osmosis/tokenfactory/v1beta1.rs#L555

QueryRequest::Grpc (related to #127)

cw_multi_test:

Explain the need to mock (since there's no real chain to hit), with examples for both Custom and Grpc. Also highlight how this can be a very good thing since mocking allows testing the contract under extreme scenarios, e.g. the "oracle" can provide prices via proptest and stress-test wild price-swings etc.

Document Instantiate2 algorithm

For CosmWasm/cosmwasm#2155 and and other cases we need a spec for the Instantiate2 address generation algorithm. We already have 3 implementartions (Go, Rust and TypeScript) but no central definition how the addresses are calculated.

CosmWasm core - Installation - mention that optimizer isn't suitable for dev/fast iteration

The docs should mention that the optimizer Docker image isn't suitable for fast iteration since it optimizes too much.

See #57 (comment) and CosmWasm/optimizer#152 (comment)

Possibility to highlight relevant code parts

Can we add a possibility in the code examples to highlight relevant lines? The best would probably be to dim most of the code and only make normal coloring for the relevant parts for the reader to focus on them, but any solution that moves attention to only relevant lines of the holistic example would most likely work. @abefernan ideas?

Describe actual usage of CosmWasm

The CosmWasm docs describe the creation of a product (Smart Contract) but do not explain how to use it in the real world.

I would like to see maybe a separate section like Deployment where we would create a simple but feature-full contract, set up a simple chain, and describe:

Install the contract on the chain
Initialize the contract
Execution, queries, sudos, ...
Usage of custom messages and custom queries
And potentially more

All of that with example setups in both contract and chain.

are we consistent with using code tags in section/article titles

The question is - when the section/article name is a keyword/function name, should we use code tags or not? That is the minor things, and my take is that the clue is to be consistent about that. Reading some of the docs I think that doing so makes the formatting strange so I'd rather avoid any additional formatting in headers, but let's get aligned about this in the discussion and when we decide one would go through all the pages and unify that.

Double Footer

https://cosmwasm-docs.vercel.app has the "CosmWasm is proudly created..." footer twice.
Curiously, this is not seem to be the case for the PR deployments.

Entrypoints - Additional Info

I think the entrypoints page would be a good place to explain what DepsMut, Env and MessageInfo are for. We don't need to go into a lot of detail, but a short sentence and a docs.rs link for each would be nice.

The docs should also explain that the InstantiateMsg / ExecuteMsg / ... are defined by the user and how to do that (e.g. explain #[cw_serde]).
A similar explanation for the returned error type would be good. Right now all of the examples use StdResult, but you're totally free to use any type that implements ToString.

Feedback for IBC docs

Reading through the IBC docs, just noting some things for consideration. Not making a PR at this stage since some of this is definitely nitpicky/subjective, maybe even wrong. Happy to discuss this and decide if/how any of it should be addressed, and then close the issue out - perhaps with no changes at all.

Landing page

"You can use the IBC protocol as a building block to create your own custom protocols on top of it" - I think this can be a much stronger marketing pitch. This page should emphasize the power of using contracts via IBC. Most people think of IBC as only ICS-20, and for good reason: developing anything beyond that, without CosmWasm, requires a ridiculously heavy burden of chain-level-code across multiple chains. Cosmwasm isn't just the best solution for developing IBC apps, it's arguably the only reasonable solution for IBC apps
"IBC is a protocol that allows different blockchains to communicate with each other. It is a standard that defines how blockchains can send and receive messages to each other." - a bit redundant, communication means sending/receiving messages here, I think one of these sentences can be deleted

Getting Started page

"To get started, you need to enable the stargate feature of the cosmwasm-std crate" - this is confusing... what is stargate? Why isn't this feature called "ibc"? I think explaining this a bit more is worthwhile
There is still a "TODO" in Notes section

Basic Concepts page

High-level, I think it should link to the IBC docs up front, and mention the need to run a relayer, then the rest of the doc can speak about only the relationship to CosmWasm. The rest of my notes will assume that is changed.
"Port: An identifier that corresponds to a single module on a chain. One module can have multiple ports. Each contract has its own unique port." - I would de-emphasize the role of cosmos modules here... suggested change: "Port: every instantiation of an ibc-enabled contract creates a unique port, similarly to how it creates a unique address"
"Channel: A connection between two ports on different blockchains that allows them to send packets to each other. Each port can have multiple channels." - I would de-emphasize the relationship to ports, but rather to contracts. suggested change: "Channel: to send messages between contracts on different chains, you must first create a channel over their assigned ports. Multiple channels are allowed and they can be distinguished by 'version'"
"Relayer": delete (mention briefly up top)
"Packet: A piece of binary data that is sent through a channel. It can time out if it is not delivered within a certain time frame." - small suggestion: "A piece of binary data that is sent through a channel from contract to contract" (i.e. to emphasize that it's not a client->chain thing like other messages)

Using Existing Protocols page

I think this should be split into ICS-20 and Custom Contract subpages, where the intro page just explains the difference between on-chain protocols and custom contract protocols, and the custom contract walks through calling the Nois (or other) example
I also think it should come after "Build your own protocol". Even though ICS-20 is the common case, it's easy to find, and hopefully someone will be coming to these docs because they want to build contracts that do more than ICS-20

Build Your Own Protocol page

As mentioned above, I think this should come before the "use existing protocols" page. Not because of which is easier to grok, but rather from the perspective of "developers writing contracts", hopefully they are more interested in writing distributed apps that require custom logic, and that's why they're on the page
I haven't fully groked the "advanced example"... skimmed through it, but cool stuff

Overall the docs as they are are fantastic, the above are just some small suggestions - nothing at all crucial!

[tracking] Checklist before release

do most articles/sections have tags?
do examples showcase both cw-storage-plus and cw-storey? (using tabs like here)
is naming consistent?
is formatting more or less consistent? (nothing jarring)
#78

Generic contracts and interfaces in sylvia

We need a very solid explanation of generic Sylvia stuff, especially in the context of chain-agnostic contracts (those should be using generic custom msg/query). The reasoning behind that should be explained, and simple way of implementing this pattern should be presented.

Storage terminology

We might want to discuss the terminology we use in docs for storage-plus and storey.

abstractions like Item and Map: containers, accessors, collections, structures?

Suggestion: "Tutorial"

The current docs structure is excellent for someone who is working with CosmWasm and needs to look up a specific topic (e.g. how to work with wasmd, storey, add ibc hooks, etc.), or someone brand-new to CosmWasm and wants a tour of everything it can do.

However, we received a couple comments - and I agree, that it's not very clear from a "how to get started, hands-on" perspective.

What about a separate section called "Tutorial" that is a start-to-finish guide with to create a contract, deploy it, test it, etc.?

Where applicable, it can show examples with different tools in tabs (like the "Containers" section in Storey showing storage-plus vs. Story: https://docs.cosmwasm.com/storey/containers)

Explanation of submessage-reply flow in sylvia

Addressing comment after prior review: #97 (review)

IBC: State Rewinding

I like it very much. I left couple more minor comments, apply them or not basing on your judgement, then just merge (no need for re-review).
One section I find missing here is about handling the "state rewinding". What I mean is that the IBC is non-transactional. This obviously brings the difficulty that if we get the timeout, we might want to make sure the changes we did are not happening - we need to rewind them manually.
I can see two strategies to work with that issue. One is to perform the "transaction rewinding" on the timeout/failure as mentioned. The other would be storing change state in some temporal place, and then "harden" it on ack. And probably mix of those as well.
I don't know if it is a thing to do in this PR, or if its needed, but I think some additional "advanced" chapter covering that would be nice. If you agree then please either add it or create an issue to add it later.

Originally posted by @hashedone in #19 (review)

Explain Stargate / Grpc query and Stargate / Any message from a contract POV

Basically, we want to tell people that this uses protobuf for the message / query and response type,
that they should use some protobuf crate for that (we can also reference crates like cosmos-sdk-proto and mention that many chains offer their own crates with predefined types) and show some example code on how to do it.
For messages, there is one example in the IBC docs already that can be adapted.

For Stargate query specifically, we should mention this caveat.

`cw-storage-plus`: Have examples use Sylvia?

Currently, the examples in cw-storage-plus docs create storage containers ad-hoc like this:

let mut map = Map::new("foo");

This isn't great since we want to encourage better practices for RL scenarios. Maybe we can figure out something better?

CosmWasm core: Documentation outline

Tracking issue for a basic outline of the documentation:

IBC: Add storage to "Channel lifecycle" examples

Currently the channel lifecycle is not guarded in any way in the examples. There is a description in the text that you should guard it and some different ways, but it would certainly be better to have it in the examples. Let's face it, people will end up just copying code out of the docs to get stuff to work.

I think it makes sense to save the channel info in storage in ibc_channel_connect and also check it in ibc_channel_open to avoid bad actors overwriting the existing channel.

Documentation about how to correctly use the `library` feature as a consumer

Make sure all code examples containing an entry point use library feature

Follow-up to #57 (comment)

We should probably enforce the convention of having a library feature in contracts by putting them explicitly into every code sample and reinforcing that this is how it should be done.

Also, as @chipshort mentioned, people will probably copy-paste from the docs a lot, so having that library feature everywhere means that they will follow best practices.

One open question is how to enforce this in CI. An idea I had was a simple CI step that greps across the extracted tests for ^#\[entry_point\] and errors out when it gets hit (something like that)

Rewrite `Item`

Move toward more use-case-driven docs, probably!

IBC: Enable tests for 2.1 specific features

The code examples for 2.1-specific IBC features (callbacks + async acks) are currently not tested with the docs-test-gen.
I have added TODO comments in all the places where these should be enabled once 2.1 is released.

Add Query raw and smart query in wasmd section

CosmWasm gas - correction

The gas is not separate but has to be converted from CosmWasm gas to Cosmos gas. We should correct that assertion in the docs.

See #57 (comment)

Document `MultiIndex`

[docs-test-gen] Indented code blocks ignored

SEE #37 (comment) FOR DISCLAIMER

_{Original issue follows now}

Code blocks that are indented with whitespace are silently ignored by the docs-test-gen.
This is mostly a problem when putting code blocks inside <Tabs></Tabs>.