​

Overview

​

Tutorial

​

Prerequisites

1. MEV Plus with K2 Native Delegation module plugged in.
2. Ethereum EOA Wallet: You should have an Ethereum wallet with sufficient funds to pay for gas fees. This wallet is used to pay for gas fees when interacting with the Proposer Registry and K2 contracts. Keep it safe - it represents proposers on the Ethereum execution layer.
3. MEV Plus connected to node by Builder API: The module requires the node to be connected to MEV Plus through the Builder API. This is required for the module to receive the presigned messages from the node and register validators on-chain.

​

Supported Networks

• Mainnet
• Goerli
• Holesky

https://github.com/pon-network/contract-deployments

​

Web3 Signer support

​

Configuration

​

Required Flags

• k2.eth1-private-key: The private key of the proposer(s) representative wallet. This key is essential for signing registration messages and interacting with all the smart contracts. NOTE: This key is the only wallet key that would be granted permission to manage validators on-chain and act as their representative. Keep this wallet safe. This module also supports the use of multiple representative wallets, in which case provide a comma separated list of private keys. [eg. k2.eth1-private-key 1234567890abcdef1234567890abcdef12345f,1234567890abcdef1234567890abcdef12345f ]. The keys should be in order of priority, with the first key being the primary key. The module will use the first key to run contract calls and reward claim transactions. The additional keys are used to natively delegate or exit validators of varied payout recipients per key.
• k2.beacon-node-url: The URL of the beacon node. This URL is required for syncing with the Ethereum Consensus Layer.
• k2.execution-node-url: The URL of the execution node to connect to for on-chain execution.

​

Optional Flags

• k2.registration-only: This flag is used to register validators on-chain in the Proposer Registry without natively delegating them to the K2 contract pool.
• k2.web3-signer-url: The module supports the use of a Web3Signer to sign custom registration messages with a modified payout recipient address from the one configured on the node. This flag is optional and can be used to configure the Web3Signer URL. The validator keys to which their registration messages wish to be signed should be configured on the Web3Signer.
• k2.payout-recipient: The address of an alternative globally configured payout recipient. This address will be used for all validators if specified. If not specified, the payout recipient address configured on the node for each validator key will be used. To use this flag, the k2.web3-signer-url flag must also be specified in order to sign the registration messages with the alternative payout recipient address.
• k2.max-gas-price: The maximum gas price (denominated in WEI) to be used for on-chain transactions. This flag is optional and defaults to using the current netowrk gas price for execution. If set, any registration in which the gas price exceeds the maximum gas price, the registration/delegation will be skipped for that epoch.
• k2.listen-address: The address on which the module will listen for incoming requests. This flag is optional and defaults to localhost:10000 if not specified. The API specifications can be found here.
• k2.claim-threshold: The threshold for claiming rewards from the K2 contract. This flag is optional and defaults to 0.0 KETH if not specified (claims any available rewards). If the rewards for a validator exceed the threshold, the rewards will be claimed from the K2 contract upon any request to the API.
• k2.k2-lending-contract-address: The address of the K2 lending contract you wish to provide to override the default contract address for a supported network, or to provide a contract address for an unsupported network.
• k2.k2-node-operator-contract-address: The address of the K2 node operator contract you wish to provide to override the default contract address for a supported network, or to provide a contract address for an unsupported network.
• k2.proposer-registry-contract-address: The address of the proposer registry contract you wish to provide to override the default contract address for a supported network, or to provide a contract address for an unsupported network. Especially if in registration-only mode. If not in registration-only mode, the module will obtain the contract address from the K2 contracts and does not need this flag.
• k2.signature-swapper-url: The URL of the signature swapper service. This flag is optional and defaults to the network-specific signature swapper URL if not specified (overridden), or can be used to provide a custom signature swapper URL for unsupported networks. The signature swapper is used to generate and manage ECDSA signatures as proof of ownership of the BLS keys.
• k2.balance-verifier-url: The URL of the balance verifier service. This flag is optional and defaults to the network-specific balance verifier URL if not specified (overridden), or can be used to provide a custom balance verifier URL for unsupported networks. The balance verifier is used to verify the effective balance of the proposer wallet for balance report to the contracts for reward claiming or exiting the protocol.
• k2.strict-inclusion-list: This flag is used to specify a list of validator public keys to solely process. The flag accepts a filepath to a JSON file containing the list of validator public keys/fee recipients to strictly process. The file is continuously monitored by the software and would pick up any changes immediately, allowing you to manage your registrations without restarting MEV Plus. The JSON file should be in the following format:

[
    {
        "publicKey": string,
        "allowProposerRegistration": bool,
        "allowNativeDelegation": bool
    },
    ...,
    {
        "feeRecipientAddress": string,
        "allowProposerRegistration": bool,
        "allowNativeDelegation": bool
    }
]

[
  {
    "publicKey": "0x93e2de67f75817c101c637b16efc4ba1de8374ed563a4cdcf2d6cc5ea6c1de4ab5abcefdb3bd2baa96a1a2ddb1847d08",
    "allowProposerRegistration": false,
    "allowNativeDelegation": true
  },
  {
    "feeRecipientAddress": "0x22A3864baaE65a9e8E5C163F80F850ADFe40Ed90",
    "allowProposerRegistration": true,
    "allowNativeDelegation": true
  }
]

• k2.exclusion-list: This flag is used to specify a list of validator public keys to exclude from either on-chain registration or native delegation. The flag accepts a filepath to a JSON file containing the list of validator public keys/fee recipients to exclude. The file is continuously monitored by the software and would pick up any changes immediately, allowing you to manage your registrations without restarting MEV Plus. The JSON file should be in the following format:

[
    {
        "publicKey": string,
        "allowProposerRegistration": bool,
        "allowNativeDelegation": bool
    },
    ...,
    {
        "feeRecipientAddress": string,
        "allowProposerRegistration": bool,
        "allowNativeDelegation": bool
    }
]

[
  {
    "publicKey": "0x93e2de67f75817c101c637b16efc4ba1de8374ed563a4cdcf2d6cc5ea6c1de4ab5abcefdb3bd2baa96a1a2ddb1847d08",
    "allowProposerRegistration": false,
    "allowNativeDelegation": true
  },
  {
    "feeRecipientAddress": "0x22A3864baaE65a9e8E5C163F80F850ADFe40Ed90",
    "allowProposerRegistration": true,
    "allowNativeDelegation": true
  }
]

• k2.representative-mapping: This flag is used to optionally specify a mapping of representative wallets that should be used to process validators to specific validators by BLS Key or specific payout/feeRecipient addresses. The flag accepts a filepath to a JSON file containing the mapping of representative addresses designated to specific validators or that would handle validators that pay to different k2 fee/payout recipients (any ECDSA address). The file is continuously monitored by the software and would pick up any changes immediately, allowing you to manage your registrations without restarting MEV Plus. The JSON file should be in the following format:

[
    {
        "representativeAddress": string,
        "feeRecipientAddress": string
    },
    ...,
    {
        "representativeAddress": string,
        "publicKey": string
    }
]

[
  {
    "representativeAddress": "0x22A3864baaE65a9e8E5C163F80F850ADFe40Ed90",
    "feeRecipientAddress": "0x22A3864baaE65a9e8E5C163F80F850ADFe40Ed90"
  },
  {
    "representativeAddress": "0x22A3864baaE65a9e8E5C163F80F850ADFe40Ed90",
    "publicKey": "0x93e2de67f75817c101c637b16efc4ba1de8374ed563a4cdcf2d6cc5ea6c1de4ab5abcefdb3bd2baa96a1a2ddb1847d08"
  }
]

• k2.logger-level: The log level for the K2 Native Delegation module. This flag is optional and defaults to info if not specified. The available log levels are debug, info, warn, error, and fatal.

​

How It Works

​

Benefits for Node Runners

​

Installation

​

Usage

# Enable K2 Native Delegation Module
mevPlus ............ -k2.eth1-private 1234567890abcdef1234567890abcdef12345f -k2.beacon-node-url http://localhost:5052 -k2.execution-node-url http://localhost:8545

​

API

​

POST /eth/v1/exit

{
  "validator": string
}

​

POST /eth/v1/claim

{
  "nodeOperators": [
    Representative Address {string},
    Representative Address {string},
    ...
  ]
}

​

GET /eth/v1/delegated-validators

GET /eth/v1/delegated-validators?representativeAddresses=<representativeAddress>&includeBalance=true

GET /eth/v1/delegated-validators?representativeAddresses=<representativeAddress1>,<representativeAddress2>,<representativeAddress3>&includeBalance=true

[
  {
    "representativeAddress": string,
    "claimableRewards": uint64, *only if includeBalance is true
    "delegatedValidators": [
      {
        "validatorPubKey": string,
        "representativeAddress": string,
        "effectiveBalance": uint64, (in wei) *only if includeBalance is true
      },
      ...
    ]
  },
  ...
]

​

POST /eth/v1/register

[
  {
    "message": {
      "pubkey": string,
      "fee_recipient": string,
      "gas_limit": uint64,
      "timestamp": uint64,
    },
      "signature": string
    }
]