paritytech / capi

[WIP] A framework for crafting interactions with Substrate chains

Capi

Announcing Capi v0.1.0-gamma.0

Capi is a framework for crafting interactions with Substrate chains. It consists of a development server and fluent API, which facilitates multichain interactions without compromising either performance or ease of use.

• Manual →
  Guides to get up and running
• Examples →
  SHOW ME THE CODE
• API Reference →
  A generated API reference, based on type signatures and TSDocs.

Installation

npm i capi

Note: Capi depends on the standard Web Crypto API (Node 20.3.1 and above). See shimming instructions.

Deno Equivalent

import_map.json

{
  "imports": {
    "capi": "https://deno.land/x/capi/mod.ts",
    "capi/nets": "https://deno.land/x/capi/nets/mod.ts"
  }
}

Note: For now, we only support the latest 1.x version of Deno.

Configuration

Create a nets.ts and specify the chains with which you'd like to interact.

import { bins, net } from "capi/nets"

const bin = bins({ polkadot: ["polkadot", "v0.9.38"] })

// A Polkadot development network
export const polkadotDev = net.dev({
  bin: bin.polkadot,
  chain: "polkadot-dev",
})

// The Polkadot relay chain
export const polkadot = net.ws({
  url: "wss://rpc.polkadot.io/",
  targets: { dev: polkadotDev },
})

Note: if the type declarations for capi/nets are not resolved, chances are your tsconfig does not reflect the following requirements.

{
  "target": "ESNext",
  "module": "NodeNext"
}

For more information, see Node's exports docs and TypeScript's module resolution docs.

Command Line Tool

In this documentation, we use Capi's CLI via the alias "capi", instead of via its full path:

./node_modules/.bin/capi

Deno Equivalent

deno run -A https://deno.land/x/capi/main.ts

Codegen Chain-specific APIs

capi sync node

Deno Equivalent

capi sync deno

At a Glance

Retrieve the first 10 entries from a storage map of Polkadot.

import { polkadot } from "@capi/polkadot"

const accounts = await polkadot.System.Account.entries({ limit: 10 }).run()

Development Networks

During development, we may want to swap out the underlying connection with that of a devnet. This can be achieved via targets — by specifying alternate targets in your nets.ts file, you can switch to them by wrapping your command with capi serve --target someTarget --. For example:

capi serve --target dev -- node main.js

Other examples:

• capi serve --target dev -- npm run start
• capi serve --target dev -- deno run -A ./main.ts

Running Examples

Within a fresh clone of this repository...

deno task sync # only needed once
deno task run examples/<example_path>

Or, to run an example with Node:

deno task sync # only needed once
deno task dnt --examples # only needed once
deno task capi serve -- node target/npm/capi-examples/esm/examples/<example_path>

Rationale

In a likely future of specialized, interoperable chains, developers will need to make use of on-chain programs to satisfy varying use cases; the expertise required to interact with these on-chain programs is currently greater than that which should be expected of app developers. Does this mean that app developers must forgo integrating with this blossoming infrastructure? We think not; the open source community can use Capi to abstract over the atomics of the on-chain world. An interaction spanning several chains and dozens of methods can be described with a single Rune¹.

As you read through this documentation, please consider use cases over which you might like to abstract; if you wish to add your use case to Capi's standard library, please submit an issue.

Code of Conduct

Everyone interacting in this repo is expected to follow the code of conduct.

Contributing

Contributions are welcome and appreciated! Check out the contributing guide before you dive in.

License

Capi is Apache licensed.

Footnotes

1. Rune is the unit of composition with which we model Capi programs. ↩