https://github.com/paritytech/capi
[WIP] A framework for crafting interactions with Substrate chains
https://github.com/paritytech/capi
Last synced: 2 months ago
JSON representation
[WIP] A framework for crafting interactions with Substrate chains
- Host: GitHub
- URL: https://github.com/paritytech/capi
- Owner: paritytech
- License: apache-2.0
- Archived: true
- Created: 2022-03-17T01:56:40.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-30T00:24:59.000Z (over 2 years ago)
- Last Synced: 2025-10-20T17:55:58.867Z (2 months ago)
- Language: TypeScript
- Homepage: https://docs.capi.dev
- Size: 51.5 MB
- Stars: 104
- Watchers: 6
- Forks: 9
- Open Issues: 121
-
Metadata Files:
- Readme: Readme.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Capi
> [Announcing Capi v0.1.0-gamma.0](https://docs.capi.dev/blog/2023/06/29/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 →](https://docs.capi.dev)
Guides to get up and running
- [Examples →](./examples)
SHOW ME THE CODE
- [API Reference →](https://deno.land/x/capi/mod.ts)
A generated API
reference, based on type signatures and TSDocs.
## Installation
```sh
npm i capi
```
> Note: Capi depends on the standard
> [Web Crypto API](https://nodejs.org/docs/latest-v20.x/api/webcrypto.html#web-crypto-api)
> (**Node 20.3.1 and above**). See
> [shimming instructions](https://docs.capi.dev/setup/#web-crypto-api).
Deno Equivalent
`import_map.json`
```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.
```ts
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.
>
> ```json
> {
> "target": "ESNext",
> "module": "NodeNext"
> }
> ```
>
> For more information, see
> [Node's `exports` docs](https://nodejs.org/api/packages.html#exports) and
> [TypeScript's module resolution docs](https://www.typescriptlang.org/tsconfig#moduleResolution).
## Command Line Tool
In this documentation, we use Capi's CLI via the alias "capi", instead of via
its full path:
```sh
./node_modules/.bin/capi
```
Deno Equivalent
```sh
deno run -A https://deno.land/x/capi/main.ts
```
## Codegen Chain-specific APIs
```sh
capi sync node
```
Deno Equivalent
```sh
capi sync deno
```
## At a Glance
Retrieve the first 10 entries from a storage map of Polkadot.
```ts
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:
```sh
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...
```sh
deno task sync # only needed once
deno task run examples/
```
Or, to run an example with Node:
```sh
deno task sync # only needed once
deno task dnt --examples # only needed once
deno task capi serve -- node target/npm/capi-examples/esm/examples/
```
## 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[^1].
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](patterns), please
[submit an issue](https://github.com/paritytech/capi/issues/new?title=pattern%20idea:%20).
## Code of Conduct
Everyone interacting in this repo is expected to follow the
[code of conduct](CODE_OF_CONDUCT.md).
## Contributing
Contributions are welcome and appreciated! Check out the
[contributing guide](CONTRIBUTING.md) before you dive in.
## License
Capi is [Apache licensed](LICENSE).
[^1]: Rune is the unit of composition with which we model Capi programs.