host.gno

 1package vmkit
 2
 3import "errors"
 4
 5// ErrNotGranted is returned by a [Host] for a capability the instance was
 6// never given. A guest that ignores the error and keeps going is a guest bug;
 7// a machine should turn it into a [Trapped] status.
 8var ErrNotGranted = errors.New("vmkit: capability not granted")
 9
10// Host is everything a guest program can reach outside its own memory.
11//
12// It is deliberately small, and deliberately handed in rather than looked up:
13// a guest has exactly the authority its [Host] carries. Gno realm code has
14// ambient authority through the realm frame, so the guest is where the
15// capability-secure version can actually be tried.
16//
17// Every method must be deterministic across replays of the same block. Now
18// and Height come from the chain, never from a wall clock.
19type Host interface {
20	// Caller is the address that called the realm running this guest.
21	Caller() address
22	// Origin is the address that signed the transaction.
23	Origin() address
24	// Now is block time in Unix seconds, never wall time.
25	Now() int64
26	// Height is the block height.
27	Height() int64
28
29	// Get reads from storage scoped to this instance. A miss is nil.
30	Get(key []byte) []byte
31	// Set writes to storage scoped to this instance.
32	Set(key, val []byte)
33
34	// Input is the immutable call input for this slice of execution: the
35	// guest's calldata, argv, or stdin depending on the machine. A machine
36	// tracks its own read cursor, in its snapshot, so that resuming reads
37	// the byte it had not read yet.
38	Input() []byte
39	// Output appends to the guest's output buffer.
40	Output(p []byte)
41
42	// Emit writes a chain event. kv is a flat list of alternating keys and
43	// values; an odd trailing element is dropped.
44	Emit(typ string, kv ...string)
45	// Send transfers amount ugnot to `to`, and returns [ErrNotGranted]
46	// unless the deploying realm funded this instance with a budget.
47	Send(to address, amount int64) error
48	// Log records a diagnostic line. Never consensus-relevant.
49	Log(msg string)
50}