Builder Guide

🚧

Suzaku is in testnet phase. This documentation is subject to change.

During Suzaku's testnet, we offer Avalanche L1 builders to become permissionless Suzaku-secured networks.

This guide walks you through the process of becoming a Suzaku Network.

Suzaku Core L1 interactions

⚠️

Suzaku is a very modular protocol with many smart contracts involved. L1 builders looking to leverage Suzaku to enhance their decentralization and security are encouraged to reach out via X (opens in a new tab) or Discord (opens in a new tab).

Suzaku is a permissionless protocol that allows any entity to register as a Suzaku L1, opt-in to Vaults and expand their chain's validator set.

Requirements

suzaku-cli (opens in a new tab) installed
A private key for the L1 owner with AVAX balance on the C-Chain
An Avalanche L1 live on Fuji with the Validator Manager contract on the C-Chain

BalancerValidatorManager deployment

🚧

This section is under construction.

See the DeployBalancerValidatorManager.s.sol (opens in a new tab) Forge script.

L1 Middleware deployment

🚧

This section is under construction.

See the MiddlewareL1.s.sol (opens in a new tab) Forge script.

Setup the L1 Middleware as Security Module:

BALANCER_VALIDATOR_MANAGER=...
L1_MIDDLEWARE=...
SECURITY_MODULE_MAX_WEIGHT=200000
pnpm cli --network fuji balancer-set-up-security-module $BALANCER_VALIDATOR_MANAGER $L1_MIDDLEWARE $SECURITY_MODULE_MAX_WEIGHT --private-key $PK

The arguments are:

BALANCER_VALIDATOR_MANAGER: The BalanceValidatorManager address, deployed previously
L1_MIDDLEWARE: The AvalancheL1Middleware address, deployed previously
SECURITY_MODULE_MAX_WEIGHT: The total maximum weight in the P-Chain for the validators that are managed by the security module being set up, here the AvalancheL1Middleware

See Progressive Decentralization to learn more about BalanceValidatorManager and AvalancheL1Middleware.

(Optional) Verify the Security Module has been set up:

pnpm cli --network fuji balancer-get-security-modules $BALANCER_VALIDATOR_MANAGER

L1 registration in the L1 Registry

BALANCER_VALIDATOR_MANAGER=...
L1_MIDDLEWARE=...
L1_METADATA_URL=https://l1.com
pnpm cli --network fuji --private-key $PK register-l1 $BALANCER_VALIDATOR_MANAGER $L1_MIDDLEWARE $L1_METADATA_URL

The arguments are:

BALANCER_VALIDATOR_MANAGER: The BalanceValidatorManager address, deployed previously
L1_MIDDLEWARE: The AvalancheL1Middleware address, deployed previously
L1_METADATA_URL: URL to a JSON file providing metadata for the L1, format is TBD, in the meantime L1s are encouraged to use any link to a website or social media profile

Registering an L1 in the L1 Registry costs 1 $AVAX (0.1 $AVAX in Fuji). This is to avoid malicious actors to flood the protocol.

(Optional) Verify the L1 is registered in the L1 Registry:

pnpm cli --network fuji get-l1s

Vault registration in MiddlewareVaultManager

⚠️

Stake vs Weight

In a typical Suzaku L1 setup, the BalancerValidatorManager manages 2 security modules: a PoASecurityModule and a AvalancheL1Middleware, each managing a portion of the total weight of the Avalanche L1 as tracked in the P-Chain. Assets deposited in Vaults are denominated in stake from which the AvalancheL1Middleware will calculate a corresponding weight.

MIDDLEWARE_VAULT_MANAGER=...
VAULT=0x85F212C69f0C567011E1eCFf956dCc0014754A2c
ASSET_CLASS=1
MAX_LIMIT=200000000000000000000000
pnpm cli --network fuji --private-key $PK vault-manager-register-vault-l1 $MIDDLEWARE_VAULT_MANAGER $VAULT $ASSET_CLASS $MAX_LIMIT

The arguments are:

MIDDLEWARE_VAULT_MANAGER: the address of the MiddlewareVaultManager.
VAULT is the address of a Vault. The Suzaku team has deployed a Vault on the Fuji testnet at address. 0x85F212C69f0C567011E1eCFf956dCc0014754A2c (opens in a new tab) for testing purposes.
ASSET_CLASS is 1 since we are setting up a Vault for the Primary Asset Class is the first requirement before adding other asset classes.
MAX_LIMIT is the maximum stake the L1 can receive from this Vault. It is set to an arbitrary high value of 200,000 sAVAX in the example and can be adapted accordingly.

This command calls SetMaxL1Limit on the L1RestakeDelegator contract managed by the Curator.

Set L1 limit

DONE BY THE L1???

DELEGATOR=...
L1_LIMIT=100000000000000000000000
ASSET_CLASS=1
pnpm cli --network fuji --private-key $PK set-l1-limit $DELEGATOR $BALANCER_VALIDATOR_MANAGER $L1_LIMIT $ASSET_CLASS

The arguments are:

DELEGATOR it the address of the L1RestakeDelegator
L1_LIMIT is the maximum stake the L1 can receive from the L1RestakeDelegator. It is set to an arbitrary high value of 200,000 sAVAX in the example and can be adapted accordingly.
ASSET_CLASS is 1 since we are setting the maxium stake for the Primary Asset Class.

Operator registration in L1

L1_MIDDLEWARE=...
OPERATOR=0xfFF4224c953682C0866cb45643512D8Eee6eB608
pnpm cli --network fuji --private-key $PK middleware-register-operator $L1_MIDDLEWARE $OPERATOR

The arguments are:

L1_MIDDLEWARE: the address of the AvalancheL1Middleware.
OPERATOR: the address of an Operator registered in the Operator Registry and opted-in to the L1 (see Operator Guide).

At this point, everything is setup on the L1 side and the Curator can delegate stake to an Operator, see Curator Guide.

LST-as-a-Service For Operators