npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@sentio/abi-wan-kanabi

v2.2.2-1

Published

Abi parser for Cairo smart contracts, based on wagmi abitype

Downloads

747

Readme

Abiwan

Exploration_Team

About

Abiwan 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.

Cairo versions

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

| Abiwan | Cairo compiler | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1.0.3 | Cairo v1.0.0 Cairo v1.1.0 | | 2.1.1 | Cairo v2.3.0 | | 2.2.2 | Cairo v2.4.4 |

Getting Started

Demo

https://github.com/haroune-mohammedi/abi-wan-kanabi/assets/118889688/b7e20ab0-7314-402d-99fa-2888c20136c9

Prerequisites

Abiwan dependence only 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"]
  }
}

Usage standalone

To use Abiwan, you must first export your ABI as const in a typescript file

export const ABI = [
  //Your ABI here
] as const;

If you have a json file containing your contract class, you can use the CLI to generate the typescript file for you:

npx abi-wan-kanabi --input /path/to/contract_class.json --output /path/to/abi.ts

You can then import it in any script and you are set to go:

import ABI from "./path/to/abi";
import { call } from "abi-wan-kanabi";
// You'll notice the editor is able to infer the types of the contract's functions
// It'll give you autocompletion and typechecking
const balance = call(ABI, "your_function_name", ["your", "function", "args"]);

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

Usage with starknet.js

Let's say you want to interact with the Ekubo: Core contract using starknet.js

You need to first get the ABI of the contract and export it in a typescript file, you can do so using one command combining both starkli (tested with version 0.2.3) and npx abi-wan-kanabi, the command will also print a helpful snippet that you can use to get started

starkli class-at "0x00000005dd3d2f4429af886cd1a3b08289dbcea99a294197e9eb43b0e0325b4b" --network mainnet | npx abi-wan-kanabi --input /dev/stdin --output abi.ts
import { Contract, RpcProvider, constants } from "starknet";
import { ABI } from "./abi";

async function main() {
  const address =
    "0x00000005dd3d2f4429af886cd1a3b08289dbcea99a294197e9eb43b0e0325b4b";
  const provider = new RpcProvider({ nodeUrl: constants.NetworkName.SN_MAIN });
  const contract = new Contract(ABI, address, provider).typedv2(ABI);

  const version = await contract.getVersion();
  console.log("version", version);

  // Abiwan is now successfully installed, just start writing your contract
  // function calls (`const ret  = contract.your_function()`) and you'll get
  // helpful editor autocompletion, linting errors ...
  const primary_inteface_id = contract.get_primary_interface_id();
  const protocol_fees_collected = contract.get_protocol_fees_collected("0x1");
}
main().catch(console.error);

Configuration

Abiwan's types are customizable using declaration merging. Just extend the Config interface and override the types you want to change, see how starknet.js is doing it here

declare module "abi-wan-kanabi" {
  interface Config {
    FeltType: string;
    IntType: number;
    // ...
  }
}

Check config.ts for all the available options and the their default values.

 Supported Cairo Types

Abiwan 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 \| U256  | | ContractAddress  | string | | EthAddress  | string | | ClassHash  | string | | bytes31  | string | | ByteArray  | string | | bool | boolean  | | ()  | void |

 Complex Types

| Cairo | TypeScript | | ------------------------- | --------------------------------------------------- | | Option<T> | T \| undefined | | Array<T> | T[] | | Span<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

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

Contributions on Abiwan are most welcome! If you are willing to contribute, please get in touch with one of the project leads 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! :clap: 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.