Table of Contents
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.
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.0 | Cairo v2.4.4 |
abiwan-demo.mp4
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"]
}
}
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!
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);
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.
Abiwan supports all of Cairo types, here's the mapping between Cairo types and Typescript 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 |
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 |
Cairo:
struct TestStruct {
int128: u128,
felt: felt252,
tuple: (u32, u32)
}
Typescript:
{
int128: number | bigint | Uint256;
felt: string | number | bigint;
tuple: [number | bigint, number | bigint];
}
Cairo:
enum TestEnum {
int128: u128,
felt: felt252,
tuple: (u32, u32),
}
Typescript:
{ int128: number | bigint | Uint256 } |
{ felt: string | number | bigint } |
{ tuple: [number | bigint, number | bigint]}
npm run typecheck
# 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
For a full list of all authors and contributors, see the contributors page.
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!
Abiwan is greatly influenced by the similar project for EVM-compatible contracts wagmi/abitype.
abi-wan-kanabi's People
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.