ic-basilisk 0.8.37

No project description provided

Basilisk

Write Python canisters for the Internet Computer. Forked from Kybra.

Features

• Write IC canisters in pure Python using @query and @update decorators
• Two backends: CPython 3.13 (default, fast builds) and RustPython
• Fast template builds: CPython canisters build in seconds, not minutes
• IC system APIs: ic.caller(), ic.time(), ic.print(), ic.canister_balance(), etc.
• Chunked code upload for canisters larger than 10MB
• StableBTreeMap for persistent key-value storage across upgrades
• Principal, Opt, Vec, Record, Variant type support

Getting Started

Prerequisites

• dfx (IC SDK)
• Python 3.10+
• WASI SDK (for CPython backend)

Install

pip install ic-basilisk

Create a new project

basilisk new my_project
cd my_project

This creates a ready-to-deploy project:

my_project/
  src/main.py    -- your canister code
  dfx.json       -- IC project config

The generated canister code

from basilisk import query, update, text, nat64, ic

counter = 0

@query
def greet(name: text) -> text:
    return f"Hello, {name}! The counter is at {counter}."

@query
def get_counter() -> nat64:
    return counter

@update
def increment() -> nat64:
    global counter
    counter += 1
    return counter

@query
def get_time() -> nat64:
    return ic.time()

@query
def whoami() -> text:
    return str(ic.caller())

Deploy and call

dfx start --background
dfx deploy

dfx canister call my_project greet '("World")'
# ("Hello, World! The counter is at 0.")

dfx canister call my_project increment
# (1 : nat64)

dfx canister call my_project whoami
# ("2vxsx-fae")

Python Backends

Basilisk supports two Python backends:

# CPython 3.13 (default) -- fast template builds
basilisk new my_project

# RustPython -- legacy, full Rust build
basilisk new --backend rustpython my_project

CPython vs RustPython

	CPython 3.13	RustPython
Build time	~seconds (template)	~60-120s (Cargo build)
Wasm size	~5.3 MB	~26 MB
Python compatibility	Full (reference implementation)	Partial (~3.10)

Benchmark Results

Wasm instruction counts measured on a PocketIC replica via GitHub Actions CI. Lower is better — fewer instructions means lower cycle cost on the IC.

Benchmark	CPython (instructions)	RustPython (instructions)	RustPython / CPython
noop (call overhead)	15,914	88,918	5.6x
increment (state mutation)	16,050	92,485	5.8x
fibonacci(25) (iterative)	37,269	294,649	7.9x
fibonacci_recursive(20)	29,617,903	337,795,318	11.4x
string_ops (100 concatenations)	275,375	2,135,202	7.8x
list_ops (500 append + sort)	602,711	5,819,267	9.7x
dict_ops (500 inserts + lookups)	3,407,101	23,087,720	6.8x
method_overhead (total prelude)	11,122	42,216	3.8x

CPython is 6–11x faster than RustPython for compute-heavy workloads due to its optimized C interpreter. The gap is largest for recursive function calls (11.4x) and list operations (9.7x). Even the minimum overhead per call is lower: 11K vs 42K instructions.

Full CI logs: CPython run · RustPython run

Run it yourself: trigger the Benchmark workflow from the Actions tab — select cpython, rustpython, or both as the backend, and local or ic as the network.

The benchmark source is in benchmarks/counter/.

CLI Reference

basilisk new [--backend cpython|rustpython] <project_name>   # scaffold a project
basilisk build                                                # build in current dir
basilisk --version                                            # print version

Available Types

from basilisk import (
    query, update,                    # method decorators
    text, blob, null, void,           # basic types
    nat, nat8, nat16, nat32, nat64,   # unsigned integers
    int8, int16, int32, int64,        # signed integers
    float32, float64,                 # floats
    Opt, Vec, Record, Variant,        # compound types
    Principal,                        # IC principal
    ic,                               # IC system API
)

IC System API

from basilisk import ic

ic.caller()              # caller's Principal
ic.time()                # current timestamp (nanoseconds)
ic.id()                  # canister's own Principal
ic.print(msg)            # debug print (visible in replica logs)
ic.trap(msg)             # abort with error message
ic.canister_balance()    # current cycle balance
ic.canister_balance128() # cycle balance as 128-bit int

Disclaimer

Basilisk may have unknown security vulnerabilities due to the following:

• Limited production deployments on the IC
• No extensive automated property tests
• No independent security reviews/audits

Documentation

For detailed architecture notes, see CPYTHON_MIGRATION_NOTES.md. For the original Kybra documentation, see The Kybra Book.

Discussion

Feel free to open issues.

License

See LICENSE and NOTICE.