/abi-wan-kanabi

Abi parser for Cairo smart contracts, based on wagmi abitype

Primary LanguageTypeScriptThe UnlicenseUnlicense

ABI-WAN-KANABI

npm version

Table of Contents

About

Abi-wan-kanabi is an UNLICENSE standalone TypeScript parser for Cairo smart contracts. It enables on the fly typechecking and autocompletion for contract calls directly in TypeScript. Developers can now catch typing mistakes early, prior to executing the call on-chain, and thus enhancing the overall Dapp development experience.

Getting Started

Prerequisites

Abiwan is a standalone typescript library. Its only dependence is on typescript version 4.9.5 or higher. Also, it makes use of BigInt, so the tsconfig.json should target at least ES2020:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "ESNext"]
  }
}

Cairo versions

abiwan will support multiple Cairo compiler versions, but not in parallel - different package versions will support consecutive Cairo versions.

Currently supported:

Abi-Wan npm Cairo compiler
1.0.3 Cairo v1.0.0
Cairo v1.1.0
2.0.0 Cairo v2.3.0-rc0

Build

To use abiwan, you must first generate types from your contracts' ABI json files, you can use the helper script:

npm run generate -- --input /path/to/abi.json --output /path/to/abi.ts

This will create a typescript file for the abi. You can then import it in any script and you are set to go:

import abi from "./path/to/abi";
import { call } from "./kanabi";
const balance = call(abi, "balance_of", 5n);

If you think that we should be able to import types directly from the json files, we think so too! See this typescript issue and thumb it up!

Run tests

npm run typecheck

Generate test/example.ts

# First build the example project with `scarb`
cd test/example
scarb build
# Then generate test/example.ts
cd ../..
npm run generate -- --input test/example/target/dev/example_example_contract.contract_class.json --output test/example.ts

Demo

https://drive.google.com/file/d/1OpIgKlk-okvwJn-dkR2Pq2FvOVwlXTUJ/view?usp=sharing

Warning

Abiwan is still very young and has not yet been subject to an official release. We do not recommend using it in production yet.

 Supported Cairo Types

Abi-wan-kanabi supports all of Cairo types, here's the mapping between Cairo types and Typescript types

Primitive Types

Cairo TypeScript
felt252 string | number | bigint
u8 - u32 number | bigint 
u64 - u256 number | bigint | Uint256 
ContractAddress  string
ClassHash  string
bool boolean 
()  void

 Complex Types

Cairo TypeScript
Option<T> T | undefined
Array<T> T[]
tuple (T1, T2, ..., Tn) [T1, T2, ..., Tn] 
struct  an object where keys are struct member names
enum a union of objects, each enum variant is an object 

Struct example

Cairo:

struct TestStruct {
  int128: u128,
  felt: felt252,
  tuple: (u32, u32)
}

Typescript:

{
  int128: number | bigint | Uint256;
  felt: string | number | bigint;
  tuple: [number | bigint, number | bigint];
}

Enum example

Cairo:

enum TestEnum {
  int128: u128,
  felt: felt252,
  tuple: (u32, u32),
}

Typescript:

{ int128: number | bigint | Uint256 } |
{ felt: string | number | bigint } |
{ tuple: [number | bigint, number | bigint]}

Contributing

Contributions on abiwan are most welcome! If you are willing to contribute, please get in touch with one of the project lead or via the repositories Discussions

Acknowledgements

Authors and Contributors

For a full list of all authors and contributors, see the contributors page.

Special mentions

Big thanks and shoutout to Francesco! 👏 who is at the origin of the project!

Also thanks to the awesome Haroune (@haroune-mohammedi) and Thomas (@thomas-quadratic) from Quadratic!

Other projects

Abiwan is greatly influenced by the similar project for EVM-compatible contracts wagmi/abitype.