convex-sdk 0.3.2__py2.py3-none-any.whl

convex_sdk/__init__.py

@@ -0,0 +1,12 @@
+"""
+
+    Convex API Python Library
+
+"""
+
+from convex_sdk.account import Account                   # type: ignore # noqa: F401
+from convex_sdk.convex import Convex                     # type: ignore # noqa: F401
+from convex_sdk.contract import Contract                 # type: ignore # noqa: F401
+from convex_sdk.key_pair import KeyPair                  # type: ignore # noqa: F401
+
+__version__ = '0.3.2'

convex_sdk/account.py

@@ -0,0 +1,192 @@
+"""
+
+    Account class for convex api
+
+
+"""
+from __future__ import annotations
+
+import re
+from convex_sdk.key_pair import KeyPair
+
+
+class Account:
+
+    @staticmethod
+    def is_address(text: int | str) -> bool:
+        """
+        Returns True if the text value is a valid address.
+
+        :param str, int text: Possible address field.
+
+        :returns: True if the text field is a valid address.
+
+        """
+        return Account.to_address(text) >= 0
+
+    @staticmethod
+    def to_address(value: Account | int | str) -> int:
+        """
+        Convert address text with possible leading '#' to an integer address value.
+
+        :param str text: Address text to convert
+
+        :returns: Integer address
+
+        :raises ValueError: If the address is not valid
+
+        """
+        if isinstance(value, Account):
+            return value.address
+        elif isinstance(value, int):
+            return int(value)
+        else:
+            try:
+                address = int(re.sub(r'^#', '', value.strip()))
+            except ValueError:
+                raise ValueError(f'Invalid address {value}')
+            return address
+
+    def __init__(self, key_pair: KeyPair, address: Account | int | str, name: str | None = None):
+        """
+
+        Create a new account with a private key KeyPair.
+
+        :param KeyPair key_pair: The public/private key of the account
+
+        :param int address: address of the account
+
+        :param str name: Optional name of the account
+
+        .. code-block:: python
+
+            >>> # import convex-api
+            >>> from convex_sdk import Convex, KeyPair, Account
+
+            >>> # setup the network connection
+            >>> convex = Convex('https://convex.world')
+
+            >>> # create a random keypair
+            >>> key_pair = KeyPair()
+
+            >>> # create a new account and address
+            >>> account = convex.create_account(key_pair)
+
+            >>> # export the private key to a file
+            >>> key_pair.export_to_file('/tmp/my_account.pem', 'my secret password')
+
+            >>> # save the address for later
+            >>> my_address = account.address
+
+            >>> # ----
+
+            >>> # now import the account and address for later use
+            >>> key_pair = KeyPair.import_from_file('/tmp/my_account.pem', 'my secret password')
+            >>> account = Account(key_pair, my_address)
+
+
+        """
+        self._key_pair = key_pair
+        self._address = Account.to_address(address)
+        self._name = name
+
+    def sign(self, hash_text: str) -> str:
+        """
+
+        Sign a hash text using the internal key_pair.
+
+        :param str hash_text: Hex string of the hash to sign
+
+        :returns: Hex string of the signed text
+
+        .. code-block:: python
+
+            >>> # create an account
+            >>> account = convex.create_account(key_pair)
+            >>> # sign a given hash
+            >>> sig = account.sign('7e2f1062f5fc51ed65a28b5945b49425aa42df6b7e67107efec357794096e05e')
+            >>> print(sig)
+            '5d41b964c63d1087ad66e58f4f9d3fe2b7bd0560b..'
+
+        """
+        return self._key_pair.sign(hash_text)
+
+    def __str__(self):
+        return f'Account {self.address}:{self.key_pair.public_key}'
+
+    @property
+    def address(self) -> int:
+        """
+
+        :returns: the network account address
+        :rtype: int
+
+        .. code-block:: python
+
+            >>> # create an account with the network
+            >>> key_pair = KeyPair()
+            >>> account = convex.create_account(key_pair)
+            >>> print(account.address)
+            42
+
+        """
+        return self._address
+
+    @address.setter
+    def address(self, value: Account | int | str) -> None:
+        """
+
+        Sets the network address of this account
+
+        :param value: Address to use for this account
+        :type value: str, int
+
+        .. code-block:: python
+
+            >>> # import the account keys
+            >>> key_pair = KeyPair.import_from_mnemonic('my private key words ..')
+
+            >>> account = convex.create_account(key_pair)
+            >>> # set the address that was given to us when we created the account on the network
+            >>> account.address = 42
+
+        """
+        self._address = Account.to_address(value)
+
+    @property
+    def name(self) -> str | None:
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        self._name = value
+
+    @property
+    def public_key(self) -> bytes:
+        """
+
+        Return the public key of the account in the format '0x....'
+
+        :returns: public_key with leading '0x'
+        :rtype: str
+
+        .. code-block:: python
+
+            >>> # create an account with the network
+            >>> account = convex.create_account(key_pair)
+
+            >>> # show the public key as a hex string
+            >>> print(account.public_key)
+            0x36d8c5c40dbe2d1b0131acf41c38b9d37ebe04d85...
+
+        """
+        return self._key_pair.public_key_bytes
+
+    @property
+    def key_pair(self) -> KeyPair:
+        """
+
+        Return the internal KeyPair object for this account
+
+        """
+        return self._key_pair

convex_sdk/contract.py

@@ -0,0 +1,211 @@
+"""
+
+
+Convex Contract
+
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from convex_sdk.convex import Convex
+
+import re
+
+from convex_sdk.account import Account
+
+
+class Contract:
+    def __init__(self, convex: Convex):
+        """
+
+        Contract class to provide access and name resolution to deployed convex contracts.
+
+        """
+        self._convex = convex
+        self._name = None
+        self._address = None
+        self._owner_address = None
+
+    def load(
+        self,
+        name: str | None = None,
+        address: Account | int | str | None = None,
+        owner_address: Account | int | str | None = None
+    ):
+        """
+
+        Load a contract details using it's registered name or directly using it's known address.
+
+        :param str name: Name of the contract that has been registered.
+        If provided the address and owner_address of the registration is stored within this object
+
+        :param str, int, Account address: Address of the contract, if the name is not known,
+        then you can provide the actual address of the contract.
+
+        :param str, int, Account owner_address: If the contract is registered the owner address of the registration.
+
+        :returns int The address of the resolved contract
+
+        """
+        if name:
+            address = self.resolve_address(name)
+            owner_address = self.resolve_owner_address(name)
+            self._name = name
+
+        if address is None:
+            raise ValueError('no contract found')
+
+        if owner_address is None:
+            owner_address = address
+
+        self._address = Account.to_address(address)
+        self._owner_address = Account.to_address(owner_address)
+        return self._address
+
+    def deploy(
+        self,
+        account: Account,
+        text: str | None = None,
+        filename: str | None = None,
+        name: str | None = None,
+        owner_account: Account | None = None
+    ):
+        """
+
+        Deploy a new/updated contract on the Convex network.
+
+        :param Account account: Account to use to deploy the contract
+
+        :param str text: Contract text to deploy
+
+        :param str filename: Filename of the contract to deploy
+
+        :param str name: Name of the contract to register
+
+        :param Account owner_account: Optional owner account of the registration.
+        If not provided then the Account will be used.
+
+        :returns Address of the new contract
+
+        """
+        if filename:
+            with open(filename, 'r') as fp:
+                text = fp.read()
+        if text is None:
+            raise ValueError('You need to provide a contract filename or text to deploy')
+        deploy_line = f"""
+(deploy
+    (quote
+        (do
+            {text}
+        )
+    )
+)
+    """
+        result = self._convex.transact(deploy_line, account)
+        if result is not None and result.value:
+            address = Account.to_address(result.value)
+            if name:
+                if owner_account is None:
+                    owner_account = account
+                self._convex.registry.register(name, address, owner_account)
+            return address
+
+    def register_contract_name(self, name: str, address: int, account: Account):
+        """
+
+        Register a contract address with a resolvable name. This name can be used on the Convex network to resolve
+        to the contract address.
+
+        :param str name: Name to register.
+
+        :param str, int, Account address: Address to use to assign with the name.
+
+        :param Account account: Account who owns the registration.
+
+        :returns Result from the register transaction
+
+        """
+        return self._convex.registry.register(name, address, account)
+
+    def transact(self, transaction: str, account: Account):
+        """
+
+        Submit a transaction to the contract. You need to run `load` before calling this method.
+
+        :param str transaction: Transaction to submit to the contract.
+
+        :param Account account: Account to pay for the transaction.
+
+        :returns The transaction result.
+
+        """
+        if not self._address:
+            raise ValueError(f'No contract address found for {self._name}')
+        return self._convex.transact(f'(call #{self._address} {transaction})', account)
+
+    def query(self, transaction: str, account_address: Account | int | str | None = None):
+        """
+
+        Sends a query to the contract.
+
+        :param str transaction: The transaction query to send to the contract
+
+        :param str, int, Account account_address: The address to provide as the sender for this query.
+
+        :returns The query result
+
+        """
+        if not self._address:
+            raise ValueError(f'No contract address found for {self._name}')
+        if account_address is not None:
+            account_address = Account.to_address(account_address)
+        if account_address is None:
+            account_address = self._address
+        return self._convex.query(f'(call #{self._address} {transaction})', account_address)
+
+    def resolve_address(self, name: str):
+        """
+
+        Return an address from a registered name.
+
+        """
+        return self._convex.registry.resolve_address(name)
+
+    def resolve_owner_address(self, name: str):
+        """
+
+        Returns the register owner of a registered name.
+
+        """
+        return self._convex.registry.resolve_owner(name)
+
+    @property
+    def is_registered(self) -> bool:
+        return self._address is not None
+
+    @property
+    def address(self):
+        return self._address
+
+    @property
+    def owner_address(self):
+        return self._owner_address
+
+    @property
+    def name(self):
+        return self._name
+
+    @staticmethod
+    def escape_string(text: str) -> str:
+        """
+        Escape any string and replace quote chars with leading escape chars
+
+        """
+        escape_text = re.sub('\\\\', '\\\\\\\\', text)
+        escape_text = re.sub('"', '\\"', escape_text)
+        escape_text = re.sub('\n', '\\\\n', escape_text)
+        escape_text = re.sub('\t', '\\\\t', escape_text)
+        return escape_text