Precompiled Smart Contracts

ZenChain supports precompiled smart contracts to improve the user experience. Precompiles work just like other smart contracts deployed on the network, yet are more computationally efficient than user-deployed smart contracts.

Contract	Ethereum Address	Solidity Interface	Description
NativeStaking	0x0000000000000000000000000000000000000800	GitHub	ZenChain staking
NativeFastUnstake	0x0000000000000000000000000000000000000801	GitHub	Fast unstake
KeyManager	0x0000000000000000000000000000000000000802	GitHub	Manage validator session keys
Batch	0x0000000000000000000000000000000000000803	GitHub	Efficient batch transactions
NativeCurrency	0x0000000000000000000000000000000000000804	GitHub	Use ZTC like a token
VaultStaking	0x0000000000000000000000000000000000000805	GitHub	ZenVault staking system
Treasury	0x0000000000000000000000000000000000000806	GitHub	Manage treasury address
ConfigurableStakingRewardCurve	0x0000000000000000000000000000000000000807	GitHub	Manage staking reward curve
System	0x0000000000000000000000000000000000000808	GitHub	Manage system-level operations

NativeStaking Precompile

This contract provides comprehensive staking functionality, including core staking operations and various view functions for querying system state and parameters.

Write Functions

Function	Description
bondWithRewardDestination(value, dest)	Stake ZTC and set reward destination.
bondWithPayeeAddress(value, payee)	Stake ZTC and set a custom payee address for rewards.
bondExtra(value)	Add more ZTC to your existing stake.
rebond(value)	Re-stake a portion of your unbonding ZTC.
unbond(value)	Schedule a portion of your staked ZTC for unbonding.
withdrawUnbonded(numSlashingSpans)	Withdraw your unbonded ZTC after the unbonding period.
validate(commission, blocked)	Declare intent to become a validator with specified commission and blocking status.
nominate(targets)	As a nominator, select the validators you want to back.
chill()	Stop validating or nominating.
setPayee(payee)	Set a custom address to receive rewards.
setRewardDestination(dest)	Set the reward destination (Staked, Stash, or None).
payoutStakersByPage(validatorStash, era, page)	Trigger payout of rewards for a specific validator, era, and page of nominators.
kick(nominators)	Kick specified nominators from a validator's list.
chillOther(stash)	Chill another stash account.
forceApplyMinCommission(validatorStash)	Force a validator to apply the minimum commission.

Admin Write Functions

Function	Description
addToValidatorWhitelist(stash)	Adds a validator's stash account to the whitelist.
removeFromValidatorWhitelist(stash)	Removes a validator's stash account from the whitelist.
setIsValidatorWhitelistEnabled(isEnabled)	Enables or disables the validator whitelist.
forceNewEra()	Force there to be a new era at the end of the next session.
forceUnstake(stash, numSlashingSpans)	Force a current staker to become completely unstaked, immediately.
setValidatorCount(count)	Sets the ideal number of validators.
setMinValidatorBond(minValidatorBond)	Sets the minimum active bond needed to be a validator.
setMinNominatorBond(minNominatorBond)	Sets the minimum active bond needed to be a nominator.
setMaxNominatorCount(maxNominatorCount)	Sets the max number of users who can be a nominator at once.
setMaxValidatorCount(maxValidatorCount)	Sets the max number of users who can be a validator at once.
setMinCommission(minCommission)	Sets the minimum amount of commission that each validators must maintain.

View Functions

Function	Description
idealValidatorCount()	Get the ideal number of validators.
minValidatorCount()	Get the minimum number of validators.
invulnerables()	Get the list of invulnerable validators.
minNominatorBond()	Get the minimum bond amount for nominators.
minValidatorBond()	Get the minimum bond amount for validators.
minActiveStake()	Get the minimum active nominator stake from the last election.
minValidatorCommissionPerbill()	Get the minimum validator commission.
payee(who)	Get the reward payee address for an account.
rewardDestination(who)	Get the reward destination for an account.
validatorPrefs(who)	Get validator preferences (commission and blocked status).
maxValidatorsCount()	Get the maximum number of validators.
nominatorPrefs(who)	Get nominator preferences (targets, submission era, and suppressed status).
maxNominatorsCount()	Get the maximum number of nominators.
currentEra()	Get the current era index.
activeEra()	Get the active era index.
erasStartSessionIndex(eraIndex)	Get the starting session index for a given era.
erasValidatorTotalStake(eraIndex, validatorStash)	Get total and own stake for a validator in a given era.
erasValidatorNominatorsCount(eraIndex, validatorStash)	Get nominator count and page count for a validator in a given era.
erasValidatorNominationPageTotalExposure(eraIndex, validatorStash, pageIndex)	Get total exposure for a specific page of nominators.
erasValidatorNominationPageNominatorExposure(eraIndex, validatorStash, pageIndex, nominationIndex)	Get stake and address for a specific nominator.
erasClaimedRewards(eraIndex, validatorStash, index)	Get claimed page index for rewards in a specific era.
erasValidatorPrefs(eraIndex, validatorStash)	Get validator preferences for a given era.
erasValidatorPayout(eraIndex)	Get total validator payout for a given era.
erasTotalRewardPoints(eraIndex)	Get total reward points for a given era.
erasValidatorRewardPoints(eraIndex, validatorStash)	Get reward points for a validator in a given era.
erasTotalStake(eraIndex)	Get total stake for a given era.
erasStakersPage(eraIndex, validatorStash, page)	Get the list of nominators with paged rewards for the given era, validator, and page.
maxStakedRewardsPercent()	Get maximum staked rewards percentage.
slashRewardFractionPerbill()	Get slash reward fraction.
cancelledSlashPayout()	Get cancelled slash payout amount.
currentPlannedSession()	Get the last planned session index.
isUnbonding(who)	Check if an account is unbonding.
status(who)	Get the staking status of an account.
stake(who)	Get the total and active stake of an account.
isExposedInEra(who, era)	Check if an account was exposed in a specific era.
bonded(who)	Check if an account is bonded.
validatorWhitelist()	Get the list of all validator addresses currently in the whitelist.
isWhitelistedValidator(stash)	Check whether the stash address is in the validator whitelist.
isValidatorWhitelistEnabled()	Check whether the validator whitelist is enabled.

Constants

Function	Description
historyDepth()	Get the number of eras stored in history.
sessionsPerEra()	Get the number of sessions per era.
bondingDuration()	Get the number of eras a staker's funds remain locked after unbonding request.
slashDeferDuration()	Get the number of eras that slashes are deferred.
maxExposurePageSize()	Get the maximum size of each ExposurePage.
maxUnlockingChunks()	Get the maximum number of unlocking chunks a StakingLedger can have.

This updated documentation now includes all the view functions and constants from the provided Solidity interface, offering a comprehensive overview of the NativeStaking precompile's capabilities.

NativeFastUnstake Precompile

This contract allows for quicker unbonding of your stake under the condition that the staker is not an active validator or nominating another account. If the staker's bond is locked in an ongoing era, it cannot be quickly unbonded because it must remain subject to rewards and slashing.

Function	Description
registerFastUnstake()	Initiate a fast unstake request.
deregister()	Cancel a fast unstake request and return to regular unbonding.

KeyManager Precompile

The KeyManager contract facilitates session key management for validators.

Function	Description
setKeys(bytes calldata keys)	Sets the session keys of the function caller to the provided keys. This allows an account to set its session keys prior to becoming a validator, and takes effect in the next session. Validators can be obtain keys from their node using the author_rotateKeys RPC method.
purgeKeys()	Removes any session keys associated with the function caller. This change will take effect in the next session.
keyOwner(KeyType keyType, bytes32 key)	Queries the owner of a specific session key. It returns the address of the key owner, or the zero address if no owner is found.

Batch Precompile

The Batch precompile contract provides methods for efficient batch transactions.

Function	Description
batchSome(address[] memory to, uint256[] memory value, bytes[] memory callData, uint64[] memory gasLimit)	Batches multiple calls into a single transaction, attempting all subcalls even if one or more revert.
batchSomeUntilFailure(address[] memory to, uint256[] memory value, bytes[] memory callData, uint64[] memory gasLimit)	Batches multiple calls into a single transaction. If a subcall reverts, no further subcalls are executed, but the transaction itself succeeds.
batchAll(address[] memory to, uint256[] memory value, bytes[] memory callData, uint64[] memory gasLimit)	Batches multiple calls into a single transaction. If any subcall reverts, the entire batch transaction reverts.

NativeCurrency Precompile

The NativeCurrency precompile contract allows users to interact with the native ZTC token using a standard ERC20/ZIP20 interface. It facilitates transferring ZTC, checking balances, spending approvals, spending permits, and other standard token operations.

Write Functions

Function	Description
transfer(to, value)	Transfers value amount of ZTC to the specified to address.
approve(spender, value)	Approves the spender to withdraw up to value amount of ZTC from the caller's account.
transferFrom(from, to, value)	Transfers value amount of ZTC from the from address to the to address. Requires prior approval from the from address.
permit(owner, spender, value, deadline, v, r, s)	Sets value as the allowance of spender over owner's ZTC, given owner's signed approval (EIP-2612).

View Functions

Function	Description
name()	Returns the name of the token (e.g., "ZenChain Token").
symbol()	Returns the symbol of the token (e.g., "ZTC").
decimals()	Returns the number of decimal places the token uses.
totalSupply()	Returns the total amount of ZTC in existence.
balanceOf(who)	Returns the token balance of the specified who address.
allowance(owner, spender)	Returns the amount of ZTC that the owner has allowed the spender to withdraw.
nonces(owner)	Returns the current EIP-2612 permit nonce for the owner address.
DOMAIN_SEPARATOR()	Returns the EIP-712 domain separator for EIP-2612 permit signatures.
getFacilitator(facilitator)	Returns the bucket capacity, bucket level, and label of a specified facilitator.
getFacilitators()	Returns a list of active facilitator addresses.
getAdmin()	Gets the admin address, which can set minter capacity.

Events

Event	Description
Transfer(address indexed from, address indexed to, uint256 value)	Emitted when ZTC are transferred from one account to another.
Approval(address indexed owner, address indexed spender, uint256 value)	Emitted when an owner approves a spender to withdraw ZTC from their account.
FacilitatorAdded(address indexed facilitator, string label, uint256 capacity)	Emitted when a new facilitator is added to the system.
FacilitatorRemoved(address indexed facilitator)	Emitted when a facilitator is removed from the system.
FacilitatorCapacityUpdated(address indexed facilitator, uint256 oldCapacity, uint256 newCapacity)	Emitted when a facilitator's bucket capacity is updated.
FacilitatorBucketLevelUpdated(address indexed facilitator, uint256 oldLevel, uint256 newLevel)	Emitted when a facilitator's bucket level changes due to minting or burning.

VaultStaking Precompile

The VaultStaking precompile allows users to interact with the ZenVault staking system. This system enables users to participate in ZenChain staking indirectly through ZenVault smart contracts by depositing ZenSwap liquidity pool (LP) tokens. The precompile facilitates vault registration, updates, reward distribution, and slashing.

Write Functions

Function	Description
updateVault(address vaultAddress)	Synchronizes the vault's virtual bond with the current state of the underlying staking system.
distributeRewards(address vaultAddress)	Transfers accumulated staking rewards from the reward account to the ZenVault contract and distributes them to stakers.

Admin Write Functions

Function	Description
applyPendingSlash(address vaultAddress)	Applies any pending slash for a specific vault.
registerVault(address vaultAddress)	Registers a new vault.
deregisterVault(address vaultAddress)	Deregisters an existing vault.
setNominations(address vaultAddress, targets)	Sets the nomination targets for a vault.

View Functions

Function	Description
vaults(address vaultAddress)	Returns the details of a specific vault, including address, pool address, token address, reward account, virtual bond, and last update era.
getAllVaults()	Returns a complete list of all registered vaults in the system.
pendingSlashes(address vaultAddress)	Returns the pending slashes for a specific vault.
lastBondUpdateEra()	Returns the last era index when vault bond updates were processed.
vaultBondUpdateQueue()	Returns the queue of vaults pending bond updates.

Treasury Precompile

The Treasury precompile allows for management of the treasury address in the system. The treasury is a designated account that can receive funds for various protocol operations. Staking rewards are distributed from the treasury account.

Admin Write Functions

Function	Description
setTreasury(new_treasury)	Updates the treasury address in the system.

View Functions

Function	Description
treasury()	Retrieves the current treasury address. Returns the address of the configured treasury account, or the zero address if no treasury is set.

Events

Event	Description
NewTreasury(address indexed treasury)	Emitted when a new treasury address is set in the system.

ConfigurableStakingRewardCurve Precompile

The ConfigurableStakingRewardCurve precompile allows for management of the staking reward curve in the system.

Admin Write Functions

Function	Description
setRewardCurve(minInflation, maxInflation, idealStake, falloff, maxPieceCount, testPrecision)	Sets the reward curve for staking.

Events

Event	Description
NewRewardCurve(minInflation, maxInflation, idealStake, falloff, maxPieceCount, testPrecision)	Emitted when a new reward curve is set in the system.

System Precompile

The System precompile allows for management of system-level operations, such as runtime upgrades.

Admin Write Functions

Function	Description
authorizeUpgrade(codeHash)	Authorize an upgrade to a given codeHash for the runtime.
applyAuthorizedUpgrade(code)	Provide the preimage (runtime binary) code for an upgrade.
setCode(code)	Sets the new runtime code for the blockchain.
noteStalled(delay, bestFinalizedBlockNumber)	Notes that the finality gadget has stalled.

View Functions

Function	Description
authorizedUpgrade()	Checks for a pending authorized runtime upgrade.
lastRuntimeUpgradeSpecVersion()	Retrieves the spec version of the last successful runtime upgrade.
stalled()	Indicates whether the finality gadget is currently stalled.
nextForced()	Returns the block number when a forced change of authorities will occur.

Events

Event	Description
NewRuntime(codeHash)	Emitted when a new runtime has been successfully applied.
RuntimeUpgradeAuthorized(codeHash)	Emitted when a runtime upgrade has been authorized.
FinalizationStallNoted(delay, bestFinalizedBlockNumber)	Emitted when a finalization stall has been noted.