Skip to main content

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 ic-python-db API (TodoList.create(...), TodoList.instances(), TodoList.count(), TodoList.find({...}), lst.title = "x" auto-saves) — always Cedar-filtered to rows the caller may see. Every change crosses a host RPC gated by Cedar owner policies. See the todo_list template and how the sandbox/Cedar/RPC pipeline works.

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 (_basilisk_cedar). Policy text is tracked in Python (the native module does not export loaded policies). Use reload_policies() to hot-swap extra permits at runtime; __cedar__ shows what is currently loaded.

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 sshd command 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

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

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ic-basilisk-toolkit 0.5.1
File Size Uploaded
ic_basilisk_toolkit-0.5.1.tar.gz 190.6 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for ic-basilisk-toolkit 0.5.1
File Interpreter ABI Platform
ic_basilisk_toolkit-0.5.1-py3-none-any.whl Python 3 none any Details

Total release size: 306.0 kB

Release files / ic_basilisk_toolkit-0.5.1.tar.gz

Download URL ic_basilisk_toolkit-0.5.1.tar.gz
Size 190.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1b1644d96a70bba1aea0f2f4cc2ca97b3bf95afa42b0e22641ae6c798fb97584
BLAKE2b-256 checksum
How to use checksums
034abb8b07581f0eb913d448d85562dfad95342e1b03c2e49c81f1b914ade265
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.1-py3-none-any.whl

Download URL ic_basilisk_toolkit-0.5.1-py3-none-any.whl
Size 115.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4a85000591c733188d637d6f59b581ebe00cd10ef2027d36ab0e052c1f72077c
BLAKE2b-256 checksum
How to use checksums
2780101c456f46b0d1bce9c4d30e16e0ca32f05b25d4388e568c5b517238ec33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.20

Release history Release notifications | RSS feed

0.5.3

2 release files

0.5.2

2 release files

This release

0.5.1 This release

2 release files

0.5.0

2 release files

0.4.0

2 release files

0.3.0

2 release files

0.2.1

2 release files

0.2.0

2 release files

0.1.7

2 release files

0.1.6

2 release files

0.1.5

2 release files

0.1.4

2 release files

0.1.3

2 release files

0.1.2

2 release files

0.1.1

2 release files

0.1.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page