lighter.pubkey

Documentation for eth_defi.lighter.pubkey Python module.

Lighter API-key registration (changePubKey) for a Safe-controlled account.

Creating a Lighter API key is two steps:

  1. Generate the API keypair off-chain (the lighter-python SDK SignerClient; no L1 private key needed). Use indices 4-254 for automated keys; Lighter’s dedicated API-key documentation reserves indices 0-3 for the web/mobile UI.

  2. Register its public key with the Lighter account on L1 via ZkLighter.changePubKey(accountIndex, apiKeyIndex, pubKey). For a Gnosis Safe / Lagoon vault this is done as a Safe transaction — Lighter explicitly recommends the on-chain ChangePubKey “if you’re running a multi-sig” (the SDK’s EOA sign_change_api_key path needs a raw private key, which a Safe does not have).

This module covers step 2 for a Safe: validating the pubkey, encoding the changePubKey call, and building / executing the Safe transaction. To collect multisig signatures, print the transaction with scripts/lighter/lagoon-lighter-change-pubkey.py and use the Safe{Wallet} Transaction Builder.

Note

changePubKey is intentionally not part of the asset-manager guard whitelist (eth_defi.lighter LighterLib). It is a privileged setup action performed by the Safe owners (governance), so it goes directly through the Safe, not the TradingStrategyModule’s restricted performCall path. The asset-manager hot wallet cannot rotate trading keys.

Authoritative docs:

Functions

build_change_pubkey_safe_tx(web3, safe, ...)

Build an (unsigned) Safe transaction calling ZkLighter.changePubKey.

encode_change_pubkey(web3, account_index, ...)

Encode a ZkLighter.changePubKey(accountIndex, apiKeyIndex, pubKey) call.

execute_change_pubkey(web3, safe, ...[, ...])

Build, sign and execute the changePubKey Safe transaction immediately.

validate_lighter_pubkey(pubkey)

Validate a Lighter API-key public key client-side.
build_change_pubkey_safe_tx(web3, safe, account_index, api_key_index, pubkey, zk_lighter='0x3B4D794a66304F130a4Db8F2551B0070dfCf5ca7')

Build an (unsigned) Safe transaction calling ZkLighter.changePubKey.

The Safe is the Lighter account’s L1 owner. Sign + execute it with the Safe owners, or post it to the Safe Transaction Service via propose_change_pubkey().

Returns

An unsigned SafeTx.

Parameters
Return type

safe_eth.safe.safe_tx.SafeTx

encode_change_pubkey(web3, account_index, api_key_index, pubkey, zk_lighter='0x3B4D794a66304F130a4Db8F2551B0070dfCf5ca7')

Encode a ZkLighter.changePubKey(accountIndex, apiKeyIndex, pubKey) call.

Validates api_key_index and pubkey before encoding.

Parameters

  • web3 (web3.main.Web3) – Web3 connection (for the ABI / encoding).

  • account_index (int) – The Lighter account index whose key is being set.

  • api_key_index (int) – The API-key slot (4-254 for automated user keys).

  • pubkey (bytes) – The API-key public key (see validate_lighter_pubkey()).

  • zk_lighter (Union[eth_typing.evm.HexAddress, str]) – The ZkLighter L1 contract address.

Returns

(zk_lighter_address, calldata).

Return type

tuple[eth_typing.evm.HexAddress, hexbytes.main.HexBytes]

execute_change_pubkey(web3, safe, owner_private_key, account_index, api_key_index, pubkey, zk_lighter='0x3B4D794a66304F130a4Db8F2551B0070dfCf5ca7', hot_wallet=None)

Build, sign and execute the changePubKey Safe transaction immediately.

For a single-owner Safe (or local simulation). For a real multisig, build the transaction with build_change_pubkey_safe_tx() (or print it with scripts/lighter/lagoon-lighter-change-pubkey.py) and collect the owner signatures in the Safe UI.

Parameters

  • owner_private_key (str) – The executing owner’s private key (0x-prefixed).

  • hot_wallet (Optional[eth_defi.hotwallet.HotWallet]) – Optional owner wallet for nonce allocation. Use this in scripts that already submit transactions through HotWallet to avoid stale RPC nonce reads.

  • web3 (web3.main.Web3) –

  • safe (safe_eth.safe.safe.Safe) –

  • account_index (int) –

  • api_key_index (int) –

  • pubkey (bytes) –

  • zk_lighter (Union[eth_typing.evm.HexAddress, str]) –

Returns

The executed transaction hash.

Return type

hexbytes.main.HexBytes

validate_lighter_pubkey(pubkey)

Validate a Lighter API-key public key client-side.

Mirrors the on-chain checks in ZkLighter.changePubKey so callers fail fast before submitting a transaction: the pubkey must be exactly PUB_KEY_BYTES_SIZE bytes, each 8-byte little-endian limb must be strictly below GOLDILOCKS_MODULUS, and it must not be all-zero.

Parameters

pubkey (bytes) – The API-key public key, as produced by the Lighter SDK.

Raises

ValueError – If the pubkey is malformed.

Return type

None