Built-ins

Lithe has no magic globals. Execution context comes from Evm, hashing from Crypto, and encoding from Abi. Every call names where its value comes from, so a search for Evm. finds every place a contract depends on its environment.

Each of these is a module of the standard library, declared in its own file, and a file imports the ones it uses as it imports any module. A file that doesn't import std/evm doesn't read the caller, the block, or balances, and its first lines say so.

Using one without its import is the error any unknown name is, with the import to add:

storage is record {
  owner : address;
}
 
external function claim() is {
  storage.owner := Evm.sender();
}

unknown name `Evm`

`Evm` is declared in `std/evm`: `import "std/evm";`

An alias qualifies the module as it does any other: after import "std/evm" as Chain;, the caller is Chain.Evm.sender(). A file that doesn't import std/evm can declare a module of its own named Evm.

The compiler implements these modules' members. Each file declares its members with intrinsic, with a signature where Lithe can write one, and a comment that editors show on hover. A member whose arguments vary in number or type, such as Abi.encode, or whose width comes from the context, such as Uint.max, has no signature, and its row below says what it takes. Only the standard library declares an intrinsic.

The language's own names need no import: types, literals, conversions such as uint(x), Some and None, and assert, fail, and forward.

Evm

Execution context, from import "std/evm";. Readable in view and stateful functions, and not in pure functions.

Message

Transaction

Block

Accounts

Sending ether

Evm.transfer builds an operation, so it is only valid after defer, in a stateful function: defer Evm.transfer(to, amount);. See Queries and deferred calls.

Raw calls

Evm.call and Evm.delegateCall are deferred, and a continuation gets the return data as bytes. Evm.staticCall runs with query. See Raw calls.

Reading Evm.value() outside a payable function is an error, so a function cannot rely on ether it could never receive:

import "std/evm";
 
storage is record {
  n : uint;
}
 
external function go() is {
  const x : wei := Evm.value();
  skip
}

external function `go` reads `Evm.value()`; write `external payable function`

Target fork

Evm.osaka is a bool constant: whether the code is built for Osaka or later, as --evm-version sets. Unlike the rest of Evm, a pure function can read it. An if on it builds only the branch for the target. Both branches are still checked:

import "std/evm";
import "std/uint";
 
storage is record {
  n : uint;
}
 
external pure function bitLength(const x : uint) : uint is
  if Evm.osaka then 256 - Uint.clz(x) else {
    var n : uint := 0;
    for _ : uint in 0 .. 256 until x >> n = 0 do {
      n := n + 1;
    }
  } with n

Uint.clz works on every fork. The branch is worth writing only when the older fork has a cheaper way than the built-in's own fallback.

Crypto

Hash functions and signature recovery, from import "std/crypto";. Usable in any function, pure ones included.

To hash several values, encode them first: Crypto.keccak256(Abi.encode(a, b)).

The hash of a string or hex literal is a constant: Crypto.keccak256("MINTER_ROLE") compiles to the 32-byte word, as Solidity's keccak256("MINTER_ROLE") in a constant does. Write typehashes and role ids this way rather than pasting the hash.

Precompiles

Every precompiled contract is a built-in, given its input as the precompile lays it out. Like the hashes, they are usable in pure functions.

BLS12-381 points and field elements are bytes in EIP-2537's encoding: a field element is 64 bytes, a G1 point 128, and a G2 point 256.

A precompile that rejects its input, such as a point off its curve, reverts the transaction, except where the result is a bool: kzgPointEvaluation and p256Verify answer false for a proof or signature that does not verify. The pairings answer whether the product of pairings is one, and revert on malformed input.

Each call also checks the size of the answer. On a chain without the precompile, the call reaches an account with no code, which succeeds with no answer: that reverts, or reads as false, never as zeros. Crypto.p256Verify answers false on chains before EIP-7951; WebAuthn.verifySignature in std/crypto/webauthn falls back to Solady's verifier contract there.

The identity precompile, 0x04, copies its input, which a value already is. query Evm.staticCall(to, data) reaches any precompile directly.

Abi

ABI encoding and decoding, from import "std/abi";. Usable in any function, pure ones included.

Abi.decode takes a type name as its second argument: Abi.decode(data, uint), which decodes one value, as Solidity's abi.decode(data, (uint256)). Any ABI value can be decoded; name a list or record type first, as type ids is list(uint);, then Abi.decode(data, ids). A tuple of type names decodes one value of each, as abi.decode(data, (address, uint256)) does: const (who, amount) : (address, uint) := Abi.decode(data, (address, uint));. Malformed data reverts, with Solidity's checks on every offset, length, and word.

Abi.encode takes any ABI values, each one argument: a record or tuple is a Solidity tuple. Abi.encodePacked packs what Solidity's abi.encodePacked does: words, strings, bytes, and lists of words, each element padded to 32 bytes. It has no layout for records, tuples, nested lists, or lists of strings or bytes.

import "std/abi";
import "std/crypto";
import "std/evm";
 
storage is record {
  digest : bytes32;
}
 
external function commit(const amount : uint; const salt : bytes32) is {
  storage.digest := Crypto.keccak256(Abi.encode(Evm.sender(), amount, salt));
}
 
external pure function roundTrip(const n : uint) : uint is
  Abi.decode(Abi.encode(n), uint)
 
external pure function transferCall(const to : address; const amount : uint) : bytes is
  Abi.encodeWithSignature("transfer(address,uint256)", to, amount)

Bytes and String

From import "std/bytes"; and import "std/string";.

import "std/bytes";
import "std/string";
 
storage is record {
  greeting : string;
}
 
external function greet(const name : string) is {
  storage.greeting := String.concat("hello, ", name, "!");
}
 
external pure function tagged(const tag : bytes4; const data : bytes) : bytes is
  Bytes.concat(tag, data)
 
external pure function attribute(const name : string; const value : string) : string is
  String.concat("{\"trait_type\":\"", String.escapeJson(name), "\",\"value\":\"", String.escapeJson(value), "\"}")

Searching strings is in the standard library's Strings. A slice passed to Bytes.concat or Crypto.keccak256 is read where it lies, not copied first.

bytes values index and slice as in Solidity. Each works on parameters, locals, stored values, and call results such as Evm.calldata():

A single byte can't be assigned: build a new value from slices with Bytes.concat.

import "std/abi";
import "std/crypto";
import "std/evm";
 
storage is record {
  forwarder : address;
}
 
(* ERC-2771: a trusted forwarder appends the original sender to the calldata. *)
external view function msgSender() : address is {
  const data : bytes := Evm.calldata();
  var sender : address := Evm.sender();
  if sender = storage.forwarder and data.length >= 20 then {
    sender := address(bytes20(data[data.length - 20:]));
  }
} with sender
 
(* The payload of a custom error `LowBalance(uint256)`, from its revert data. *)
external pure function lowBalance(const reason : bytes) : uint is {
  var have : uint := 0;
  if reason.length >= 36 and bytes4(reason) = bytes4(Crypto.keccak256("LowBalance(uint256)")) then {
    have := Abi.decode(reason[4:], uint);
  }
} with have

Base64

RFC 4648 base64, from import "std/base64";, with the same algorithm and lookup tables as Solady's Base64. Usable in any function, pure ones included. data is bytes or string.

Like Solady's, Base64.decode does not check its input. A character Solady's lookup table covers decodes as it does there: [ as 63, and other characters outside both alphabets below { as zero bits. So do { to DEL and the control characters, and a byte from 0x80 up decodes as its low seven bits.

import "std/base64";
import "std/string";
 
storage is record {
  n : uint;
}
 
external pure function contractURI() : string is
  String.concat("data:application/json;base64,", Base64.encode("{\"name\":\"Badge\"}"))

List

From import "std/list";.

xs is a stored list or a var, and List.push(xs, v); and List.pop(xs); are statements: they write xs as an assignment would, so a view function cannot push to or pop a stored list. A stored list clears the element's slots. To remove an element from the middle, move the last one into its place first:

import "std/list";
 
storage is record {
  ids : list(uint);
}
 
external function remove(const i : uint) is {
  storage.ids[i] := storage.ids[storage.ids.length - 1];
  List.pop(storage.ids);
}

List.resized is an expression, and works on any dynamic list: a parameter, a local, or a stored list, which it reads. The padding is the value unwritten storage reads as: zero words, empty strings, bytes, and lists, None, and a variant's first case. Sizing a list once and writing its elements costs less than pushing them one by one:

import "std/list";
 
storage is record { n : uint; }
 
external pure function squares(const n : uint) : list(uint) is {
  var xs : list(uint) := List.resized([], n);
  for i : uint in 0 .. n do {
    xs[i] := i * i;
  }
} with xs

Uint, Int, and Address

From import "std/uint";, import "std/int";, and import "std/address";. Constants take their width from the type the context expects. With no expected type, they are 256-bit.

import "std/int";
import "std/string";
import "std/uint";
 
storage is record {
  cap : uint8;
  label : string;
}
 
external function name(const id : uint) is {
  storage.label := String.concat("token #", Uint.toString(id));
}
 
external function reset() is {
  storage.cap := Uint.max;
}
 
external pure function bounds() : (int16, int16) is
  (Int.min, Int.max)
 
external pure function elapsed(const later : uint32; const earlier : uint32) : uint32 is
  Uint.wrappingSub(later, earlier)

Here storage.cap := Uint.max stores 255, because the target is a uint8, and elapsed(1, 3) is 4294967294: the difference wraps to 32 bits.

Some and None

Some(x) and None build options.

Conversions

A type name used as a function converts to it: uint(x), uint8(n), int(n), address(b), bytes20(a), wei(n), timestamp(n), and the names of your own nominal types. See Conversions.