ic-basilisk-toolkit
Basilisk Toolkit — A set of ready-made tools on top of Basilisk CDK for IC Python canisters.
Live demo: https://ic-basilisk.tech/.
Overview
| Task Management | Create, schedule, and run background tasks |
%task create heartbeat every 60s --code "print('alive')"
%task start 1
%task info 1
%task list
t = Task(name="sync")
TaskStep(task=t, code="print('syncing...')")
TaskSchedule(task=t, interval=60)
TaskManager().run()
| |
| Wallet | ICRC-1 token registry, transfers, balance tracking |
%wallet balance
%wallet transfer ckBTC <principal> 1000
w = Wallet()
w.register_token("ckBTC", ledger="mxzaz-...", indexer="n5wcd-...")
yield from w.balance_of("ckBTC")
yield from w.transfer("ckBTC", to_principal, amount=1000)
yield from w.refresh("ckBTC", max_results=50)
w.list_transfers("ckBTC", limit=20)
| |
| Encryption | vetKeys + per-principal envelopes + groups |
%crypto encrypt "secret"
%group create team1
%group add team1 <principal>
cs = CryptoService(vetkey_service)
yield from cs.init_scope("my-scope")
cs.grant_access("my-scope", target_principal)
cs.create_group("team")
cs.add_member("team", principal)
cs.grant_group_access("my-scope", "team")
cs.revoke_access("my-scope", principal)
| |
| FX | Exchange rate queries via the IC XRC canister |
%fx ICP/USD
fx = FXService()
fx.register_pair("ICP", "USD")
yield from fx.refresh() # fetch latest rates from XRC canister
fx.get_rate("ICP", "USD") # cached float
fx.get_rate_info("ICP", "USD") # full info with staleness metadata
| |
| Entities | Persistent ORM via ic-python-db |
%db types
%db list User 10
%db show User 1
%db search User name=alice
%db export User backup.json
%db import backup.json
u = User(name="alice") # auto-persisted on creation
u.name = "bob" # changes save automatically
bob = User['bob']
bob.friends
| |
| Secure ORM | Sandboxed, Cedar-authorized entity access — plug-and-play |
class TodoList(SecureEntity):
title = String(max_length=200)
owner = String(max_length=64)
orm = setup_secure_orm([TodoList], namespace="TodoApp")
@update
def __shell__(code: str) -> text:
return orm.shell(code) # sandboxed REPL; Cedar checks every mutation
Users REPL with the native | |
| Cedar Authorization | Policy engine wrapper, schema generation, fail-closed decision point |
from ic_basilisk_toolkit.cedar_engine import CedarEngine
engine = CedarEngine("TodoApp", "User", schema, policies)
engine.load() # fail-closed; parses + validates at startup
engine.check(caller, "entity.update", "TodoList", row_id, row)
@query
def __cedar__(query: str) -> text:
return orm.cedar(query) # read-only: schema, policies, status
Requires the Cedar canister template artifact ( | |
| Schema Upgrades | Pre-deploy schema diff, migration safety, read-only data browsing |
basilisk check-upgrade --canister my_app --network ic
See documentation. | |
| Logging | Structured logging via ic-python-logging |
from ic_python_logging import get_logger
logger = get_logger("my_module")
logger.info("processing")
logger.error("failed", exc_info=True)
| |
| HTTP Fetch | Download a URL into the canister filesystem |
%wget https://example.com/data.json /data.json
yield from wget("https://example.com/data.json", "/data.json")
run("/data.json") # execute a downloaded Python script
| |
| File Transfer | Move files between local machine and canister |
%put local_script.py /app/script.py
%get /app/output.json result.json
| |
| Interactive Shell | REPL for live canister interaction |
basilisk-toolkit shell --canister my_app --network ic
basilisk-toolkit exec --canister my_app 'print(ic.time())'
| |
| SFTP | Browse and edit canister filesystem over SSH |
basilisk-toolkit sshd --canister my_app --network ic
sftp -P 2222 localhost
ssh -p 2222 localhost
| |
Type :help inside the shell for full command reference, or see the tip_jar template for a working example project.
Templates
Full-stack example canisters, each deployable as-is:
- Tip Jar — crypto donations in ckBTC / ckETH / ckUSDC / ICP with live exchange rates, encrypted messages, donor leaderboard. Live.
- File Registry — general-purpose on-chain file storage with HTTP serving, CORS, chunked upload for large WASMs, and per-namespace ACLs. Live.
- Todo List — multi-user todo lists with sandboxed REPL and Cedar owner-only authorization, built on
SecureEntity. Backend-only; the smallest secure-ORM example.
Website
website/ is the static landing page at ic-basilisk.tech — it introduces basilisk and this toolkit and links out to the live template demos. Pure assets canister, no backend.
Installation
pip install ic-basilisk-toolkit
For shell/SFTP support (requires asyncssh):
pip install ic-basilisk-toolkit[shell]
CLI Usage
basilisk-toolkit exec 'print("hello")' # Execute code on canister
basilisk-toolkit shell --canister my_app --network ic # Interactive shell
basilisk-toolkit sshd --canister my_app --network ic # SSH/SFTP server
Schema Upgrade Checking & Data Browsing
See docs/SCHEMA_UPGRADE_CHECKING.md for the full guide on pre-deploy schema diffing, step-by-step migration examples, verbose mode, on-chain enforcement, and the read-only __browse__ query API.
Security note: The
sshdcommand starts a local development proxy that accepts any password. It is intended for local use only — do not expose it on a public network without adding proper authentication.
Dependencies
- ic-basilisk — CDK (types, decorators,
ic.*API) - ic-python-db — Persistent entity ORM
- ic-python-logging — Structured logging
Disclaimer
This software is not production-ready. Do not deploy to mainnet or use with real assets or canister state you cannot afford to lose.
This software is in early development (alpha). It may contain bugs, breaking changes, and unknown security vulnerabilities. It has not undergone an independent security audit. Use at your own risk — see the Basilisk disclaimer for additional context.
- Not recommended for production deployments on the Internet Computer
- No guarantee of correctness, availability, or security
- APIs and behavior may change without notice
License
MIT — see LICENSE.
Release files for ic-basilisk-toolkit 0.5.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ic_basilisk_toolkit-0.5.3.tar.gz | 199.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ic_basilisk_toolkit-0.5.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 323.2 kB
Release files / ic_basilisk_toolkit-0.5.3.tar.gz
| Download URL | ic_basilisk_toolkit-0.5.3.tar.gz |
|---|---|
| Size | 199.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8020a0cea85cc5c542e95647b28e20a8ad55caf2cfa82087ce957cc14725841b
|
|
BLAKE2b-256 checksum How to use checksums |
124edea8e4b1a1ead0247d6fbdd5cf7d9ac4ace7a82bd0285e24590690fc0da4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Release files / ic_basilisk_toolkit-0.5.3-py3-none-any.whl
| Download URL | ic_basilisk_toolkit-0.5.3-py3-none-any.whl |
|---|---|
| Size | 123.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19e9ef1f40ee39541056b4b245c3a2b7c55a7f679e740a445d3f304609a471fb
|
|
BLAKE2b-256 checksum How to use checksums |
5831ead95670fc2a53e457b232c9ce8c3aca772b7f4160eb2669b65a448c539e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|