AckiNackiBlockManagerNodeWallet.sol

Overview

AckiNackiBlockManagerNodeWallet.sol implements a smart contract that serves as a wallet and manager node interface for block management within the Acki Nacki ecosystem. This contract manages licenses, rewards, slashing procedures, and interactions with root contracts and license management components. It handles staking, reward distribution, slashing penalties, and license lifecycle events. The contract ensures secure operations by enforcing ownership controls and validating message senders based on cryptographic keys and whitelist licenses.

The contract relies on external libraries and contracts such as BlockKeeperLib, LicenseBMContract, and BlockManagerContractRoot for calculations and coordination. It uses persistent state variables to track license details, wallet rewards and penalties, timing for reward epochs, and control flags for slashing and reward mechanisms.

Contract: AckiNackiBlockManagerNodeWallet

State Variables

• string constant version = "1.0.0"
  Version identifier of this contract.

• mapping(uint8 => TvmCell) _code
  Stores contract code cells, indexed by a byte identifier. Used for managing different contract codes like LicenseBM.

• uint256 static _owner_pubkey
  Immutable public key of the wallet owner, set at deployment.

• address _root
  Address of the root contract (likely BlockManagerContractRoot).

• optional(uint256) _license_num
  Optional license number currently assigned to this wallet.

• mapping(uint256 => bool) _whiteListLicense
  Whitelist of valid license numbers for this wallet.

• address _licenseBMRoot
  Address of the license block manager root contract.

• optional(uint32) _start_bm
  Optional start timestamp of the block manager operation.

• uint128 _wallet_reward
  Accumulated reward balance in the wallet.

• uint128 _slashSum
  Total slashed amount deducted from rewards/stake.

• uint32 _start_time
  Timestamp marking the wallet start time.

• uint32 _stop_seqno
  Sequence number of the last stop event.

• uint64 _waitStep
  Required wait period between certain wallet operations.

• uint32 _rewarded
  Timestamp of the last reward event.

• uint32 _epochStart
  Epoch start timestamp for reward calculation.

• uint64 _epochEnd
  Epoch end timestamp for reward calculation.

• uint64 _walletLastTouch
  Last block sequence number when wallet was touched/modified.

• bool _isSlashing
  Flag indicating whether the wallet is currently being slashed.

• uint32 _tryReward
  Sequence number of the last attempt to collect a reward.

• uint8 _walletTouch
  Minimal interval (in seqno) between wallet modifications.

• uint256 _signing_pubkey
  Public key used for signing operations by this wallet.

Constructor

constructor (
    TvmCell LicenseBMCode,
    mapping(uint256=>bool) whiteListLicense,
    address licenseBMRoot,
    uint32 start_time,
    uint64 waitStep,
    uint256 signing_pubkey,
    uint8 walletTouch
)

• Purpose: Initializes the wallet with license code, whitelist, root addresses, timing parameters, and keys.

• Parameters:

  • LicenseBMCode: Code cell for License Block Manager contract.

  • whiteListLicense: Mapping of valid license numbers.

  • licenseBMRoot: Address of license BM root contract.

  • start_time: Wallet start timestamp.

  • waitStep: Waiting interval for operations.

  • signing_pubkey: Public key to sign transactions.

  • walletTouch: Minimal seqno interval between wallet updates.

• Behavior: Validates the sender is the root contract, sets the initial state, and stores license whitelist and contract codes.

Public Methods

removeLicense

function removeLicense(uint256 license_number) public senderIs(...) accept

• Purpose: Removes the current license from the wallet.

• Parameters:

  • license_number: License number to remove.

• Requirements:

  • Caller must be the LicenseBM contract for the license number.

  • License must exist and match the given license number.

  • Wallet must not be active (_start_bm unset).

  • Sufficient wait time after stop sequence number.

• Effect: Resets license data and calls deleteWallet on the license contract with accrued rewards and slashing data.

• Usage: Called by license management contracts to revoke wallet licenses.

setSigningPubkey

function setSigningPubkey(uint256 pubkey) public onlyOwnerPubkey(_owner_pubkey) accept

• Purpose: Updates the wallet's signing public key.

• Parameters:

  • pubkey: New public key.

• Requirements:

  • Must be called by the owner.

  • Wallet must not be recently touched (enforced by _walletTouch).

• Effect: Updates _signing_pubkey and refreshes last touch timestamp.

setLicenseWhiteList

function setLicenseWhiteList(mapping(uint256 => bool) whiteListLicense) public onlyOwnerPubkey(_owner_pubkey) accept

• Purpose: Updates the whitelist of licenses.

• Parameters:

  • whiteListLicense: New whitelist mapping.

• Requirements:

  • Owner only.

  • Not recently touched.

  • Whitelist size must not exceed MAX_LICENSE_NUMBER_WHITELIST_BM.

• Effect: Replaces the existing whitelist.

addLicense

function addLicense(uint256 license_number, uint128 reward, uint128 slashSum) public senderIs(...) accept

• Purpose: Adds a license to the wallet.

• Parameters:

  • license_number: License number to add.

  • reward: Initial reward amount.

  • slashSum: Initial slashing sum.

• Requirements:

  • Caller must be the LicenseBM contract for the license.

  • No license currently assigned.

  • License is whitelisted.

• Effect: Assigns license and rewards or calls notAcceptLicense to reject.

slash

function slash() public senderIs(address(this))

• Purpose: Initiates slashing procedure on the wallet.

• Requirements:

  • License must exist.

  • Not already slashing.

• Effect: Marks slashing state, updates stop seqno and wallet touch, and requests reward from root contract if applicable. If conditions are unmet, calls finalSlash().

• Algorithm:

  • Checks reward timing and status.

  • If slashing or reward period conditions are met, calls finalSlash.

  • Otherwise, requests reward from root contract.

noRewards

function noRewards() public senderIs(_root) accept

• Purpose: Called by root contract to indicate no rewards are available.

• Effect: If slashing is active, finalizes slashing; resets reward try counter.

finalSlash

function finalSlash() private

• Purpose: Completes the slashing process by calculating the slash amount and notifying the root contract.

• Algorithm:

  • Calculates difference between wallet reward and previous slashes.

  • Calculates minimal stake to slash using gosh.calcminstakebm.

  • Caps slash to wallet balance.

  • Updates _slashSum and clears slashing flag.

  • Calls slashed on root contract with slash amount and license status.

withdrawToken

function withdrawToken(address to, varuint32 value) public view senderIs(...) accept

• Purpose: Allows license contract to withdraw tokens from the wallet.

• Parameters:

  • to: Recipient address.

  • value: Amount to withdraw.

• Requirements:

  • License must exist.

  • Wallet not active (_start_bm is null).

  • Wait time after stop sequence satisfied.

  • Sufficient balance.

• Effect: Transfers specified tokens to the recipient.

startBM

function startBM() public onlyOwnerPubkey(_owner_pubkey) accept

• Purpose: Starts block manager operation on this wallet.

• Requirements:

  • License exists.

  • Not already started.

  • Wait time after stop sequence satisfied.

  • Wallet not busy.

  • Sufficient stake balance.

• Effect: Sets _start_bm timestamp and notifies root contract to increase BM.

getReward

function getReward() public onlyOwnerPubkey(_owner_pubkey) accept

• Purpose: Requests reward from the root contract.

• Requirements:

  • License exists.

  • Block manager is started.

  • Reward epoch ended.

  • Wallet not busy.

• Effect: Updates last touch and tryReward, calls getReward on root contract.

takeReward

function takeReward(uint8 walletTouch, uint64 waitStep, uint32 epochStart, uint64 epochEnd) public senderIs(_root) accept

• Purpose: Receives reward payment and updates wallet timing parameters.

• Parameters:

  • walletTouch, waitStep, epochStart, epochEnd: Updated timing and epoch parameters.

• Effect: Adds reward value, updates internal state, and finalizes slashing if active.

stopBM

function stopBM() public onlyOwnerPubkey(_owner_pubkey) accept

• Purpose: Stops block manager operation.

• Requirements:

  • License exists.

  • Block manager started.

  • Wallet not busy.

• Effect: Calls root contract to get reward with stop flag, resets _start_bm, and records stop sequence number.

Internal / Private Methods

ensureBalance

function ensureBalance() private pure

• Purpose: Ensures the contract has sufficient balance to operate, minting tokens if below threshold.

• Behavior: If balance is below three times FEE_DEPLOY_BLOCK_MANAGER_WALLET, mints tokens.

Special Functions

receive() external

• Accepts incoming transfers with no data.

• Calls ensureBalance to maintain minimal balance.

Getters

getDetails

function getDetails() external view returns(
    uint256 pubkey,
    address root,
    uint256 balance,
    optional(uint256) license_num,
    uint128 minstake,
    uint256 signerPubkey
)

• Purpose: Returns key wallet details.

• Returns:

  • Owner public key.

  • Root contract address.

  • Current wallet token balance.

  • Optional license number.

  • Minimal stake calculated using current rewards and time.

  • Signing public key.

getVersion

function getVersion() external pure returns(string, string)

• Purpose: Returns version string and contract name.

• Returns: Tuple with version and contract identifier.

Important Implementation Details & Algorithms

• License Management:
  The wallet maintains an optional license number and a whitelist of acceptable licenses. License contracts communicate with this wallet to add or remove licenses, and licenses are tightly controlled by verifying the sender's address via the BlockKeeperLib.calculateLicenseBMAddress function.

• Reward and Slashing Mechanism:
  Rewards accumulate in _wallet_reward, and slashing penalties accumulate in _slashSum. Slashing can be triggered internally, which calculates the slash amount based on the minimal stake required, the elapsed time, and the current wallet balance. Slashing disables reward collection until resolved.

• Timing Controls:
  Operations such as setting keys, starting/stopping block management, and withdrawing tokens require time checks against _walletLastTouch and _walletTouch to prevent rapid successive changes.

• Balance Management:
  The contract ensures it maintains a minimal balance by minting tokens if the balance drops below a threshold (3 times FEE_DEPLOY_BLOCK_MANAGER_WALLET).

• Root Contract Interaction:
  Communication with the root contract (_root) is essential for increasing block manager status, retrieving rewards, and reporting slashing events.

Interaction with Other System Components

• LicenseBMContract:
  The wallet interacts with license block manager contracts to accept or reject licenses, delete wallets, and manage license lifecycle events.

• BlockManagerContractRoot:
  The root contract is notified upon starting, stopping, slashing, or requesting rewards. These interactions use small token values (0.1 vmshell) to trigger contract calls.

• BlockKeeperLib:
  Provides utility functions such as address calculations for license BM contracts and version checks.

• gosh System Namespace:
  Used for minting tokens and calculating minimal stakes (gosh.calcminstakebm).

Diagram: Contract Structure and Main Methods

classDiagram
class AckiNackiBlockManagerNodeWallet {
-string version
-mapping _code
-uint256 _owner_pubkey
-address _root
-optional _license_num
-mapping _whiteListLicense
-address _licenseBMRoot
-optional _start_bm
-uint128 _wallet_reward
-uint128 _slashSum
-uint32 _start_time
-uint32 _stop_seqno
-uint64 _waitStep
-uint32 _rewarded
-uint32 _epochStart
-uint64 _epochEnd
-uint64 _walletLastTouch
-bool _isSlashing
-uint32 _tryReward
-uint8 _walletTouch
-uint256 _signing_pubkey
+constructor()
+removeLicense()
+setSigningPubkey()
+setLicenseWhiteList()
+addLicense()
+slash()
+noRewards()
-finalSlash()
+withdrawToken()
+startBM()
+getReward()
+takeReward()
+stopBM()
+ensureBalance()
+receive()
+getDetails()
+getVersion()
}

This diagram represents the contract properties and main methods, illustrating the encapsulated state and exposed functionality of the wallet node within the Acki Nacki block management system.