Convex class

class convex_sdk.Convex(url: str)

Bases: object

Convex API client for interacting with the Convex network.

Convex is a decentralized platform based on lattice technology, not a blockchain. The Convex lattice enables efficient data organization and rapid transaction processing through the Convex Virtual Machine (CVM). The network utilizes Convergent Proof of Stake (CPoS) for secure consensus, allowing sub-second transaction confirmation times.

Parameters:: url (str) – URL of the Convex peer endpoint (e.g., ‘https://peer.convex.live’)

create_account(key_pair: KeyPair, sequence_retry_count: int = 20) → Account

Create a new account address on the Convex network.

Parameters:

key_pair (KeyPair) – KeyPair object that you wish to use as the signing account. The KeyPair object contains the public/private keys to access and submit commands on the Convex network.
sequence_retry_count (int, optional) – Number of retries to create the account. If too many clients are trying to create accounts on the same node, then we will get sequence errors.

Returns:

A new Account object, or copy of the Account object with a new address property value set

>>> from convex_sdk import Convex
>>> convex = Convex('https://convex.world')
>>> # Create a new account with new public/private keys and address
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> print(account.address)
>>> 42

>>> #create a new account address, but use the same keys as `account`
>>> new_account_address = convex.create_account(account=account)
>>> print(new_account.address)
>>> 43

get_account_info(address_account: Account | int | str) → AccountDetailsResponse

Get account information. This will only work with an account that has a balance or has had some transactions processed on the Convex network. New accounts with no transfers or transactions will raise:

ConvexRequestError(404, ‘The Account for this Address does not exist.’) error

The returned information is dictionary of account information.

Parameters:: address_account (Account, int, str) – Account object or address of an account to get current information on.
Returns:: dict of information, such as

>>> # Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> # get the account information
>>> print(convex.get_account_info(account))

{'environment': {}, 'address': 1178, 'memorySize': 0, 'balance': 0,
'isLibrary': False, 'isActor': False, 'allowance': 0,
'sequence': 0, 'type': 'user'}

get_address(function_name: str, address_account: Account | int | str)

Query the network for a contract ( function ) address. The contract must have been deployed by the account address provided. If not then no address will be returned

Parameters:

function_name (str) – Name of the contract/function
address_account (Account, int, str) – Account object or str address of an account to use for running this query.

Returns:

Returns address of the contract

>>> # Create a new account with new public/private keys and address
>>> account = convex_sdk.create_account()
>>> # find the address of a contract
>>> print(convex_sdk.get_address('my_contract', account))

get_balance(address_account: Account | int | str, account_from: Account | int | str | None = None)

Get a balance of an account.

At the moment the account needs to have a balance to get the balance of it’s account or any other account. Event though this is using a query request.

Parameters:

address_account (Account, int, str) – Address or Account object to get the funds for.
account_from (Account, int, str, optional) – Optional Account object or account address to make the request.

Returns:

Return the current balance of the address or account address_account

>>> # Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> # get the balance of the account
>>> print(convex.get_balance(account))
0
>>> print(convex.request_funds(100000, account))
100000
>>> print(convex.get_balance(account))
100000

load_account(name: str, key_pair: KeyPair) → Account | None

Load an account using the correct name. If successful return the Account object with the address set.

This is a Query operation, so no juice (Convex coins) are consumed when loading the account.

Parameters:

name (str) – name of the account to load
key_pair (KeyPair) – KeyPair object to import for the account

Results:

Account object with the address and name set and key_pair, if not found then return None

>>> # Create a new account with new public/private keys and address
>>> import_account = Account.import_from_file('my_account.pem', 'secret')
>>> account = convex.load_account('my_account, import_account)
>>> print(account.name)
my_account
>>> print(account.address)
930

load_contract(name: str)

query(transaction: str, address_account: int | str | Account)

Run a query on the Convex lattice. Since queries do not change the lattice state, the account does not need to sign the transaction and no juice (Convex coins) are consumed. For this reason you can just pass the account address, or if you want to the Account object.

Parameters:

transaction (str) – Convex Lisp source code to execute as a read-only query.
address_account (Account, int, str) – Account object or int address of an account to use for running this query.

Returns:

Return the resultant query transaction

>>> # Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)

>>> # submit a query using the account address

>>> print(convex.query(f'(balance {account.address})', account.address))
{'value': 0}

>>> # request some funds to do stuff
>>> print(convex.request_funds(100000, account))
100000
>>> print(convex.query(f'(balance {account.address})', account.address))
{'value': 100000}

register_account_name(name: str, address_account: Account | int | str, account: Account | None = None) → Account

Register or update an account address with an account name.

This call will submit to the CNS (Convex Name Service), a name in the format “account.<your_name>”. You need to have some convex balance in your account, and a valid account address.

Parameters:

name (str) – name of the account to register.
account_address (number|Account) – Account or address to register.
account (Account) – Account object to register the account name.

>>> # load the register account
>>> register_account = convex.load_account('register_account', key_pair)
>>> account = convex.create_account(key_pair)
>>> print(account.address)
1024
>>> account = convex.register_account('my_new_account', account.address, register_account)
>>> print(account.address)
1024

# or you can call with only one account, this will use the address of that account
>>> print(register_account.address)
404
>>> account = convex.register_account('my_new_account', register_account)
>>> print(account.address)
404

property registry: Registry

request_funds(amount: int, account: Account) → int

Request funds for an account from the Convex faucet.

Parameters:

amount (number) – The amount of funds to request
account (Account) – The Account object to receive funds too

Returns:

The amount transferred to the account

>>> # Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> # request some funds to do stuff
>>> print(convex.request_funds(100000, account))
100000

resolve_account_name(name: str) → int | None

Resolves an account name to an address. :param string name Name of the account to resolve.

>>> convex.resolve_account_name('my_account')
405

resolve_name(name: str) → int | None

Resolves any Convex Name Services to an address. :param string name Name of the the CNS Service. Optional @ prefix will be stripped.

>>> convex.resolve_name('convex.nft-tokens')
25
>>> convex.resolve_name('@convex.trust')
123

setup_account(name: str, key_pair: KeyPair, register_account: Account | None = None) → Account | None

Convenience method to create or load an account based on the account name. If the account name cannot be found then account will be created and account name registered, if the name is found, then account and it’s address with that name will be loaded.

Parameters:

name (str) – name of the account to create or load
key_pair (KeyPair) – KeyPair object to use to sign for the account.
register_account (Account) – Optional Account object to use for registration of the account

Results:

Account object with the address and name set, if not found then return None

Note If you do not provide a register_account, then this method calls the topup_account() method to get enough funds to register an account name.

>>> import_key_pair = KeyPair.import_from_file('my_account.pem', 'secret')
>>> # create or load the account named 'my_account'
>>> account = convex.setup_account('my_account', import_key_pair)
>>> print(account.name)
my_account

topup_account(account: Account, min_balance: int = 10000000, retry_count: int = 8)

Topup an account from the Convex faucet, so that the balance of the account is above or equal to the min_balance.

Parameters:

account (Account) – The Account object to receive funds for
min_balance (number, optional) – Minimum account balance that will allowed before a topup occurs
retry_count (number, optional) – The number of times the faucet will be called to get above or equal to the min_balance

Returns:

The amount transferred to the account

>>> # Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> # request some funds to do stuff
>>> print(convex.topup_account(account, 100000))
100000
>>> # try again, but only return 0 topup amount credited
>>> print(convex.topup_account(account, 100000))
0

transact(transaction: str, account: Account, sequence_retry_count: int = 20)

Submit a transaction to the Convex network.

Parameters:

transaction (str) – The transaction as a string to submit
account (Account) – The account that needs to sign the transaction
sequence_retry_count (int, optional) – Number of retries to do if a SEQUENCE error occurs. When submitting multiple transactions on the same account, you can get SEQUENCE errors, This transact method will automatically retry again

Returns:

The dict returned from the result of the submitted transaction.

>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://convex.world')

>>> # Create a new account with new public/private keys and address
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)

>>> # request some funds to do stuff
>>> print(convex.request_funds(100000, account))
100000

>>> # submit a transaction using the new account
>>> print(convex.transact('(map inc [ 1 2 3 4])', account))
{'value': [2, 3, 4, 5]}

transfer(to_address_account: Account | int | str, amount: int | float, account: Account)

Transfer funds from on account to another.

Parameters:

to_address_account (Account, int, str) – Address or Account object to send the funds too
amount (number) – Amount to transfer
account (Account) – Account object to send the funds from

Returns:

The transfer record sent back after the transfer has been made

>>> # Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> print(convex.request_funds(10000000, account))
10000000
>>> print(convex.get_balance(account))
10000000

>>> my_key_pair = KeyPair()
>>> my_account = convex.create_account(my_key_pair)
>>> # transfer some funds to my_account
>>> print(convex.transfer(my_account, 100, account))
100
>>> print(convex.get_balance(my_account))
100
>>> print(convex.get_balance(account))
9998520

transfer_account(from_account: Account | int | str, to_account: Account | int | str)

WARNING If you do not save the from_account keys for later use, this call can stop you from accessing your transferred to_account.

Transfer and copy the keys from the from_account over too the to_account.

Parameters:

from_account (Account) – Account object that has public/private keys you with to copy
to_account (Account) – Account object that has an address and you wish to change to now

use the to_account access keys.

Returns:: A new account object that has the same name and address as the to_account, but with

the access keys of the from_account.

# Create a new account with new public/private keys and address
>>> from convex_sdk import Convex, KeyPair, Account
>>> convex = Convex('https://peer.convex.live')
>>> key_pair = KeyPair()
>>> account = convex.create_account(key_pair)
>>> account.public_key
'0xae4c019e68591e085d52cdb41924bde067d864cecb1780faa37142054b0fd8ef'

# get a saved account keys
>>> import_account = Account.import_from_file('my_account.pem', 'secret')
>>> import_account.public_key
'5288fec4153b702430771dfac8aed0b21cafca4344dae0d47b97f0bf532b3306'


# transfer the loaded keys from the `import_account`, to `account`
>>> account = convex.transfer_account(import_account, account)
>>> account.public_key
'5288fec4153b702430771dfac8aed0b21cafca4344dae0d47b97f0bf532b3306'