New Features
1. Broad stdlib support
2. Greatly expanded Python source code size limit
3. Various syntax changes that we hope improve the developer experience and solve various issues
4. Guard functions
5. Greatly improved error reporting
6. match function
Breaking Changes
Please follow this breaking change guide to ensure a smoother transition from previous versions of Kybra to version `0.5.0`.
It is recommended to do the following before starting a manual project migration:
1. delete `~/.config/kybra`
2. delete your local `venv`
3. delete your local `.dfx` directory
4. delete your local `.kybra` directory
opt is now Opt
`opt` has been renamed to `Opt`
Vec
The `Vec` type has been introduced, and it must be used in place of `list`.
Variant casing
Variants now follow conventions from Rust enums. The first letter will be uppercase and the rest camel case. For example, for the `Result` types `ok` is now `Ok` and `err` is now `Err`.
void is now required on system methods
All canister methods must have an explicit return type. In the case of certain system methods like `init` and `post_upgrade`, you must explicitly return `void`.
candid:service metadata is gone
For the time being the `candid:service` metadata has been removed and Kybra relies on the `__get_candid_interface_tmp_hack` canister method.
dfx.json
All `dfx.json` files must add the following to the canister objects:
Add the `post_install` script path:
json
"post_install": ".kybra/canister_name/post_install.sh"
Add `gzip` `true`:
json
"gzip": true
Remove `.gz` from the Wasm path:
json
"wasm": ".kybra/canister_name/canister_name.wasm"
StableBTreeMap memory ids
`StableBTreeMap` memory ids 0, 1, 2, 252, 253, 254 are now reserved. If you are using one of these memory ids then your application will break. Remember that migrating `StableBTreeMap`s is not well supported, be careful with trying to upgrade an existing canister in production using a `StableBTreeMap`.
None is no longer a type
`None` is not a Candid type anymore. It has been replaced by `null`.
Canister is now Service
`Canister` has been renamed to `Service`.
method is now service_query or service_update
The `method` decorator is now `service_query` or `service_update` depending on if the `Service` method is a query or an update method.
CanisterResult is now CallResult
`CanisterResult` has been renamed to `CallResult`.
manual is now Manual
`manual` has been renamed to `Manual`.
tuple is now Tuple
`tuple` has been renamed to `Tuple`.
alias is now Alias
`alias` has been renamed to `Alias`.
init and post_upgrade params
When adding `init` and `post_upgrade` params you must manually edit the Candid service and add the params on the first deploy. For more information see [The Kybra Book](https://demergent-labs.github.io/kybra/caveats.html#init-and-post_upgrade-params).
No encrypted dfx identities
Encrypted dfx identities are no longer supported. For more information see [The Kybra Book](https://demergent-labs.github.io/kybra/caveats.html#no-encrypted-dfx-identities).
Wasm module hash no longer useful
The Wasm module hash has been rendered unuseful. For more information see [The Kybra Book](https://demergent-labs.github.io/kybra/caveats.html#wasm-module-hash-now-less-useful).
ic.caller() in init and post_upgrade
When deploying with dfx, `ic.caller()` in `init` and `post_upgrade` will now be the canister's id and not the dfx identity's principal. For more information see [The Kybra Book](https://demergent-labs.github.io/kybra/caveats.html#iccaller-in-init-and-post_upgrade)
init under-the-hood nuances
In order to allow for larger Kybra Wasm modules and to enable the Python stdlib, we had to introduce some trade-offs into the `init` and `post_upgrade` processes:
1. The under-the-hood Rust `init` function of your application canister is never called directly, only the `post_upgrade` function. This function will call your Python `init` or `post_upgrade` function in a timer callback
2. When deploying to a local replica, errors from your `init` or `post_upgrade` will be logged from your replica, not from the `dfx deploy` process
3. When deploying to mainnet, errors from your `init` or `post_upgrade` will not be logged
4. Your canister will go through the following main steps when deploying: first a deployer canister Wasm binary will be deployed to the canister, then your application Wasm binary will be chunk uploaded to the deployer canister along with the Python stdlib, and finally the deployer canister will call `install_code` on itself with the full application Wasm binary
What's Changed
* Add support for arbitrary virtualenvs by dansteren in https://github.com/demergent-labs/kybra/pull/253
* timers can now do cross canister calls by lastmjs in https://github.com/demergent-labs/kybra/pull/252
* Seed the custom randomness by lastmjs in https://github.com/demergent-labs/kybra/pull/255
* Improved organization of generated code by dansteren in https://github.com/demergent-labs/kybra/pull/254
* Void and null by bdemann in https://github.com/demergent-labs/kybra/pull/251
* Function guards by bdemann in https://github.com/demergent-labs/kybra/pull/256
* add initial version of Kybra book by lastmjs in https://github.com/demergent-labs/kybra/pull/264
* adding a lot of documentation by lastmjs in https://github.com/demergent-labs/kybra/pull/265
* 271 embrace results by bdemann in https://github.com/demergent-labs/kybra/pull/274
* Remove cargo test by lastmjs in https://github.com/demergent-labs/kybra/pull/283
* Kybra rewrite by bdemann in https://github.com/demergent-labs/kybra/pull/262
* The kybra book by lastmjs in https://github.com/demergent-labs/kybra/pull/279
* Func type no longer needs a TypeAlias and the type errors are gone by lastmjs in https://github.com/demergent-labs/kybra/pull/312
* test nested tuples by bdemann in https://github.com/demergent-labs/kybra/pull/313
* complex init example by bdemann in https://github.com/demergent-labs/kybra/pull/314
* explicit voids for system canister methods by bdemann in https://github.com/demergent-labs/kybra/pull/315
* change method decorator to either update or query by bdemann in https://github.com/demergent-labs/kybra/pull/316
* 288 update function guards by bdemann in https://github.com/demergent-labs/kybra/pull/318
* re-export kybra management modules by bdemann in https://github.com/demergent-labs/kybra/pull/319
* threshold ecdsa by bdemann in https://github.com/demergent-labs/kybra/pull/321
* 284 all examples should use the pretest method like azle and node compatibility should be set to true and dfx generated not checked in by bdemann in https://github.com/demergent-labs/kybra/pull/322
* 285 make sure all examples and tests match azle for example there is no async heartbeat test for kybra but there is for azle by bdemann in https://github.com/demergent-labs/kybra/pull/323
* 304 match function by lastmjs in https://github.com/demergent-labs/kybra/pull/330
* 303 unify external canister with service by bdemann in https://github.com/demergent-labs/kybra/pull/328
* update manual reply example by bdemann in https://github.com/demergent-labs/kybra/pull/331
* Update candid by bdemann in https://github.com/demergent-labs/kybra/pull/338
* Call result by bdemann in https://github.com/demergent-labs/kybra/pull/339
* Book verification by bdemann in https://github.com/demergent-labs/kybra/pull/344
* Vec tuple wrappers by bdemann in https://github.com/demergent-labs/kybra/pull/349
* 351 make type capitalization more uniform in kybra types by bdemann in https://github.com/demergent-labs/kybra/pull/353
* Vec tuple documentation by bdemann in https://github.com/demergent-labs/kybra/pull/352
* 351 update documentation by bdemann in https://github.com/demergent-labs/kybra/pull/354
* update dfx by bdemann in https://github.com/demergent-labs/kybra/pull/357
* Fixed name collisions by dansteren in https://github.com/demergent-labs/kybra/pull/362
* 358 support creating stablebtreemaps with type annotations by bdemann in https://github.com/demergent-labs/kybra/pull/363
* Error infrastructure by bdemann in https://github.com/demergent-labs/kybra/pull/375
* 307 too many params by bdemann in https://github.com/demergent-labs/kybra/pull/376
* 325 remove fragile snippets by bdemann in https://github.com/demergent-labs/kybra/pull/381
* Check for multiple definitions by bdemann in https://github.com/demergent-labs/kybra/pull/383
* Changed runtime errors to bubble up correctly by dansteren in https://github.com/demergent-labs/kybra/pull/389
* 364 runtime errors by bdemann in https://github.com/demergent-labs/kybra/pull/388
* Fixed Guard Functions example by dansteren in https://github.com/demergent-labs/kybra/pull/401
* Refactored calls to global python functions by dansteren in https://github.com/demergent-labs/kybra/pull/402
* Implemented broad support for the Python stdlib in Kybra by lastmjs in https://github.com/demergent-labs/kybra/pull/413
* Kybra build optimizations by lastmjs in https://github.com/demergent-labs/kybra/pull/415
* add warning and protection for the pre_upgrade method by lastmjs in https://github.com/demergent-labs/kybra/pull/423
* attempt to retrieve candid in post_install by lastmjs in https://github.com/demergent-labs/kybra/pull/430
* remove candid metadata by lastmjs in https://github.com/demergent-labs/kybra/pull/432
* make candid parsing much more robust by lastmjs in https://github.com/demergent-labs/kybra/pull/434
* test out a couple fixes by lastmjs in https://github.com/demergent-labs/kybra/pull/436
* add chunk upload clearing, use secrets stdlib by lastmjs in https://github.com/demergent-labs/kybra/pull/438
* Documentation 0.5.0 by bdemann in https://github.com/demergent-labs/kybra/pull/356
**Full Changelog**: https://github.com/demergent-labs/kybra/compare/0.4.0...0.5.0