Persistent mode

In persistent mode, Saya fetches blocks from Katana, verifies proofs, and updates the core contract state on the settlement layer.

saya

Setup Katana

Katana must be configured in provable mode to work with Saya. First, initialize a new chain spec:

katana init --id per1 \
    --settlement-chain <Sepolia|Mainnet> \
    --settlement-account-address <ADDRESS> \
    --settlement-account-private-key <PRIVATE_KEY>

This automatically deploys a fresh core contract on the settlement layer. If you want to use a specific facts registry contract, set it via the settlement-facts-registry argument:

katana init --id per1 \
    --settlement-chain <Sepolia|Mainnet> \
    --settlement-account-address <ADDRESS> \
    --settlement-account-private-key <PRIVATE_KEY>
    --settlement-facts-registry <ADDRESS>

When working with Katana in provable mode, two additional parameters are required:

block-time: Since every block is proven, it is recommended to use a block time instead of the default mode where a block is mined for each transaction. This prevents overwhelming the prover with too many blocks and ensures consistent proving performance.
block-max-cairo-steps: In the current implementation of Katana, the default cairo steps limit in a block is 50 million. For provable mode with Saya, it is recommended to use 16 million to ensure the proving step succeeds reliably. This limit exists due to Cairo VM constraints and proving complexity - larger blocks may fail to prove or timeout.

katana --chain per1 \
    --block-time 30000 \
    --sequencing.block-max-cairo-steps 16000000

Run Saya

If you haven't already, consult the Herodotus guide to get an account and an API key.

If you are not running Saya in docker, you can download the SNOS program and the Layout Bridge program from the Saya releases. If you are running Saya in docker, the programs are already present in the /programs directory.

# .env.persistent
 
# The number of blocks to process in parallel in Saya.
BLOCKS_PROCESSED_IN_PARALLEL=60
 
# The database directory, to ensure long running queries are tracked
# and not re-run if Saya is restarted.
DB_DIR=/tmp/saya_persistent
 
# The Atlantic key, obtained from https://herodotus.cloud.
ATLANTIC_KEY=
 
# The path to the compiled SNOS program to be run against each block.
SNOS_PROGRAM=./programs/snos.json
 
# The path to the compiled layout bridge program to be run against each block.
LAYOUT_BRIDGE_PROGRAM=./programs/layout_bridge.json
 
# In persistent mode, the rollup RPC to pull the blocks from.
ROLLUP_RPC=http://0.0.0.0:5050
 
# Integrity verifier contract address.
# https://github.com/HerodotusDev/integrity/blob/main/deployed_contracts.md
SETTLEMENT_INTEGRITY_ADDRESS=0x04ce7851f00b6c3289674841fd7a1b96b6fd41ed1edc248faccd672c26371b8c
 
# Settlement chain.
SETTLEMENT_RPC=https://api.cartridge.gg/x/starknet/sepolia
SETTLEMENT_PILTOVER_ADDRESS=
SETTLEMENT_ACCOUNT_ADDRESS=
SETTLEMENT_ACCOUNT_PRIVATE_KEY=

Export those variables in your shell by sourcing the file or running:

export $(grep -v '^#' .env.persistent | xargs)

Then, you can start Saya with:

saya persistent start