aea.crypto.base

Abstract module wrapping the public and private key cryptography and ledger api.

Crypto

class Crypto(Generic[EntityClass],  ABC)

Base class for a crypto object.

__init__

 | __init__(private_key_path: Optional[str] = None, **kwargs)

Initialize the crypto object.

The actual behaivour of this constructor is determined by the abstract methods 'generate_private_key()' and 'load_private_key_from_path(). Either way, the entity object will be accessible as a property.

Arguments:

  • private_key_path: the path to the private key. If None, the key will be generated by 'generate_private_key()'. If not None, the path will be processed by 'load_private_key_from_path()'.
  • kwargs: keyword arguments.

generate_private_key

 | @classmethod
 | @abstractmethod
 | generate_private_key(cls) -> EntityClass

Generate a private key.

Returns:

the entity object. Implementation dependent.

load_private_key_from_path

 | @classmethod
 | @abstractmethod
 | load_private_key_from_path(cls, file_name: str) -> EntityClass

Load a private key in hex format from a file.

Arguments:

  • file_name: the path to the hex file.

Returns:

the entity object.

entity

 | @property
 | entity() -> EntityClass

Return an entity object.

Returns:

an entity object

public_key

 | @property
 | @abstractmethod
 | public_key() -> str

Return a public key.

Returns:

a public key string

address

 | @property
 | @abstractmethod
 | address() -> str

Return the address.

Returns:

an address string

get_address_from_public_key

 | @classmethod
 | @abstractmethod
 | get_address_from_public_key(cls, public_key: str) -> str

Get the address from the public key.

Arguments:

  • public_key: the public key

Returns:

str

sign_message

 | @abstractmethod
 | sign_message(message: bytes, is_deprecated_mode: bool = False) -> str

Sign a message in bytes string form.

Arguments:

  • message: the message to be signed
  • is_deprecated_mode: if the deprecated signing is used

Returns:

signature of the message in string form

sign_transaction

 | @abstractmethod
 | sign_transaction(transaction: Any) -> Any

Sign a transaction in bytes string form.

Arguments:

  • transaction: the transaction to be signed

Returns:

signed transaction

recover_message

 | @abstractmethod
 | recover_message(message: bytes, signature: str, is_deprecated_mode: bool = False) -> Tuple[Address, ...]

Recover the addresses from the hash.

Arguments:

  • message: the message we expect
  • signature: the transaction signature
  • is_deprecated_mode: if the deprecated signing was used

Returns:

the recovered addresses

dump

 | @abstractmethod
 | dump(fp: BinaryIO) -> None

Serialize crypto object as binary stream to fp (a .write()-supporting file-like object).

Arguments:

  • fp: the output file pointer. Must be set in binary mode (mode='wb')

Returns:

None

LedgerApi

class LedgerApi(ABC)

Interface for ledger APIs.

api

 | @property
 | @abstractmethod
 | api() -> Any

Get the underlying API object.

This can be used for low-level operations with the concrete ledger APIs. If there is no such object, return None.

get_balance

 | @abstractmethod
 | get_balance(address: Address) -> Optional[int]

Get the balance of a given account.

This usually takes the form of a web request to be waited synchronously.

Arguments:

  • address: the address.

Returns:

the balance.

transfer

 | @abstractmethod
 | transfer(crypto: Crypto, destination_address: Address, amount: int, tx_fee: int, tx_nonce: str, **kwargs) -> Optional[str]

Submit a transaction to the ledger.

If the mandatory arguments are not enough for specifying a transaction in the concrete ledger API, use keyword arguments for the additional parameters.

Arguments:

  • crypto: the crypto object associated to the payer.
  • destination_address: the destination address of the payee.
  • amount: the amount of wealth to be transferred.
  • tx_fee: the transaction fee.
  • tx_nonce: verifies the authenticity of the tx

Returns:

tx digest if successful, otherwise None

send_signed_transaction

 | @abstractmethod
 | send_signed_transaction(tx_signed: Any) -> Optional[str]

Send a signed transaction and wait for confirmation.

Use keyword arguments for the specifying the signed transaction payload.

Arguments:

  • tx_signed: the signed transaction

is_transaction_settled

 | @abstractmethod
 | is_transaction_settled(tx_digest: str) -> bool

Check whether a transaction is settled or not.

Arguments:

  • tx_digest: the digest associated to the transaction.

Returns:

True if the transaction has been settled, False o/w.

is_transaction_valid

 | @abstractmethod
 | is_transaction_valid(tx_digest: str, seller: Address, client: Address, tx_nonce: str, amount: int) -> bool

Check whether a transaction is valid or not (non-blocking).

Arguments:

  • seller: the address of the seller.
  • client: the address of the client.
  • tx_nonce: the transaction nonce.
  • amount: the amount we expect to get from the transaction.
  • tx_digest: the transaction digest.

Returns:

True if the transaction referenced by the tx_digest matches the terms.

get_transaction_receipt

 | @abstractmethod
 | get_transaction_receipt(tx_digest: str) -> Optional[Any]

Get the transaction receipt for a transaction digest (non-blocking).

Arguments:

  • tx_digest: the digest associated to the transaction.

Returns:

the tx receipt, if present

generate_tx_nonce

 | @abstractmethod
 | generate_tx_nonce(seller: Address, client: Address) -> str

Generate a random str message.

Arguments:

  • seller: the address of the seller.
  • client: the address of the client.

Returns:

return the hash in hex.

FaucetApi

class FaucetApi(ABC)

Interface for testnet faucet APIs.

get_wealth

 | @abstractmethod
 | get_wealth(address: Address) -> None

Get wealth from the faucet for the provided address.

Arguments:

  • address: the address.

Returns:

None