# ckb-std
[![Crates.io](https://img.shields.io/crates/v/ckb-std.svg)](https://crates.io/crates/ckb-std)

This library contains several modules that help you write CKB contract with Rust.

## Usage

[Documentation](https://docs.rs/ckb-std)

### Modules

* `syscalls` module: defines [CKB syscalls](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0009-vm-syscalls/0009-vm-syscalls.md)
* `high_level` module: defines high level APIs
* `dynamic_loading` module: dynamic loading primitives
* `debug!` macro: a `println!` like macro helps debugging
* `entry!` macro: defines contract entry point
* `default_alloc!` macro: defines global allocator for no-std rust
* `dummy_atomic` module: dummy atomic operations
* `logger` module: colored logger implementation
* `type_id` module: Type ID implementation (feature `type-id`)
### Memory allocator

Default allocator uses a mixed allocation strategy:

* Fixed block heap, only allocate fixed size(64B) memory block
* Dynamic memory heap, allocate any size memory block

User can invoke macro with arguments to customize the heap size. The default heap size arguments are:

(fixed heap size 4KB, dynamic heap size 516KB, dynamic heap min memory block 64B)

Use the macro with arguments to change it:

``` rust
default_alloc!(4 * 1024, 516 * 1024, 64)
```

> Beware, use difference heap size or memory block size may affect the verification result of the contract, some runtime errors such as **out of memory** may occur; you should always test the contract after customizing.

### Examples

Check `examples` and [tests](https://github.com/nervosnetwork/ckb-std/blob/master/contracts/ckb-std-tests) to learn how to use.

See also [ckb-tool](https://github.com/nervosnetwork/capsule/tree/develop/crates/testtool) which helps you write tests.


### Upgrading Issues

Starting from ckb-std 0.16.0, RISC-V atomic instructions are generated by
default. However, ckb-vm doesn't directly support atomic instructions. To
address this, ckb-std provides the following solutions:

1. Use the "dummy-atomic" feature (enabled by default)
2. Adjust Rust compilation flags by adding `-C target-feature=-a` to `RUSTFLAGS`

For more detailed information on compilation flags, refer to the [CKB Script Templates repository](https://github.com/cryptape/ckb-script-templates/tree/main?tab=readme-ov-file#molecule-uses-bytes-crates).