Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add pop api documentation #74

Merged
merged 5 commits into from
May 5, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 73 additions & 1 deletion pop-api/README.md
Original file line number Diff line number Diff line change
@@ -1 +1,73 @@
Reserved crate for pop-api.
# Pop API

## Examples
ink! smart contract examples using the Pop API
- [balance-transfer](./examples/balance-transfer/)
- [NFTs](./examples/nfts/)
- [place-spot-order](./examples/place-spot-order/)
- [read-runtime-state](./examples/read-runtime-state/)

## What is the Pop API?

One of the core value propositions of Pop Network is to enable smart contracts to easily access the power of Polkadot. As such, the Pop API was built to enable smart contracts to easily utilize the functionality provided by the Pop Network parachain runtime.

Substrate already exposes a Runtime API which is typically associated with the “outer node” calling into the runtime via RPC. Pop Network extends this concept in a direction that makes it usable by smart contracts, allowing untrusted contracts to make use of carefully exposed trusted functionality available within the runtime - this is the Pop API.
Daanvdplas marked this conversation as resolved.
Show resolved Hide resolved

The Pop API is designed to be:
- **Stable**: contracts are generally immutable and therefore need a stable interface, especially as the runtime evolves over time.
- **Future Proof**: technologies improve, so the Pop API implementation is adaptable to new approaches without affecting the interface. The Pop API implementation also selects the optimal approach to realize a use case from a range of possible technical implementations.
- **Versioned**: not every future technology can be retro-fitted, so the API is versioned.
- **Simple**: providing an abstraction layer over runtime-level features. Hand-rolled with love, Pop API is easy to use for smart contract development.

The Pop API consists of three main parts:
- the Pop API ink! library
- the Pop API runtime code (chain extension)
- shared primitive types between the Pop API ink! library and the Pop API runtime code

Let's go over the flow.

## The Pop API ink! Library
Everything in [`pop-api`](./src/) **is the** Pop API ink! library.

So when the ink! smart contract wants to use the Pop API library, it can simply have a line like:
```rust
use pop_api::nfts::*;
```

## The Glue
Daanvdplas marked this conversation as resolved.
Show resolved Hide resolved

Certain types are shared between the ink! library portion of the Pop API and the runtime portion of the Pop API. These types can be found in [`pop_primitives`](../primitives/src/), outside the [`pop-api`](./src/) folder.

## The Entry into the Pop API

When we use the Pop API in our smart contract like so:
```rust
use pop_api::nfts::*;
mint(collection_id, item_id, receiver)?;
```

This will call the Pop API `mint` function in the [./src/v0/nfts.rs](./src/v0/nfts.rs) file, which is a wrapper to `dispatch` a `Runtime::Call` to the NFTs pallet's mint function. This is how most of the Pop API is built. This abstraction allows for creating a developer-friendly API over runtime level features such as calling pallets, reading state, and cross-chain interactions. All Pop API functionality can be found in [./src/v0/](./src/v0/) which is the current version of the Pop API.


## Dispatching to the runtime ([./src/lib.rs](./src/lib.rs))

### `PopApi`
The `PopApi` trait is an ink! chain extension trait with three functions:
- `dispatch()`
- `read_state()`
- `send_xcm()`

These are the workhorse functions of the Pop API. Through these functions all the interactions between the ink! smart contract and the runtime are carried out. So in our example above, the `mint` function in [nfts.rs](./src/v0/nfts.rs) calls a `dispatch`, this `dispatch` is defined here in the [lib.rs](./src/lib.rs) file. It is what calls into the runtime chain extension.

> Notice how each function is assigned a function ID e.g. `#[ink(function = 1)]`. This will play a role later when we cover the runtime portion of the chain extension.

### `PopApiError`
When Pop API calls the runtime, it will either receive a successful result or an encoded error. `PopApiError` translates the encoded error into the appropriate module error according to the index that the pallet has been configured to.

## The Pop API Chain Extension

So we have covered how the ink! Pop API library calls the chain extension. But where is the chain extension actually defined? In the Pop Network runtime.

Chain extensions "extend" a runtime. We can find the `PopApiExtension` chain extension in [extension.rs](../runtime/devnet/src/extensions.rs). The `PopApiExtension` chain extension is matching based on the function IDs that we defined on the ink! side of the Pop API. The chain extension here will execute the appropriate functions e.g. `dispatch` or `read_state`. These functions are defined in this file as well and interact directly with the Pop Network runtime.

If you would like to see the whole flow, checkout the end-to-end tests in [extensions.rs](../runtime/devnet/src/extensions.rs) file e.g. `dispatch_nfts_mint_from_contract_works()`
Loading