Miscellaneous API

#![allow(unused)]
fn main() {
value_return(value_len: u64, value_ptr: u64)
}

Sets the blob of data as the return value of the contract.

Panics
  • If value_len + value_ptr exceeds the memory container it panics with MemoryAccessViolation;
  • If value_len == u64::MAX and value_ptr points to an unused register it panics with InvalidRegisterId;
  • If the value is longer than max_length_returned_data (4 MiB) it panics with ReturnedValueLengthExceeded.

If value_return or promise_return is called more than once, the last call sets the return value.

#![allow(unused)]
fn main() {
panic()
}

Terminates the execution of the program with panic GuestPanic("explicit guest panic").

panic_utf8

#![allow(unused)]
fn main() {
panic_utf8(len: u64, ptr: u64)
}

Terminates the execution of the program with panic GuestPanic(s), where s is the given UTF-8 encoded string.

Normal behavior

If len == u64::MAX then treats the string as null-terminated with character '\0';

Panics
  • If string extends outside the memory of the guest with MemoryAccessViolation;
  • If string is not UTF-8 returns BadUTF8.
  • If the string length without the null-termination symbol, plus the bytes already logged in this function call, is larger than max_total_log_length (16,384 bytes), returns TotalLogLengthExceeded.

log_utf8

#![allow(unused)]
fn main() {
log_utf8(len: u64, ptr: u64)
}

Logs the UTF-8 encoded string.

Normal behavior

If len == u64::MAX then treats the string as null-terminated with character '\0';

Panics
  • If string extends outside the memory of the guest with MemoryAccessViolation;
  • If string is not UTF-8 returns BadUTF8.
  • If the string length without the null-termination symbol, plus the bytes already logged in this function call, is larger than max_total_log_length (16,384 bytes), returns TotalLogLengthExceeded.
  • If this function call already has max_number_logs (100) logs, returns NumberOfLogsExceeded.

log_utf16

#![allow(unused)]
fn main() {
log_utf16(len: u64, ptr: u64)
}

Logs the UTF-16 little-endian encoded string. len is the number of bytes in the string. See https://stackoverflow.com/a/5923961 that explains that null termination is not defined through encoding.

Normal behavior

If len == u64::MAX then treats the string as null-terminated with two-byte sequence of 0x00 0x00.

Panics
  • If string extends outside the memory of the guest with MemoryAccessViolation;
  • If len is odd and not u64::MAX, or the string is not UTF-16, returns BadUTF16;
  • If the UTF-16 length of the string, or the UTF-8 length of the decoded string, plus the bytes already logged in this function call is larger than max_total_log_length (16,384 bytes), returns TotalLogLengthExceeded;
  • If this function call already has max_number_logs (100) logs, returns NumberOfLogsExceeded.

abort

#![allow(unused)]
fn main() {
abort(msg_ptr: u32, filename_ptr: u32, line: u32, col: u32)
}

Special import kept for compatibility with AssemblyScript contracts. Not called by smart contracts directly, but instead called by the code generated by AssemblyScript.

Future Improvements

In the future we can have some of the registers to be on the guest. For instance a guest can tell the host that it has some pre-allocated memory that it wants to be used for the register, e.g.

set_guest_register

#![allow(unused)]
fn main() {
set_guest_register(register_id: u64, register_ptr: u64, max_register_size: u64)
}

will assign register_id to a span of memory on the guest. Host then would also know the size of that buffer on guest and can throw a panic if there is an attempted copying that exceeds the guest register size.