App Circuit Interface

Your circuit needs to implement the AppCircuit interface to be used with the Brevis SDK.

type AppCircuit interface {
	Define(api *CircuitAPI, input CircuitInput) error
	Allocate() (maxReceipts, maxStorage, maxTransactions int)
}

Define

Define defines your app circuit logic. The code you write in Define is a set of instructions that tells the framework "how to build the circuit". You could use if statements and loops for constructing the circuit, but as soon as the circuit is compiled, meaning the ifs and loops are run to build the circuit, the wiring is set in stone and there is no more concept of ifs and loops.

The first parameter api *CircuitAPI contains a set circuit building blocks. Read more

The second parameter input CircuitInput contains the data you want to process in the circuit. You should only need to access input.Receipts, input.StorageSlots, and input.Transactions. more on these data types

Allocate

You need to declare your data "slot" allocations because circuit inputs cannot be dynamic like data structures in normal programs.

The only thing you need to worry about is that when you add data into BrevisApp using AddReceipt, AddStorageSlot, and AddTransaction, the number of items you add to each type cannot exceed (but can be less than) the number you declare for that type.

For example, if this is your Allocate function:

func (c *AppCircuit) Allocate() (maxReceipts, maxStorage, maxTransactions int) {
    return 32, 0, 0
}

Then you can have a maximum of 1 receipt, 2 storage, and 3 transactions as data points. The sum of these values cannot exceed NumMaxDataPoints.

The less slots you allocate, the better your circuit will perform. You should always aim for allocating the least amount of slots possible. If you intend to build multiple circuits for your use case, the slot allocations for these circuits don't need to be the same.

For performance optimization, allocate maxReceipts/maxStorage/maxTransaction as an integral multiple of 32. 0 is allowed. Brevis app will use NextPowerOf2(maxReceipts+maxStorage+maxTransaction) as NumMaxDataPoints

Here is a visualization that may help you develop a mental model: