AckiNackiBlockKeeperNodeWallet.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the AckiNackiBlockKeeperNodeWallet contract. It specifies the contract's version, initialization parameters, internal state fields, and the complete set of callable functions with their input and output types. The contract serves as a wallet and stake manager for nodes participating in a block-keeping system that involves licensing, staking, and epoch management. The wallet manages licenses, stakes, slashing, and interactions with other contracts such as BlockKeeperEpoch and BlockKeeperPreEpoch.

Functionality includes license management (adding, removing, locking), stake operations (setting, updating, withdrawing), slashing penalties, deployment of epoch-related contracts, and communication with proxy lists. The wallet also holds details about the node's public keys, balances, and epoch-related parameters.

ABI Structure and Components

ABI Metadata

• ABI version: 2

• Contract version: 2.4

• Header fields: pubkey, time, expire — standard fields used in message headers for security and timing.

Fields (Contract State Variables)

Functions

The contract exposes numerous functions for managing node wallets, licenses, stakes, and related operations. The functions are listed below with detailed descriptions.

constructor

• Purpose: Initializes the contract with multiple code cells representing various components, epoch duration, licenses, and wallet parameters.

• Inputs:

  • BlockKeeperPreEpochCode (cell): Code cell for pre-epoch contract.

  • AckiNackiBlockKeeperNodeWalletCode (cell): Code cell for the wallet contract.

  • BlockKeeperEpochCode (cell): Code cell for epoch contract.

  • BlockKeeperEpochCoolerCode (cell): Code cell for epoch cooler contract.

  • BlockKeeperEpochProxyListCode (cell): Code cell for proxy list contract.

  • BLSKeyCode (cell): Code cell for BLS key management.

  • SignerIndexCode (cell): Code cell for signer index.

  • LicenseCode (cell): Code cell for license contract.

  • epochDuration (uint128): Duration of an epoch.

  • freeLicense (uint32): Number of free licenses.

  • whiteListLicense (map(uint256,bool)): Whitelist of licenses.

  • licenseRoot (address): Address of license root contract.

  • stakesCnt (uint8): Number of stakes allowed.

  • walletTouch (uint8): Wallet interaction flag or counter.

• Outputs: None

• Usage: Called once during contract deployment to initialize core parameters and code references.

setSigningPubkey

• Purpose: Sets the public key used for signing operations.

• Inputs:

  • pubkey (uint256): New signing public key.

• Outputs: None

• Usage: Updates the signing key, essential for verifying signatures on transactions.

setLockToStake / setLockToStakeByWallet

• Purpose: Locks or unlocks a license from staking, either directly or by wallet control.

• Inputs:

  • license_number (uint256): Identifier of the license.

  • lock (bool): True to lock, false to unlock.

• Outputs: None

• Usage: Controls staking eligibility of licenses.

removeLicense / deleteLicense

• Purpose: Removes or deletes a license from the wallet.

• Inputs:

  • license_number (uint256): License to remove.

• Outputs: None

• Usage: Used to revoke or clean up licenses.

setLicenseWhiteList

• Purpose: Updates the whitelist map of licenses.

• Inputs:

  • whiteListLicense (map(uint256,bool)): Updated whitelist.

• Outputs: None

• Usage: Adjusts the set of licenses allowed to participate.

addLicense

• Purpose: Adds a new license to the wallet.

• Inputs:

  • license_number (uint256): License identifier.

  • reputationTime (uint128): Reputation timestamp.

  • last_touch (uint64): Last interaction time.

  • isPrivileged (bool): Privilege flag.

• Outputs: None

• Usage: Registers a new license with initial parameters.

addBalance

• Purpose: Adds balance to a license.

• Inputs:

  • license_number (uint256): License to credit.

• Outputs: None

• Usage: Increases funds related to a license.

setLockStake / deleteLockStake / updateLockStake

• Purpose: Manage locked stakes with detailed license info and BLS keys.

• Inputs:

  • seqNoStart (uint64): Start sequence number.

  • seqNoFinish (uint64, only in updateLockStake): Finish sequence number.

  • stake (uint256): Amount staked.

  • bls_key (bytes): BLS public key bytes.

  • signerIndex (uint16): Index of the signer.

  • licenses (tuple[]): Array of licenses with numbers and stake amounts.

• Outputs: None

• Usage: Used to lock/unlock or update stake states for licenses with cryptographic verification keys.

slash / slashCooler / slashStake

• Purpose: Apply penalties (slashing) to stakes or licenses.

• Inputs vary but generally include:

  • slash_type (uint8): Type of slashing.

  • seqNoStart (uint64): Sequence number for stake.

  • slash_stake (uint128/uint256): Amount to slash.

  • License and BLS key info depending on method.

• Outputs: None

• Usage: Enforce penalties for misbehavior or protocol rules.

withdrawToken / withdrawWalletToken

• Purpose: Withdraw tokens from licenses or the wallet.

• Inputs:

  • license_number (uint256) or to (address): Target license or address.

  • value (varuint32): Amount to withdraw.

• Outputs: None

• Usage: Transfer tokens out of the wallet or license balances.

resetWallet

• Purpose: Reset the wallet state.

• Inputs: None

• Outputs: None

• Usage: Clears or reinitializes wallet internal state.

getDetails

• Purpose: Retrieves comprehensive wallet and stake details.

• Inputs: None

• Outputs: Multiple fields including:

  • pubkey, signerPubkey (uint256): Public keys.

  • root (address): Root address.

  • balance (uint256): Wallet balance.

  • activeStakes (map): Active stake details.

  • stakesCnt (uint8): Stake count.

  • licenses (map): License details.

  • epochDuration (uint128): Epoch length.

  • whiteListLicense (map): License whitelist.

• Usage: Provides a full snapshot for external queries or UI.

getEpochAddress / getSumBalanceForStake / getProxyListAddr / getProxyListCodeHash / getProxyListCode / getVersion

• Purpose: Getter functions for epoch address, total stake balance, proxy list addresses/codes, and contract version.

• Inputs: None

• Outputs: Corresponding data types.

• Usage: Retrieve specific contract state or metadata.

stakeNotAccepted / stakeNotAcceptedContinue / tryCooler / sendBlockKeeperRequestWithStake / sendBlockKeeperRequestWithCancelStakeContinue / cancelContinueStake / sendBlockKeeperRequestWithStakeContinue / deployPreEpochContract / deployBlockKeeperContractContinue / continueStakeNotAccept / continueStakeAccept / deployBlockKeeperContractContinueAfterDestroy / updateLockStakeCooler / unlockStakeCooler

• Purpose: These functions manage stake acceptance workflows, deployment of epoch contracts, continuation or cancellation of stakes, and coordination with cooler contracts.

• Inputs: Various, including sequence numbers, BLS keys, proxy lists, reputation coefficients, and stake details.

• Outputs: None

• Usage: Used in the staking lifecycle, epoch contract deployment, and stake management protocols.

Important Implementation Details

• License and Stake Management: Licenses have detailed metadata including reputation time, privileges, balances, and lock states. Stakes are tracked with sequence numbers and linked to BLS keys and signer indices for cryptographic verification.

• Slashing Mechanism: Multiple functions implement slashing logic, allowing partial or full stake penalties based on misbehavior or protocol rules, with different contexts such as cooler or continuation states.

• Epoch Contract Interaction: Deployment functions allow the wallet to instantiate or continue epoch contracts, suggesting a modular design where epochs are managed by separate contracts.

• Proxy List Usage: Proxy lists are maps from integers to strings and are used in several functions, indicating that nodes can be addressed or communicated with through proxies, enhancing scalability and redundancy.

• Versioning: The contract maintains version info accessible via getVersion for compatibility and upgrade tracking.

Interactions With Other System Components

• BlockKeeperPreEpoch, BlockKeeperEpoch, BlockKeeperEpochCooler, BlockKeeperEpochProxyList: The wallet references code cells for these contracts, indicating it deploys and interacts with them to manage staking epochs, cooldown periods, and proxy lists.

• LicenseRoot Contract: The wallet references a license root address and manages licenses that are likely governed by this root contract.

• BLS Keys and Signer Indexing: The wallet uses BLS public keys and signer indices to manage stake signatures and verifications.

• Proxy Lists: Nodes and wallets interact with proxy lists for network communication and stake management coordination.

Visual Diagram

classDiagram
class AckiNackiBlockKeeperNodeWallet {
-_pubkey: uint256
-_owner_pubkey: uint256
-_root: address
-_activeStakes: map(uint256, tuple)
-_licenses: map(uint256, tuple)
-_epochDuration: uint128
-_balance: uint128
-_whiteListLicense: map(uint256, bool)
+constructor()
+setSigningPubkey()
+addLicense()
+removeLicense()
+setLockToStake()
+setLockStake()
+deleteLockStake()
+updateLockStake()
+slash()
+withdrawToken()
+getDetails()
+getEpochAddress()
+deployPreEpochContract()
+deployBlockKeeperContractContinue()
}
AckiNackiBlockKeeperNodeWallet --> BlockKeeperPreEpochCode
AckiNackiBlockKeeperNodeWallet --> BlockKeeperEpochCode
AckiNackiBlockKeeperNodeWallet --> BlockKeeperEpochCoolerCode
AckiNackiBlockKeeperNodeWallet --> BlockKeeperEpochProxyListCode
AckiNackiBlockKeeperNodeWallet --> LicenseRoot

The diagram depicts the core contract with its fields and key functions, along with its dependencies on other contract codes and license root addresses.

Usage Examples

Adding a License

To add a license to the wallet:

{
  "function": "addLicense",
  "inputs": {
    "license_number": 123456,
    "reputationTime": 1627847284,
    "last_touch": 1627847284,
    "isPrivileged": true
  }
}

This registers a new license with given reputation and timestamp.

Setting a Lock on a License for Staking

To lock a license from staking:

{
  "function": "setLockToStake",
  "inputs": {
    "license_number": 123456,
    "lock": true
  }
}

This prevents the license from participating in staking until unlocked.

Deploying a Pre-Epoch Contract

To deploy a pre-epoch contract with specified parameters:

{
  "function": "deployPreEpochContract",
  "inputs": {
    "epochDuration": 86400,
    "walletTouch": 1,
    "epochCliff": 3600,
    "waitStep": 300,
    "bls_pubkey": "0x...",
    "signerIndex": 0,
    "rep_coef": 1000000,
    "virtualStake": null,
    "ProxyList": {"1": "proxy1.example.com"},
    "reward_sum": 10000,
    "myIp": "192.168.0.1",
    "nodeVersion": "v2.4"
  }
}

This initiates the pre-epoch phase for staking.

Querying Wallet Details

To get a full snapshot of wallet and stake details:

{
  "function": "getDetails",
  "inputs": {}
}

Returns all key wallet data including licenses, active stakes, balances, and epoch parameters.

This contract ABI and structure form an integral part of the node's wallet and staking management system, enabling secure, verifiable, and flexible control over node participation in block keeping and epoch progression.

For related concepts, see Epoch Management, Stake Management, and License Handling.