Zymbit Wallet Python SDK Documentation

Zymbit Wallet Python SDK

Introduction

This documentation contains a set of Python classes which intend to abstract away the technical complexities of using Zymbit's hardware wallet with various blockchains.

The first iteration of the SDK encapsulates all wallet creation, management, and use (sending transactions and interacting with dApps) capabilities for Ethereum and EVM compatible chains.

To see examples of the Python SDK in use, check out this tutorial

Installation

pip install zymbitwalletsdk

High Level Overview

Abstract Classes

  1. Account
    • An abstract class which outlines the basic functionality for an account
  2. Keyring
    • An abstract class which outlines the basic functionality required to be considered a keyring
    • If you want your keyring to work with KeyringManager, your keyring implementation must be a subclass of keyring

Classes

  1. EthAccount
    • A subclass of Account which represents an Ethereum account in the context of Zymbit’s hardware wallet
  2. EllipticCurve
    • An enum which represents the elliptic curves supported on Zymbit’s hardware wallet.
  3. ZymbitEthKeyring
    • A subclass of Keyring which represents a keyring of Ethereum accounts
    • Can be used to create, manage, use (sign transactions and messages), and delete Ethereum accounts
  4. KeyringManager
    • A class used to create, manage, and delete multiple Keyrings (must be a subclass of Keyring)
  5. EthTransaction
    • A class representing an unsigned EIP-1559 Ethereum transaction
  6. SignedEthTransaction
    • A class representing a signed EIP-1559 Ethereum transaction
  7. EthConnect
    • A class with an assortment of methods for interacting with Ethereum using ZymbitEthKeyring instances

Zymbit Wallet SDK Classes

class zymbitwalletsdk.EthAccount

The EthAccount class definition

This class provides access to EthAccount within Python.

EthAccount extends the Account abstract class.

__init__ ( path, address, slot)

Initialize an instance of an EthAccount context

Parameters
  • path (str) — The BIP44 path of the Ethereum Account. Must be a child of m/44'/60'/0'/0
  • address (str) — The address of the Ethereum account. Must be a valid checksum address.
  • slot (int) — The key slot that holds the private key for the account.
Exceptions
  • ValueError If the path, address, or slot is invalid

serialize ()

Serialize the EthAccount object

Returns
dict — containing the path (str), address (hex encoded str), and slot (int) properties

get_public_key ()

Retrieve the public key associated with the Ethereum account

Returns
str — hex encoded public key

class zymbitwalletsdk.EllipticCurve

The EllipticCurve class definition

This class represents an enumeration of elliptic curves available on Zymbit's hardware wallet and extends the Python Enum class.

secp256k1

An enumeration value representing the secp256k1 elliptic curve, used in Ethereum and Bitcoin.

secp256r1

An enumeration value representing the secp256r1 elliptic curve, also known as nist256 or prime256v1.

ed25519

An enumeration value representing the Ed25519 elliptic curve, used in Cardano, Solana, Polkadot, and Monero to name a few

get_curve_type ()

Returns the string representation of the elliptic curve type.

Returns
  • str — The string representation of the elliptic curve type. Can return "secp256k1", "secp256r1", or "ed25519", depending on the enum's value.

class zymbitwalletsdk.ZymbitEthKeyring

The ZymbitEthKeyring class definition

This class provides access to ZymbitEthKeyring within Python.

ZymbitEthKeyring extends the Keyring abstract class.

TYPE

A class level variable set to "ETH"

BASE_PATH

A class level variable set to "m/44'/60'/0'/0"

CURVE

A class level variable set to EllipticCurve.secp256k1

__init__ ( wallet_name = None, master_slot = None)

Initialize an instance of a ZymbitEthKeyring context. Internally calls deserialize(wallet_name, master_slot) and makes some basic checks.

Parameters
  • wallet_name (str) — The name of the wallet associated with the keyring.
  • master_slot (int) — The master slot number of the keyring, optional.
Exceptions
  • ValueError If the "wallet_name" or "master_slot" provided in options is invalid

serialize ()

Serialize the ZymbitEthKeyring instance.

Returns
  • dict — A dictionary containing the serialized keyring's data including wallet_name (str), master_slot (int), type ("ETH"), curve (EllipticCurve.secp256k1), base_path ("m/44'/60'/0'/0"), base_slot (int), and accounts (list of serialized EthAccount instances).

deserialize ( wallet_name = None, master_slot = None)

Deserializes a keyring using either a wallet name or a master slot to restore an instance of a ZymbitEthKeyring context.

Parameters
  • wallet_name (str) — The wallet name associated with the keyring.
  • master_slot (int) — The master slot number of the keyring.
Exceptions
  • ValueError If neither wallet_name nor master_slot are provided
  • ValueError If both wallet_name and master_slot are provided
  • ValueError If the provided wallet_name or master_slot is invalid
Returns
  • bool — True if the keyring is successfully deserialized, otherwise an exception is raised.

add_account (index = 0)

Add an Ethereum account to the keyring at the specified index.

Parameters
  • index (int) — The index at which to add the account
Exceptions
  • ValueError If the index is invalid or the account already exists in the keyring
Returns
  • EthAccount — The added Ethereum account

add_accounts ( n = 1)

Add multiple Ethereum accounts to the keyring.

Parameters
  • n (int) — The number of accounts to add
Exceptions
  • ValueError If the number of accounts to add is invalid
Returns
  • list[EthAccount] — A list of added Ethereum accounts

add_accounts_list ( index_list = [])

Add Ethereum accounts to the keyring at specified indexes from a list.

Parameters
  • index_list (list[int]) — A list of indexes at which to add the accounts
Exceptions
  • ValueError If the list of indexes is invalid or an account with the specified index already exists in the keyring
Returns
  • list[EthAccount] — A list of added Ethereum accounts

get_accounts ()

Get a list of Ethereum accounts in the keyring.

Returns
  • list[EthAccount] — A list of Ethereum accounts in the keyring

remove_account ( address = None, slot = None, path = None)

Remove an Ethereum account from the keyring by its address, slot, or path.

Parameters
  • address (str) — The address of the account to remove
  • slot (int) — The slot of the account to remove
  • path (int) — The path of the account to remove
Exceptions
  • ValueError If valid address, slot, or path is not provided
Returns
  • bool — True if the account is removed, False otherwise

get_public_key ( address = None, slot = None, path = None)

Retrieve the public key of an Ethereum account in the keyring by its address, slot, or path.

Parameters
  • address (str) — The address of the account
  • slot (int) — The slot of the account
  • path (int) — The path of the account
Exceptions
  • ValueError If valid address, slot, or path is not provided
  • ValueError If the account is not found in the keyring
Returns
  • str — The public key of the Ethereum account

sign_transaction ( transaction, address = None, slot = None, path = None)

Sign an Ethereum transaction using an account in the keyring by its address, slot, or path.

Parameters
  • transaction (EthTransaction) — The transaction to be signed
  • address (str) — The address of the account used to sign the transaction
  • slot (int) — The slot of the account used to sign the transaction
  • path (int) — The path of the account used to sign the transaction
Exceptions
  • ValueError If the transaction is not of type EthTransaction
  • ValueError If valid address, slot, or path is not provided
  • ValueError If the account does not exist in the keyring
Returns
  • SignedEthTransaction — The signed Ethereum transaction

sign_message ( message, address = None, slot = None, path = None)

Sign a message using an account in the keyring by its address, slot, or path.

Parameters
  • message (Union[SHA256.SHA256Hash, keccak.Keccak_Hash]) — The message to be signed as a Crypto.Hash object
  • address (str) — The address of the account used to sign the message
  • slot (int) — The slot of the account used to sign the message
  • path (int) — The path of the account used to sign the message
Exceptions
  • TypeError If the message is not an instance of either SHA256.SHA256Hash or keccak.Keccak_Hash Crypto.Hash object
  • ValueError If the message is not a valid 256 bit digest in hex format
  • ValueError If valid address, slot, or path is not provided
  • ValueError If the account does not exist in the keyring
Returns
  • tuple[int, int, int] — A tuple containing the v, r, and s values of the signed message

generate_eth_address ( slot)

Generates an Ethereum address using the provided slot.

Parameters
  • slot (int) — The slot to be used for generating the Ethereum address
Returns
  • str — The generated Ethereum address

account_exists ( index)

Checks if an account with the given index exists in the keyring.

Parameters
  • index (int) — The index to be checked for the existence of an account in the keyring
Returns
  • bool — True if the account exists in the keyring, False otherwise

digest_to_hex ( digest)

Converts a given Crypto.Hash digest to its hexadecimal representation.

Parameters
  • digest (Union[SHA256.SHA256Hash, keccak.Keccak_Hash]) — The digest to be converted to its hexadecimal representation
Exceptions
  • TypeError If the digest is not an instance of either SHA256.SHA256Hash or keccak.Keccak_Hash Crypto.Hash object
Returns
  • str — The hexadecimal representation of the given digest

class zymbitwalletsdk.ZymbitKeyringManager

The ZymbitKeyringManager class definition

This class provides access to ZymbitKeyringManager within Python.

__init__ ( keyrings = [])

Initializes an instance of a KeyringManager with an optional list of Keyring objects.

Parameters
  • keyrings (list[Keyring]) — A list of Keyring objects to be managed by the KeyringManager
Exceptions
  • TypeError If any item in the keyrings list is not an instance of a subclass of the Keyring abstract class.

create_keyring ( keyring_class, wallet_name, master_gen_key = bytearray())

Creates a new keyring of the specified type, associates it with a wallet name, and optionally initializes it with a master generation key.

Parameters
  • keyring_class (Type[Keyring]) — The Keyring subclass representing the type of keyring to create
  • wallet_name (str) — The name of the wallet associated with the keyring
  • master_gen_key (bytearray) — The master generation key used for initializing the keyring, optional (default is an empty bytearray)
Exceptions
  • TypeError If keyring_class is not a subclass of Keyring
  • ValueError If wallet_name is empty or not a string
  • TypeError If master_gen_key is not a bytearray
  • ValueError If the keyring creation fails
Returns
  • tuple[int, str] — A tuple containing the wallet's master key slot and the new wallet's mnemonic phrase (store safely for wallet recovery)

add_keyring ( keyring)

Adds a keyring instance to the list of keyrings

Parameters
  • keyring (Keyring) — The keyring instance to be added
Returns
  • bool — True if the keyring was added successfully

get_keyring ( wallet_name = None, master_slot = None)

Retrieves a keyring instance from the list of keyrings by either the wallet name or the master slot.

Parameters
  • wallet_name (str) — The wallet name associated with the keyring
  • master_slot (int) — The master slot associated with the keyring
Returns
  • Keyring — The keyring instance corresponding to the provided wallet name or master slot

get_keyrings ()

Retrieves the list of keyring instances stored in the KeyringManager.

Returns
  • list[Keyring] — The list of keyring instances stored in the KeyringManager

remove_keyring ( wallet_name = None, master_slot = None, remove_master = False)

Removes a keyring instance from the list of keyrings in the KeyringManager and deletes all related keys from the module by either the wallet name or the master slot. If the 'remove_master' flag is set to True, the method will also remove the master key associated with the keyring.

Parameters
  • wallet_name (str) — The wallet name associated with the keyring
  • master_slot (int) — The master slot associated with the keyring
  • remove_master (bool) — Flag indicating whether to remove the master key associated with the keyring
Returns
  • bool — True if the keyring is successfully removed, False otherwise

class zymbitwalletsdk.EthTransaction

The EthTransaction class definition

This class represents an Ethereum transaction according to the EIP-1559 standard and extends the rlp.Serializable class.

transaction_type

An integer value of 2, representing the EIP-1559 transaction type.

fields

A list of fields that are relevant to a raw EIP-1559 transaction. The fields are:

  • chain_id: The chain ID of the Ethereum network the transaction is meant for.
  • nonce: The nonce value for the sender's account, representing the number of transactions sent from the account.
  • max_priority_fee_per_gas: The maximum fee per gas the sender is willing to pay for the transaction's priority.
  • max_fee_per_gas: The maximum total fee per gas the sender is willing to pay, including both priority and base fees.
  • gas: The amount of gas the sender is willing to allocate to the transaction.
  • to: The recipient's address, or an empty address for contract creation transactions.
  • value: The amount of Wei the sender is transferring to the recipient.
  • data: The transaction data payload, typically used for contract interaction.
  • access_list: A list of addresses and storage keys the transaction will access, used for EIP-2930 access list transactions.

class zymbitwalletsdk.SignedEthTransaction

The SignedEthTransaction class definition

This class represents a signed Ethereum transaction according to the EIP-1559 standard and extends the rlp.Serializable class.

transaction_type

An integer value of 2, representing the EIP-1559 transaction type.

fields

A list of fields that are relevant to a raw EIP-1559 transaction. The fields are:

  • chain_id: The chain ID of the Ethereum network the transaction is meant for.
  • nonce: The nonce value for the sender's account, representing the number of transactions sent from the account.
  • max_priority_fee_per_gas: The maximum fee per gas the sender is willing to pay for the transaction's priority.
  • max_fee_per_gas: The maximum total fee per gas the sender is willing to pay, including both priority and base fees.
  • gas: The amount of gas the sender is willing to allocate to the transaction.
  • to: The recipient's address, or an empty address for contract creation transactions.
  • value: The amount of Wei the sender is transferring to the recipient.
  • data: The transaction data payload, typically used for contract interaction.
  • access_list: A list of addresses and storage keys the transaction will access, used for EIP-2930 access list transactions.
  • y_parity: The y-coordinate parity of the public key, used for signature validation.
  • r: The r value of the ECDSA signature.
  • s: The s value of the ECDSA signature.

class zymbitwalletsdk.EthConnect

The EthConnect class definition

This class contains an assortment of static methods which allow you to use the accounts in your ZymbitEthKeyring instances to sign Ethereum transactions and messages

create_transaction ( chain_id = 1, nonce = 0, max_priority_fee_per_gas = 1, max_fee_per_gas = 10, gas = 21000, to = None, value = 0, data = “0x”, access_list = [])

Create and return an EthTransaction object with the specified parameters.

Parameters
  • chain_id (int) — The chain ID of the Ethereum network. Defaults to 1, the chainId of the main Ethereum network
  • nonce (int) — The transaction nonce
  • max_priority_fee_per_gas (int) — The maximum priority fee per gas unit
  • max_fee_per_gas (int) — The maximum fee per gas unit
  • gas (int) — The amount of gas units for the transaction
  • to (str) — The recipient Ethereum address
  • value (int) — The amount of Wei to be sent with the transaction
  • data (str) — The transaction data in hexadecimal format
  • access_list (list) — The access list for the transaction
Exceptions
  • ValueError If one or more parameter types are invalid
  • ValueError If the 'to' field is not a valid checksum address
Returns
  • EthTransaction — An EthTransaction object with the specified parameters

create_deploy_contract_transaction ( chain_id = 1, nonce = 0, max_priority_fee_per_gas = 1, max_fee_per_gas = 10, gas = 21000, value = 0, access_list = [], contract_bytecode_path = None, contract_abi_path = None, constructor_args = [])

Create an EthTransaction object for deploying a smart contract with the provided parameters, bytecode, and ABI.

Parameters
  • chain_id (int) — The chain ID of the Ethereum network. Defaults to 1, the chainId of the main Ethereum network
  • nonce (int) — The transaction nonce
  • max_priority_fee_per_gas (int) — The maximum priority fee per gas
  • max_fee_per_gas (int) — The maximum fee per gas
  • gas (int) — The gas limit for the transaction
  • value (int) — The amount of Wei to be sent with the transaction
  • access_list (list) — An access list for the transaction
  • contract_bytecode_path (str) — The path to the file containing the contract bytecode. Should be a text file with the bytecode hex encoded.
  • contract_abi_path (str) — The path to the file containing the contract ABI (Application Binary Interface). Should be a JSON file.
  • constructor_args (list) — A list of arguments to pass to the contract constructor. Ordered from first parameter to last.
Exceptions
  • ValueError If one or more parameter types are invalid
  • ValueError If the bytecode or ABI file paths do not exist
Returns
  • EthTransaction — An EthTransaction object for deploying the smart contract with the provided parameters, bytecode, and ABI

create_execute_contract_transaction ( chain_id = 1, nonce = 0, max_priority_fee_per_gas = 1, max_fee_per_gas = 10, gas = 210000, contract_address = None, value = 0, access_list = [], contract_abi_path = None, function_name = None, args = [])

Create a transaction to execute a function of a smart contract on an Ethereum network.

Parameters
  • chain_id (int) — The chain ID of the Ethereum network. Defaults to 1, the chainId of the main Ethereum network
  • nonce (int) — The transaction nonce
  • max_priority_fee_per_gas (int) — The maximum priority fee per gas
  • max_fee_per_gas (int) — The maximum fee per gas
  • gas (int) — The gas limit for the transaction
  • contract_address (str) — The address of the smart contract
  • value (int) — The amount of Wei to be sent with the transaction
  • access_list (list) — An access list for the transaction
  • contract_abi_path (str) — The path to the file containing the contract ABI (Application Binary Interface). Should be a JSON file.
  • function_name (str) — The name of the smart contract function to be executed
  • args (list) — The arguments for the function to be executed. From first parameter to last.
Exceptions
  • ValueError If one or more parameter types are invalid, or if the provided contract address is not a valid checksum address, or if the ABI file path does not exist
Returns
  • EthTransaction — An EthTransaction object representing the contract execution transaction

sign_transaction ( transaction, keyring, address = None, slot = None, path = None)

Signs an Ethereum transaction using a Zymbit keyring.

Parameters
  • transaction (EthTransaction) — The transaction to be signed
  • keyring (ZymbitEthKeyring) — The Zymbit keyring to use for signing
  • address (str) — The address of the account in the keyring used to sign the transaction
  • slot (int) — The slot of the account in the keyring used to sign the transaction
  • path (int) — The path of the account in the keyring used to sign the transaction
Exceptions
  • ValueError If the transaction is not of type EthTransaction
  • ValueError If the keyring is not of type ZymbitEthKeyring
  • ValueError If none of address, slot, or path are provided
Returns
  • SignedEthTransaction — A SignedEthTransaction object ready to be serialized and broadcasted to an Ethereum network

rlp_serialize_transaction ( transaction)

Serialize an EthTransaction or SignedEthTransaction object using RLP encoding.

Parameters
  • transaction (Union[EthTransaction, SignedEthTransaction]) — The transaction to be serialized
Exceptions
  • ValueError If the transaction is neither of type EthTransaction nor SignedEthTransaction
Returns
  • bytes — The serialized transaction in bytes format

rlp_deserialize_transaction ( encoded_transaction)

Deserialize an RLP-encoded transaction to either an EthTransaction or a SignedEthTransaction object.

Parameters
  • encoded_transaction (bytes) — The encoded transaction as bytes
Exceptions
  • ValueError If the encoded transaction is not a bytes object
  • ValueError If the encoded transaction is not an EIP-1559 transaction (type 2)
  • ValueError If the encoded transaction cannot be deserialized to an EthTransaction or a SignedEthTransaction object
Returns
  • Union[EthTransaction, SignedEthTransaction] — An EthTransaction or a SignedEthTransaction object representing the deserialized transaction

create_message ( message)

Create an Ethereum message to be signed. Prepends the message that is passed in with "Ethereum Signed Message:\n"

Parameters
  • message (str) — The message to be signed as a string
Exceptions
  • TypeError If the message is not a string
Returns
  • tuple[str, bytes] — A tuple containing the Ethereum message (str) and its corresponding bytes representation (bytes)

sign_message ( message, keyring, address = None, slot = None, path = None)

Sign a message using an account in the keyring by its address, slot, or path.

Parameters
  • message (Union[SHA256.SHA256Hash, keccak.Keccak_Hash]) — The message to be signed as a Crypto.Hash object
  • keyring (ZymbitEthKeyring) — The keyring object used to sign the message
  • address (str) — The address of the account used to sign the message
  • slot (int) — The slot of the account used to sign the message
  • path (int) — The path of the account used to sign the message
Exceptions
  • TypeError If the message is not an instance of either SHA256.SHA256Hash or keccak.Keccak_Hash Crypto.Hash object
  • ValueError If the message is not a valid 256 bit digest in hex format
  • ValueError If the keyring is not an instance of ZymbitEthKeyring
  • ValueError If valid address, slot, or path is not provided
  • ValueError If the account does not exist in the keyring
Returns
  • str — The concatenated hex encoded ECDSA signature

keccak256 ( str_data = None, bytes_data = None)

Generate a Keccak256 hash digest from the given string or bytes data.

Parameters
  • str_data (str) — String data to generate the Keccak256 hash digest from.
  • bytes_data (bytes) — Bytes data to generate the Keccak256 hash digest from.
Exceptions
  • ValueError If both str_data and bytes_data are provided.
  • ValueError If neither str_data nor bytes_data are provided.
Returns
  • keccak.Keccak_Hash — A Keccak256 hash digest as a Crypto.Hash.keccak.Keccak_Hash object.

sha256 ( str_data = None, bytes_data = None)

Generate a SHA256 hash digest from the given string or bytes data.

Parameters
  • str_data (str) — String data to generate the SHA256 hash digest from.
  • bytes_data (bytes) — Bytes data to generate the SHA256 hash digest from.
Exceptions
  • ValueError If both str_data and bytes_data are provided.
  • ValueError If neither str_data nor bytes_data are provided.
Returns
  • SHA256.SHA256Hash — A SHA256 hash digest as a Crypto.Hash.SHA256.SHA256Hash object.

eth_to_wei ( ether_amount= 0)

Converts a given amount in Ether to its equivalent value in Wei.

Parameters
  • ether_amount (float) — The amount of Ether to convert to Wei
Returns
  • int — The equivalent value in Wei as an integer.

Additional Resources

If you are a developer interested in creating your own custom implementations of Accounts and/or Keyrings to work with ZymbitKeyringManager, we encourage you to explore our Github repository. By extending the Account and Keyring Abstract Base Classes (ABCs), you can implement the required methods and any additional functionality as needed. The elliptic curves we support (secp256k1, secp256r1, and ed25519) are used by many major blockchains, including Bitcoin, Ethereum, Cardano, Solana, and Polkadot. Developing your own keyrings can be incredibly beneficial for a wide range of applications, such as key management or on-chain interactions like sending transactions or interacting with smart contracts.