agora.model package

Submodules

agora.model.account module

class agora.model.account.AccountInfo(account_id, balance=None, owner=None, close_authority=None)

Bases: object

The information of a Kin account.

Parameters:

• account_id (PublicKey) – The ID of the account.

• balance (Optional[int]) – The balance of the account, in quarks. Included only if account info was requested.

• owner (Optional[PublicKey]) – The owner of the account, included only if it is a token account.

• close_authority (Optional[PublicKey]) – The close authority of the account, included only if it is a token account.

classmethod from_proto(proto)

Return type:

AccountInfo

agora.model.creation module

class agora.model.creation.Creation(owner, address)

Bases: object

The Creation object, which represents a token account creation.

Parameters:

• owner (PublicKey) – The PublicKey of the account that owns this token account.

• address (PublicKey) – The PublicKey representing the address of the token account.

agora.model.earn module

class agora.model.earn.Earn(destination, quarks, invoice=None)

Bases: object

The Earn object, which represents an earn payment that will get submitted.

Parameters:

• destination (PublicKey) – The PublicKey of the account the earn will be sent to.

• quarks (int) – The amount being sent.

• invoice (Optional[Invoice]) – (optional) An Invoice object to associate with this earn.

class agora.model.earn.EarnBatch(sender, earns, memo=None, subsidizer=None, dedupe_id=None)

Bases: object

The EarnBatch object, which represents a batch of Earn payments coming from a single sender.

Parameters:

• sender (PrivateKey) – The PrivateKey of the sender

• earns (List[Earn]) – A list of Earn objects.

• memo (Optional[str]) – (optional) The memo to include in the transaction. If set, none of the invoices included in earns will be applied.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used as the payer of the transaction.

• dedupe_id (Optional[bytes]) – (optional) The dedupe ID to use for the transaction submission. If included, Agora will verify that no transaction was previously submitted the same dedupe ID before submitting the transaction to the blockchain.

agora.model.invoice module

class agora.model.invoice.Invoice(items)

Bases: object

The :class: Invoice <Invoice> object, which represents a transaction invoice for a single payment.

Parameters:

items (List[LineItem]) – A list of LineItem objects.

classmethod from_proto(proto)

Return type:

Invoice

to_proto()

Return type:

Invoice

class agora.model.invoice.InvoiceList(invoices)

Bases: object

The InvoiceList object, which is a list of invoices associated with a transaction.

Parameters:

invoices (List[Invoice]) – a list of Invoice objects.

classmethod from_proto(proto)

Return type:

InvoiceList

get_sha_224_hash()

Returns the SHA-224 of the marshaled protobuf form of this invoice.

Return type:

bytes

Returns:

the SHA-224 hash.

to_proto()

Return type:

InvoiceList

class agora.model.invoice.LineItem(title, amount, description='', sku=None)

Bases: object

The LineItem object, which represents a line item in an invoice.

Parameters:

• title (str) – The title of the line item.

• amount (int) – The amount, in quarks.

• description (Optional[str]) – (optional) A description of the line item.

• sku (Optional[bytes]) – (optional) A SKU associated with the line item.

classmethod from_proto(proto)

Return type:

LineItem

to_proto()

Return type:

LineItem

agora.model.memo module

class agora.model.memo.AgoraMemo(val)

Bases: object

Implements the Agora memo specification as defined in github.com/kinecosystem/agora-api.

Parameters:

val (bytearray) – the raw memo bytearray.

app_index()

Returns the app index of the memo.

Return type:

int

Returns:

the int app index

foreign_key()

Returns the foreign key of the memo.

Return type:

bytes

Returns:

the foreign key

classmethod from_b64_string(s, strict=False)

Return type:

AgoraMemo

classmethod from_base_memo(m, strict=False)

Instantiates and returns an AgoraMemo object from a Memo, provided it is a valid (or strictly valid) Agora memo.

Parameters:

• m (Memo) – A Memo

• strict (Optional[bool]) – (optional). Dictates whether to strictly check validity of the memo or not. Defaults to False.

Return type:

AgoraMemo

Returns:

An AgoraMemo object.

classmethod from_xdr(xdr, strict=False)

Return type:

AgoraMemo

is_valid()

Returns whether or not the memo is valid.

It should be noted that there are no guarantees if the memo is valid, only if the memo is invalid. That is, this function may return false positives.

Stricter validation can be done via AgoraMemo.is_valid_strict(). However, AgoraMemo.is_valid_strict() is not as forward compatible.

Return type:

bool

Returns:

A bool indicating whether the memo is valid

is_valid_strict()

Returns whether or not the memo is valid checking against this implementation’s supported version.

It should be noted that there are no guarantees if the memo is valid, only if the memo is invalid. That is, this function may return false positives.

Return type:

bool

Returns:

A bool indicating whether the memo is strictly valid

classmethod new(version, tx_type, app_index, foreign_key)

Returns an Agora memo containing the provided properties.

Parameters:

• version (int) – The memo encoding version

• tx_type (TransactionType) – The TransactionType of the transaction

• app_index (int) – The index of the app the transaction relates to

• foreign_key (bytes) – An identifier in an auxiliary service that contains additional data about what the transaction was for

Return type:

AgoraMemo

Returns:

an AgoraMemo object

tx_type()

Returns the TransactionType of this memo.

Return type:

TransactionType

Returns:

TransactionType

tx_type_raw()

Returns the transaction type of the memo, even if is unsupported by this implementation. It should only be used as a fallback if the raw value is needed when agora.memo.AgoraMemo.transaction_type.py() yields TransactionType.UNKNOWN.

Return type:

int

Returns:

the int value of the memo transaction type

version()

Returns the memo encoding version of this memo.

Return type:

int

Returns:

the int memo encoding version

agora.model.payment module

class agora.model.payment.Payment(sender, destination, tx_type, quarks, invoice=None, memo=None, subsidizer=None, dedupe_id=None)

Bases: object

The Payment object, which represents a payment that will get submitted.

Parameters:

• sender (PrivateKey) – The PrivateKey of the account from which funds will be sent.

• destination (PublicKey) – The PublicKey of the account to which funds will be sent.

• tx_type (TransactionType) – The TransactionType of this payment.

• quarks (int) – The amount being sent.

• invoice (Optional[Invoice]) – (optional) An Invoice to associate with this payment. Only one of invoice or memo should be set.

• memo (Optional[str]) – (optional) The text memo to include with the transaction. Only one of invoice or memo should be set.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used as the payer of the transaction.

• dedupe_id (Optional[bytes]) – (optional) The dedupe ID to use for the transaction submission. If included, Agora will verify that no transaction was previously submitted the same dedupe ID before submitting the transaction to the blockchain.

class agora.model.payment.ReadOnlyPayment(sender, destination, tx_type, quarks, invoice=None, memo=None)

Bases: object

The ReadOnlyPayment object, which represents a payment that was retrieved from history.

Parameters:

• sender (PublicKey) – The PublicKey of the sending account.

• destination (PublicKey) – The PublicKey of the destination account.

• tx_type (TransactionType) – The type of this payment.

• quarks (int) – The amount of the payment.

• invoice (Optional[Invoice]) – (optional) The Invoice associated with this payment. Only one of invoice or memo will be set.

• memo (Optional[str]) – (optional) The text memo associated with this transaction. Only one of invoice or memo will be set.

agora.model.result module

class agora.model.result.EarnBatchResult(tx_id, tx_error=None, earn_errors=None)

Bases: object

The BatchEarnResult object, which contains the results of a submitted earn batch.

Parameters:

• tx_id (bytes) – The id of the transaction that was submitted for the earn batch.

• tx_error (Optional[Error]) – (optional) An Error indicating why an earn batch failed. If tx_error is defined, the transaction failed.

• earn_errors (Optional[List[EarnError]]) – (optional) A List of any available earn-specific error information. May or may not be set if tx_error is set.

class agora.model.result.EarnError(earn_index, error)

Bases: object

The EarnError object contains earn-specific details about why a submitted earn batch failed

Parameters:

• earn_index (int) – The index of the earn the error pertains to

• error (Error) – The error

agora.model.transaction module

class agora.model.transaction.TransactionData(tx_id, transaction_state, payments=None, error=None)

Bases: object

The TransactionData object, which contains information about the payments in a transaction.

Parameters:

• tx_id (bytes) – Either a 32-byte transaction hash, or a 64-byte transaction signature.

• payments (Optional[List[ReadOnlyPayment]]) – (optional) A list of ReadOnlyPayment objects.

• error (Optional[TransactionErrors]) – (optional)) A TransactionError object that contains extra details about why a transaction failed. If present, it indicates that the transaction failed.

classmethod from_proto(item, state)

Return type:

TransactionData

class agora.model.transaction.TransactionState(value)

Bases: enum.IntEnum

An enumeration.

FAILED = 2

PENDING = 3

SUCCESS = 1

UNKNOWN = 0

static from_proto(state)

static from_proto_v4(state)

agora.model.transaction_type module

class agora.model.transaction_type.TransactionType(value)

Bases: enum.IntEnum

The type of a transaction.

EARN = 1

NONE = 0

P2P = 3

SPEND = 2

UNKNOWN = -1

agora.model.utils module

agora.model.utils.app_id_from_text_memo(text_memo)

Return type:

str

agora.model.utils.is_valid_app_id(app_id)

Return type:

bool

agora.model.utils.parse_transaction(tx, invoice_list=None)

Parses payments and creations from a Solana transaction.

Parameters:

• tx (Transaction) – The transaction.

• invoice_list (Optional[InvoiceList]) – (optional) A protobuf invoice list associated with the transaction.

Return type:

Tuple[List[Creation], List[ReadOnlyPayment]]

Returns:

A Tuple containing a List of ReadOnlyPayment objects and a List of Creation objects.

Module contents

class agora.model.AccountInfo(account_id, balance=None, owner=None, close_authority=None)

Bases: object

The information of a Kin account.

Parameters:

• account_id (PublicKey) – The ID of the account.

• balance (Optional[int]) – The balance of the account, in quarks. Included only if account info was requested.

• owner (Optional[PublicKey]) – The owner of the account, included only if it is a token account.

• close_authority (Optional[PublicKey]) – The close authority of the account, included only if it is a token account.

classmethod from_proto(proto)

Return type:

AccountInfo

class agora.model.AgoraMemo(val)

Bases: object

Implements the Agora memo specification as defined in github.com/kinecosystem/agora-api.

Parameters:

val (bytearray) – the raw memo bytearray.

app_index()

Returns the app index of the memo.

Return type:

int

Returns:

the int app index

foreign_key()

Returns the foreign key of the memo.

Return type:

bytes

Returns:

the foreign key

classmethod from_b64_string(s, strict=False)

Return type:

AgoraMemo

classmethod from_base_memo(m, strict=False)

Instantiates and returns an AgoraMemo object from a Memo, provided it is a valid (or strictly valid) Agora memo.

Parameters:

• m (Memo) – A Memo

• strict (Optional[bool]) – (optional). Dictates whether to strictly check validity of the memo or not. Defaults to False.

Return type:

AgoraMemo

Returns:

An AgoraMemo object.

classmethod from_xdr(xdr, strict=False)

Return type:

AgoraMemo

is_valid()

Returns whether or not the memo is valid.

It should be noted that there are no guarantees if the memo is valid, only if the memo is invalid. That is, this function may return false positives.

Stricter validation can be done via AgoraMemo.is_valid_strict(). However, AgoraMemo.is_valid_strict() is not as forward compatible.

Return type:

bool

Returns:

A bool indicating whether the memo is valid

is_valid_strict()

Returns whether or not the memo is valid checking against this implementation’s supported version.

It should be noted that there are no guarantees if the memo is valid, only if the memo is invalid. That is, this function may return false positives.

Return type:

bool

Returns:

A bool indicating whether the memo is strictly valid

classmethod new(version, tx_type, app_index, foreign_key)

Returns an Agora memo containing the provided properties.

Parameters:

• version (int) – The memo encoding version

• tx_type (TransactionType) – The TransactionType of the transaction

• app_index (int) – The index of the app the transaction relates to

• foreign_key (bytes) – An identifier in an auxiliary service that contains additional data about what the transaction was for

Return type:

AgoraMemo

Returns:

an AgoraMemo object

tx_type()

Returns the TransactionType of this memo.

Return type:

TransactionType

Returns:

TransactionType

tx_type_raw()

Returns the transaction type of the memo, even if is unsupported by this implementation. It should only be used as a fallback if the raw value is needed when agora.memo.AgoraMemo.transaction_type.py() yields TransactionType.UNKNOWN.

Return type:

int

Returns:

the int value of the memo transaction type

version()

Returns the memo encoding version of this memo.

Return type:

int

Returns:

the int memo encoding version

class agora.model.Creation(owner, address)

Bases: object

The Creation object, which represents a token account creation.

Parameters:

• owner (PublicKey) – The PublicKey of the account that owns this token account.

• address (PublicKey) – The PublicKey representing the address of the token account.

class agora.model.Earn(destination, quarks, invoice=None)

Bases: object

The Earn object, which represents an earn payment that will get submitted.

Parameters:

• destination (PublicKey) – The PublicKey of the account the earn will be sent to.

• quarks (int) – The amount being sent.

• invoice (Optional[Invoice]) – (optional) An Invoice object to associate with this earn.

class agora.model.EarnBatch(sender, earns, memo=None, subsidizer=None, dedupe_id=None)

Bases: object

The EarnBatch object, which represents a batch of Earn payments coming from a single sender.

Parameters:

• sender (PrivateKey) – The PrivateKey of the sender

• earns (List[Earn]) – A list of Earn objects.

• memo (Optional[str]) – (optional) The memo to include in the transaction. If set, none of the invoices included in earns will be applied.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used as the payer of the transaction.

• dedupe_id (Optional[bytes]) – (optional) The dedupe ID to use for the transaction submission. If included, Agora will verify that no transaction was previously submitted the same dedupe ID before submitting the transaction to the blockchain.

class agora.model.EarnBatchResult(tx_id, tx_error=None, earn_errors=None)

Bases: object

The BatchEarnResult object, which contains the results of a submitted earn batch.

Parameters:

• tx_id (bytes) – The id of the transaction that was submitted for the earn batch.

• tx_error (Optional[Error]) – (optional) An Error indicating why an earn batch failed. If tx_error is defined, the transaction failed.

• earn_errors (Optional[List[EarnError]]) – (optional) A List of any available earn-specific error information. May or may not be set if tx_error is set.

class agora.model.EarnError(earn_index, error)

Bases: object

The EarnError object contains earn-specific details about why a submitted earn batch failed

Parameters:

• earn_index (int) – The index of the earn the error pertains to

• error (Error) – The error

class agora.model.Invoice(items)

Bases: object

The :class: Invoice <Invoice> object, which represents a transaction invoice for a single payment.

Parameters:

items (List[LineItem]) – A list of LineItem objects.

classmethod from_proto(proto)

Return type:

Invoice

to_proto()

Return type:

Invoice

class agora.model.InvoiceList(invoices)

Bases: object

The InvoiceList object, which is a list of invoices associated with a transaction.

Parameters:

invoices (List[Invoice]) – a list of Invoice objects.

classmethod from_proto(proto)

Return type:

InvoiceList

get_sha_224_hash()

Returns the SHA-224 of the marshaled protobuf form of this invoice.

Return type:

bytes

Returns:

the SHA-224 hash.

to_proto()

Return type:

InvoiceList

class agora.model.LineItem(title, amount, description='', sku=None)

Bases: object

The LineItem object, which represents a line item in an invoice.

Parameters:

• title (str) – The title of the line item.

• amount (int) – The amount, in quarks.

• description (Optional[str]) – (optional) A description of the line item.

• sku (Optional[bytes]) – (optional) A SKU associated with the line item.

classmethod from_proto(proto)

Return type:

LineItem

to_proto()

Return type:

LineItem

class agora.model.Payment(sender, destination, tx_type, quarks, invoice=None, memo=None, subsidizer=None, dedupe_id=None)

Bases: object

The Payment object, which represents a payment that will get submitted.

Parameters:

• sender (PrivateKey) – The PrivateKey of the account from which funds will be sent.

• destination (PublicKey) – The PublicKey of the account to which funds will be sent.

• tx_type (TransactionType) – The TransactionType of this payment.

• quarks (int) – The amount being sent.

• invoice (Optional[Invoice]) – (optional) An Invoice to associate with this payment. Only one of invoice or memo should be set.

• memo (Optional[str]) – (optional) The text memo to include with the transaction. Only one of invoice or memo should be set.

• subsidizer (Optional[PrivateKey]) – (optional) The subsidizer to use for the create account transaction. The subsidizer will be used as the payer of the transaction.

• dedupe_id (Optional[bytes]) – (optional) The dedupe ID to use for the transaction submission. If included, Agora will verify that no transaction was previously submitted the same dedupe ID before submitting the transaction to the blockchain.

class agora.model.ReadOnlyPayment(sender, destination, tx_type, quarks, invoice=None, memo=None)

Bases: object

The ReadOnlyPayment object, which represents a payment that was retrieved from history.

Parameters:

• sender (PublicKey) – The PublicKey of the sending account.

• destination (PublicKey) – The PublicKey of the destination account.

• tx_type (TransactionType) – The type of this payment.

• quarks (int) – The amount of the payment.

• invoice (Optional[Invoice]) – (optional) The Invoice associated with this payment. Only one of invoice or memo will be set.

• memo (Optional[str]) – (optional) The text memo associated with this transaction. Only one of invoice or memo will be set.

class agora.model.TransactionData(tx_id, transaction_state, payments=None, error=None)

Bases: object

The TransactionData object, which contains information about the payments in a transaction.

Parameters:

• tx_id (bytes) – Either a 32-byte transaction hash, or a 64-byte transaction signature.

• payments (Optional[List[ReadOnlyPayment]]) – (optional) A list of ReadOnlyPayment objects.

• error (Optional[TransactionErrors]) – (optional)) A TransactionError object that contains extra details about why a transaction failed. If present, it indicates that the transaction failed.

classmethod from_proto(item, state)

Return type:

TransactionData

class agora.model.TransactionState(value)

Bases: enum.IntEnum

An enumeration.

FAILED = 2

PENDING = 3

SUCCESS = 1

UNKNOWN = 0

static from_proto(state)

static from_proto_v4(state)

class agora.model.TransactionType(value)

Bases: enum.IntEnum

The type of a transaction.

EARN = 1

NONE = 0

P2P = 3

SPEND = 2

UNKNOWN = -1

agora.model.parse_transaction(tx, invoice_list=None)

Parses payments and creations from a Solana transaction.

Parameters:

• tx (Transaction) – The transaction.

• invoice_list (Optional[InvoiceList]) – (optional) A protobuf invoice list associated with the transaction.

Return type:

Tuple[List[Creation], List[ReadOnlyPayment]]

Returns:

A Tuple containing a List of ReadOnlyPayment objects and a List of Creation objects.