Skip to content

Production Quality contracts under open source licenses

License

AGPL-3.0, Apache-2.0 licenses found

Licenses found

AGPL-3.0
LICENSE-AGPL.md
Apache-2.0
LICENSE-APACHE
Notifications You must be signed in to change notification settings

astroport-fi/terra-plus

 
 

Repository files navigation

CosmWasm Plus

CircleCI

Specification Crates.io Docs
cw0 cw0 on crates.io Docs
cw1 cw1 on crates.io Docs
cw2 cw2 on crates.io Docs
cw3 cw3 on crates.io Docs
cw4 cw4 on crates.io Docs
cw20 cw20 on crates.io Docs
cw721 cw721 on crates.io Docs
cw1155 cw1155 on crates.io Docs
Utilities Crates.io Docs
cw-controllers cw-controllers on crates.io Docs
terra-multi-test Not published Not published
cw-storage-plus cw-storage-plus on crates.io Docs
Contracts Download Docs
cw1-subkeys Release v0.9.0 Docs
cw1-whitelist Release v0.9.0 Docs
cw3-fixed-multisig Release v0.9.0 Docs
cw3-flex-multisig Release v0.9.0 Docs
cw4-group Release v0.9.0 Docs
cw4-stake Release v0.9.0 Docs
cw20-atomic-swap Release v0.9.0 Docs
cw20-base Release v0.9.0 Docs
cw20-bonding Release v0.9.0 Docs
cw20-escrow Release v0.9.0 Docs
cw20-ics20 Release v0.9.0 Docs
cw20-staking Release v0.9.0 Docs
cw20-merkle-airdrop Release v0.9.0 Docs
cw721-base Release v0.9.0 Docs
cw1155-base Release v0.9.0 Docs

This is a collection of specification and contracts designed for use on real networks. They are designed not just as examples, but to solve real-world use cases, and to provide a reusable basis to build many custom contracts.

If you don't know what CosmWasm is, please check out our homepage and our documentation to get more background. We are running a public testnet you can use to test out any contracts.

Warning None of these contracts have been audited and no liability is assumed for the use of this code. They are provided to turbo-start your projects.

Note All code in pre-1.0 packages is in "draft" form, meaning it may undergo minor changes and additions until 1.0. For example between 0.1 and 0.2 we adjusted the Expiration type to make the JSON representation cleaner (before: expires: {at_height: {height: 12345}} after expires: {at_height: 12345})

Specifications

The most reusable components are the various cwXYZ specifications under packages. Each one defines a standard interface for different domains, e.g. cw20 for fungible tokens, cw721 for non-fungible tokens, cw1 for "proxy contracts", etc. The interface comes with a human description in the READMEs, as well as Rust types that can be imported.

They contain no logic, but specify an interface. It shows what you need to implement to create a compatible contracts, as well as what interface we guarantee to any consumer of such contracts. This is the real bonus of specifications, we can create an escrow contract that can handle many different fungible tokens, as long as they all adhere to the cw20 specification.

If you have ideas for new specifications or want to make enhancements to existing spec, please raise an issue or create a pull request on this repo.

Contracts

We provide sample contracts that either implement or consume these specifications to both provide examples, and provide a basis for code you can extend for more custom contacts, without worrying about reinventing the wheel each time. For example cw20-base is a basic implementation of a cw20 compatible contract that can be imported in any custom contract you want to build on it.

CW1 Proxy Contracts:

  • cw1-whitelist a minimal implementation of cw1 mainly designed for reference.
  • cw1-subkeys a simple, but useful implementation, which lets us use a proxy contract to provide "allowances" for native tokens without modifying the bank module.

CW3 Multisig:

  • cw3-fixed-multisig a simple implementation of the cw3 spec. It is a multisig with a fixed set of addresses, created upon initialization. Each address may have the same weight (K of N), or some may have extra voting power. This works much like the native Cosmos SDK multisig, except that rather than aggregating the signatures off chain and submitting the final result, we aggregate the approvals on-chain.
  • cw3-flex-multisig builds on cw3-fixed-multisig, with a more powerful implementation of the cw3 spec. It's a multisig contract backed by a cw4 (group) contract, which independently maintains the voter set.

CW4 Group:

  • cw4-group a basic implementation of the cw4 spec. It handles elected membership, by admin or multisig. It fulfills all elements of the spec, including raw query lookups, and is designed to be used as a backing storage for cw3 compliant contracts.
  • cw4-stake a second implementation of the cw4 spec. It fulfills all elements of the spec, including raw query lookups, and is designed to be used as a backing storage for cw3 compliant contracts. It provides a similar API to [cw4-group], but rather than appointing members, their membership and weight are based on the number of staked tokens they have.

CW20 Fungible Tokens:

  • cw20-base a straightforward, but complete implementation of the cw20 spec along with all extensions. Can be deployed as-is, or imported by other contracts.

  • cw20-atomic-swap an implementation of atomic swaps for both native and cw20 tokens.

  • cw20-bonding a smart contract implementing arbitrary bonding curves, which can use native and cw20 tokens as reserve tokens.

  • cw20-staking provides staking derivatives, staking native tokens on your behalf and minting cw20 tokens that can be used to claim them. It uses cw20-base for all the cw20 logic and only implements the interactions with the staking module and accounting for prices.

  • cw20-escrow is a basic escrow contract (arbiter can release or refund tokens) that is compatible with all native and cw20 tokens. This is a good example to show how to interact with cw20 tokens.

  • cw20-merkle-airdrop is a contract for efficient cw20 token airdrop distribution.

CW721 Non-fungible Tokens:

  • cw721-base a base implementation of a cw721 NFT contract. It implements the CW721 spec and is designed to be deployed as is, or imported into other contracts to easily build cw721-compatible NFTs with custom logic.

Compiling

To compile all the contracts, run the following in the repo root:

docker run --rm -v "$(pwd)":/code \
  --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
  --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
  cosmwasm/workspace-optimizer:0.12.1

This will compile all packages in the contracts directory and output the stripped and optimized wasm code under the artifacts directory as output, along with a checksums.txt file.

If you hit any issues there and want to debug, you can try to run the following in each contract dir: RUSTFLAGS="-C link-arg=-s" cargo build --release --target=wasm32-unknown-unknown --locked

Quality Control

One of the basic metrics of assurance over code quality is how much is covered by unit tests. There are several tools available for Rust to do such analysis and we will describe one below. This should be used as a baseline metric to give some confidence in the code.

Beyond code coverage metrics, just having a robust PR review process with a few more trained eyes looking for bugs is very helpful in detecting paths the original coder was not aware of. This is more subjective, but looking at the relevant PRs and depth of discussion can give an idea how much review was present.

After that, fuzzing it (ideally with an intelligent fuzzer that understands the domain) can be valuable. And beyond that formal verification can provide even more assurance (but is very time consuming and expensive).

Code Coverage

I recommend the use of tarpaulin: cargo install cargo-tarpaulin

To get some nice interactive charts, you can go to the root directory and run:

cargo tarpaulin -o html and then xdg-open tarpaulin-report.html (or just open on MacOS).

Once you find a package that you want to improve, you can do the following to just analyze this package, which gives much faster turn-around:

cargo tarpaulin -o html --packages cw3-fixed-multisig

Note that it will produce a code coverage report for the entire project, but only the coverage in that package is the real value. If does give quick feedback for you if you unit test writing was successful.

Licenses

This repo contains two license, Apache 2.0 and AGPL 3.0. All crates in this repo may be licensed as one or the other. Please check the NOTICE in each crate or the relevant Cargo.toml file for clarity.

All specifications will always be Apache-2.0. All contracts that are meant to be building blocks will also be Apache-2.0. This is along the lines of Open Zepellin or other public references.

Contracts that are "ready to deploy" may be licensed under AGPL 3.0 to encourage anyone using them to contribute back any improvements they make. This is common practice for actual projects running on Ethereum, like Uniswap or Maker DAO.

About

Production Quality contracts under open source licenses

Resources

License

AGPL-3.0, Apache-2.0 licenses found

Licenses found

AGPL-3.0
LICENSE-AGPL.md
Apache-2.0
LICENSE-APACHE

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Rust 95.9%
  • TypeScript 3.8%
  • Other 0.3%