v1.1.3

Author: hschickdevs

MANIFEST.in

@@ -1,2 +1,2 @@
-recursive-include alpaca_finance/abi *
+recursive-include alpaca_finance/automated_vault/abi *
 include requirements.txt

README.md

@@ -55,14 +55,16 @@ How to use the package
     from alpaca_finance.automated_vault import AutomatedVaultPosition
     ```
 
+<!--
 2. ***(Optional)*** Create your Web3 provider object to interact with the network (By default, the BSC RPC URL is used):
     ```python
     from alpaca_finance.util import get_web3_provider
 
     provider = get_web3_provider("your_rpc_url")
     ```
+-->
 
-3. Creating an [AutomatedVaultPosition](alpaca_finance/automated_vault/positions.py) instance requires the following:
+2. Creating an [AutomatedVaultPosition](alpaca_finance/automated_vault/positions.py) instance requires the following:
     - Your position key (string)
         - This key should match your position key on Alpaca Finance's webapp
         - ![demo](img/demo.png)
@@ -76,6 +78,21 @@ How to use the package
     ```python
     position = AutomatedVaultPosition(position_key="n3x-BNBBUSD-PCS1", owner_wallet_address="0x...", owner_private_key="123abc456efg789hij...")
     ```
+   
+3. How to **approve tokens**:
+    - Tokens that have never been approved on the Alpaca web interface will need to be approved programmatically
+    - The current options for token approval are as follows:
+      1. Using the `AutomatedVaultPosition.auto_token_approval` attribute:
+         ```python
+         # Set to False by default
+         # Tokens are only approved if the allowance is insufficent for the transaction
+         position.auto_token_approval = True
+         ```
+      2. Using the `AutomatedVaultPosition.do_approve_token` method:
+      
+         See the [approve_token.ipynb](examples/automated_vault/approve_token.ipynb) example file
+      
+
 4. Use your position instance to interact with Alpaca Finance:
     - For reference, see the BEP20Token class [documentation](https://github.com/hschickdevs/Python-BEP20-Token/blob/main/bep20/token.py)
     - Please view the **usage examples** under [examples/automated_vault](examples/automated_vault)

alpaca_finance/__init__.py

@@ -1 +1 @@
-__version__ = "1.1.1"
+__version__ = "1.1.3"

alpaca_finance/automated_vault/position.py

@@ -46,36 +46,47 @@ def __init__(self, position_key: str, owner_wallet_address: str, owner_wallet_ke
         self.stable_token = BEP20Token(self.vault.stableTokenAddress(), self.w3_provider)
         self.asset_token = BEP20Token(self.vault.assetTokenAddress(), self.w3_provider)
 
+        # If True, enables the allowance verification and automatic approval of tokens before transactions
+        self.auto_token_approval = False
+
+        # Specify custom web3 transaction gasPrice parameter for the BSC transactions
+        self.gasPrice = 5000000000
+
     """ ------------------ Transactional Methods (Requires private wallet key) ------------------ """
 
-    def do_invest(self, stable_token_amt: int = 0, asset_token_amt: int = 0, _approve=False) -> TransactionReceipt:
+    def do_invest(self, stable_token_amt: int = 0, asset_token_amt: int = 0) -> TransactionReceipt:
         """
         Invest the specified amount of each token into the Automated Vault.
         Use self.asset_token and self.stable_token to identify the underlying assets.
 
         :param stable_token_amt: The amount of stable token to deposit
         :param asset_token_amt: The amount of asset token to deposit
-        :param _approve: If True, approves the deposit token for spending by the vault token
-        :return:
+
+        :return: TransactionReceipt object
         """
         assert stable_token_amt > 0 or asset_token_amt > 0, \
             "Please provide an investment value for either the stable or asset tokens"
 
+        txn_nonce = self._get_nonce()
+
         # Ensure that allowances match desired investment amount
         if stable_token_amt > 0:
             token_bal = self.stable_token.balanceOf(self.owner_address)
             assert token_bal >= stable_token_amt, \
                 f"Insufficient funds to invest {stable_token_amt} {self.stable_token.symbol()} ({token_bal} Owned)"
-            if _approve:
-                self.do_approve_token(self.stable_token)
+            if self.auto_token_approval:
+                if self.do_approve_token(self.stable_token) is not None:
+                    txn_nonce += 1
         if asset_token_amt > 0:
             token_bal = self.asset_token.balanceOf(self.owner_address)
             assert token_bal >= asset_token_amt, \
                 f"Insufficient funds to invest {asset_token_amt} {self.asset_token.symbol()} ({token_bal} Owned)"
-            if _approve:
-                self.do_approve_token(self.asset_token)
+            if self.auto_token_approval:
+                if self.do_approve_token(self.asset_token) is not None:
+                    txn_nonce += 1
 
-        return self._execute(self.vault.invest(stable_token_amt, asset_token_amt, shareReceiver=self.owner_address))
+        return self._execute(self.vault.invest(stable_token_amt, asset_token_amt, shareReceiver=self.owner_address),
+                             _nonce=txn_nonce)
 
     def do_withdraw(self, shares: int, pct_stable: float = None, strategy: str = "Minimize Trading") -> TransactionReceipt:
         """
@@ -89,56 +100,90 @@ def do_withdraw(self, shares: int, pct_stable: float = None, strategy: str = "Mi
         assert self.shares()[0] >= shares, f"Shares owned insufficient to withdraw {shares} " \
                                            f"({self.from_wei(shares, self.bep20_vault_token.decimals())}) shares"
 
+        txn_nonce = self._get_nonce()
+
+        # Process withdraw functions according to the strategy passed:
         if strategy.lower() == "minimize trading":
-            # assert self.bep20_vault_token.allowance(self.owner_address, self.vault.address) >= shares, \
-            #     f"Insufficient approval amount - Spender ({self.vault.address}) requires an allowance of {shares} " \
-            #     f"{self.bep20_vault_token.symbol()} ({self.bep20_vault_token.address})"
+            if self.auto_token_approval:
+                if self.do_approve_token(self.bep20_vault_token, _spender=self.vault.address, _min_amount=shares) is not None:
+                    txn_nonce += 1
+            else:
+                assert self.bep20_vault_token.allowance(self.owner_address, self.vault.address) >= shares, \
+                    f"Insufficient approval amount - Spender ({self.vault.address}) requires an allowance of {shares} " \
+                    f"{self.bep20_vault_token.symbol()} ({self.bep20_vault_token.address})"
+
+            return self._execute(self.vault.withdraw(shares), _nonce=txn_nonce)
 
-            return self._execute(self.vault.withdraw(shares))
         elif strategy.lower() == "convert all":
             assert pct_stable is not None, "Please provide a stable token percentage to determine token swap"
-            assert self.bep20_vault_token.allowance(self.owner_address, self.gateway.address) >= shares, \
-                f"Insufficient approval amount - Spender ({self.gateway.address}) requires an allowance of {shares} " \
-                f"{self.bep20_vault_token.symbol()} ({self.bep20_vault_token.address})"
 
-            assert 0.0 < pct_stable <= 1.0, "Invalid value for pct_stable parameter, must follow 0.0 < pct_stable <= 1.0"
+            if self.auto_token_approval:
+                if self.do_approve_token(self.bep20_vault_token, _spender=self.gateway.address, _min_amount=shares) is not None:
+                    txn_nonce += 1
+            else:
+                assert self.bep20_vault_token.allowance(self.owner_address, self.gateway.address) >= shares, \
+                    f"Insufficient approval amount - Spender ({self.gateway.address}) requires an allowance of {shares} " \
+                    f"{self.bep20_vault_token.symbol()} ({self.bep20_vault_token.address})"
+
+            assert 0.0 <= pct_stable <= 1.0, "Invalid value for pct_stable parameter, must follow 0.0 <= pct_stable <= 1.0"
 
             stable_return_bps = floor(pct_stable * 10000)
 
-            return self._execute(self.gateway.withdraw(shares, stableReturnBps=stable_return_bps))
+            return self._execute(self.gateway.withdraw(shares, stableReturnBps=stable_return_bps), _nonce=txn_nonce)
+
         else:
             raise ValueError("Invalid strategy - Options are 'Minimize Trading' or 'Convert All'")
 
     def do_close(self, pct_stable: float = None, strategy: str = "Minimize Trading") -> TransactionReceipt:
         """
         Withdraws all outstanding shares from the pool and closes position.
 
-        :param pct_stable: See self.withdraw()
-        :param strategy: See self.withdraw()
+        :param pct_stable: See self.do_withdraw()
+        :param strategy: See self.do_withdraw()
         """
-        return self.do_withdraw(shares=self.shares()[0], pct_stable=pct_stable, strategy=strategy)
+        shares = self.shares()[0]
 
-    def do_approve_token(self, token: Union[BEP20Token, str], amount: int = None, _spender: str = None) -> TransactionReceipt:
+        assert shares > 0, f"Cannot close position with a balance of {shares} shares."
+
+        return self.do_withdraw(shares=shares, pct_stable=pct_stable, strategy=strategy)
+
+    def do_approve_token(self, token: Union[BEP20Token, str], amount: int = None, _min_amount: int = None,
+                         _spender: str = None) -> Union[TransactionReceipt, None]:
         """
         Approves the given token for usage by the Automated Vault.
 
         :param token: Optional - either the BEP20Token object, or the token address (str)
         :param amount: The amount of token to approve, default = maximum
         :param _spender: (Should not be changed by the caller) The address to give token spending access to
+        :param _min_amount: Used for internal functions when checking to see if a token has the minimum approval requirement
+
+        :return:
+            If the current token allowance already meets or exceeds the given amount:
+                - None
+            Else if the current token allowance does not meet the given amount:
+                - TransactionReceipt object
         """
         if type(token) != BEP20Token:
             token = BEP20Token(token)
 
+        print(f"Approving {token.symbol()}...")
+
         if amount is None:
             # Use maximum approval amount if no amount is specified
             amount = 2 ** 256 - 1
 
         if _spender is None:
             _spender = self.address
 
-        func_call = token.prepare_approve(checksum(_spender), amount)
+        if token.allowance(self.owner_address, _spender) >= (amount if _min_amount is None else _min_amount):
+            print("Approval canceled - allowance already exceeds amount")
+            return None
 
-        return self._execute(func_call)
+        txn = self._execute(token.prepare_approve(checksum(_spender), amount))
+
+        print(f"Approved {'MAX' if amount == (2 ** 256 - 1) else amount} {token.symbol()} for contract {_spender}.")
+
+        return txn
 
 
     """ ---------------- Informational Methods (Private wallet key not required) ---------------- """
@@ -187,6 +232,14 @@ def get_vault_summary(self, position_key: str = None) -> AttrDict:
         for vault in r.json()["data"]["strategyPools"]:
             if vault["key"].lower() == position_key:
                 return AttrDict(vault)
+            else:
+                try:
+                    if vault["iuToken"]["symbol"].lower() == position_key:
+                        print(f"Warning: Had to use iuToken to match vault data instead of key (Key = {vault['key']})")
+                        return AttrDict(vault)
+                except KeyError:
+                    # In the event that the vault data did not have an iuToken key for some reason
+                    pass
         else:
             raise ValueError(f"Could not locate a vault with the key {self.key}")
 
@@ -261,7 +314,7 @@ def cost_basis(self) -> float:  # tuple[float, float]
 
     """ -------------------------------- Utility Methods -------------------------------- """
 
-    def _execute(self, function_call: web3.contract.ContractFunction) -> TransactionReceipt:
+    def _execute(self, function_call: web3.contract.ContractFunction, _nonce: int = None) -> Union[TransactionReceipt, AttrDict]:
         """
         :param function_call: The uncalled and prepared contract method to sign and send
         """
@@ -272,8 +325,8 @@ def _execute(self, function_call: web3.contract.ContractFunction) -> Transaction
             "from": self.owner_address,
             'chainId': 56,  # 56: BSC mainnet
             # 'gas': 76335152,
-            'gasPrice': 5000000000,
-            'nonce': self.w3_provider.eth.get_transaction_count(self.owner_address),
+            'gasPrice': self.gasPrice,  # 5000000000
+            'nonce': self._get_nonce() if _nonce is None else _nonce,
         })
         # print(txn)
 
@@ -289,7 +342,10 @@ def _execute(self, function_call: web3.contract.ContractFunction) -> Transaction
         except Exception as exc:
             print(f"COULD NOT BUILD TRANSACTION RECEIPT OBJECT - {exc}")
             # Catch case to prevent receipt from being lost if TransactionReceipt object somehow can't be built
-            return receipt
+            return AttrDict(receipt)
+
+    def _get_nonce(self) -> int:
+        return self.w3_provider.eth.get_transaction_count(self.owner_address)
 
     @staticmethod
     def to_wei(amt: float, decimals: int) -> int:
@@ -316,8 +372,10 @@ def _decode_withdraw_transaction(self, transaction_address: Optional):
 
         try:
             decoded_bank_transaction = self.vault.contract.decode_function_input(transaction.input)
+            print("withdraw on vault")
         except:
             decoded_bank_transaction = self.gateway.contract.decode_function_input(transaction.input)
+            print("withdraw on gateway")
 
         decoded_calldata = decode_abi(
             ['uint256', 'uint256'],
@@ -339,12 +397,14 @@ def _decode_deposit_transaction(self, transaction_address: Optional):
         )
         """
         transaction = self.w3_provider.eth.get_transaction(transaction_address)
-        # print(transaction)
+        print(transaction)
 
         try:
             decoded_bank_transaction = self.vault.contract.decode_function_input(transaction.input)
+            print("deposit on vault")
         except:
             decoded_bank_transaction = self.gateway.contract.decode_function_input(transaction.input)
+            print("deposit on gateway")
 
         decoded_calldata = decode_abi(
             ["uint256"],

examples/automated_vault/approve_token.ipynb

@@ -66,6 +66,15 @@
     "position.name, position.key, position.asset_token.symbol(), position.bep20_vault_token.symbol()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **NOTE**: As of v1.1.3, you can now set the `position.auto_token_approval` attribute to `True` to automatically approve tokens.\n",
+    "\n",
+    "- This will only approve tokens that lack the required allowance for the transaction to be completed."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

examples/automated_vault/close_position.ipynb

@@ -72,7 +72,8 @@
    "source": [
     "### Close the Position (Automatically withdraws all shares):\n",
     "\n",
-    "- Using the \"convert all\" strategy to withdraw tokens"
+    "- Using the \"convert all\" strategy to withdraw tokens\n",
+    "- Setting `auto_token_approval` to `True` so that the contract can automatically withdraw tokens even if the vault token has not been approved."
    ]
   },
   {
@@ -92,6 +93,8 @@
     }
    ],
    "source": [
+    "position.auto_token_approval = True\n",
+    "\n",
     "txn_receipt = position.do_close(pct_stable=1.0, strategy=\"convert all\")\n",
     "txn_receipt"
    ]

examples/automated_vault/invest.ipynb

@@ -63,6 +63,10 @@
     "# Create a automated vault position instance:\n",
     "position = AutomatedVaultPosition(position_key=POSITION_KEY, owner_wallet_address=PUBKEY, owner_wallet_key=PRIVKEY)\n",
     "\n",
+    "# Set automated token approval so that allowances on deposit tokens are increased if needed:\n",
+    "position.auto_token_approval = True\n",
+    "\n",
+    "# Show position info:\n",
     "position.name, position.key, position.shares()[1]"
    ]
   },

examples/automated_vault/withdraw.ipynb

@@ -63,6 +63,10 @@
     "# Create a automated vault position instance:\n",
     "position = AutomatedVaultPosition(position_key=POSITION_KEY, owner_wallet_address=PUBKEY, owner_wallet_key=PRIVKEY)\n",
     "\n",
+    "# Enable auto token approval so that allowances are extended automatically if needed:\n",
+    "position.auto_token_approval = True\n",
+    "\n",
+    "# Show position Info:\n",
     "position.name, position.key, position.shares()[1]"
    ]
   },

setup.py

@@ -1,20 +1,28 @@
-from setuptools import setup
+from setuptools import setup, find_packages
 import sys
 
 from alpaca_finance import __version__
 
 if sys.version_info < (3, 9):
     sys.exit('Python 3.9+ required to install this package. Install it here: https://www.python.org/downloads/')
 
+
+def readme():
+    with open("README.md") as infile:
+        return infile.read().strip()
+
+
 setup(
     name='alpaca_finance',
     version=__version__,
     author='Harrison Schick',
     author_email='[email protected]',
     description='An unofficial Python3.9+ package that models positions on the Alpaca Finance platform to simplify interaction with their smart contracts in your Python projects.',
+    long_description=readme(),
+    long_description_content_type="text/markdown",
     url='https://github.com/PathX-Projects/Alpaca-Finance-Python',
     # license='MIT',
-    packages=['alpaca_finance'],
+    packages=find_packages(),
     include_package_data=True,
     install_requires=[line.strip() for line in open('requirements.txt').readlines()],
 )