Version 1.0.0 - Core functionality changed

Author: hschickdevs

README.md

@@ -4,16 +4,16 @@
   <a href ="https://www.alpacafinance.org//"><img src="https://pbs.twimg.com/profile_images/1481749291379081217/KGzK2UQS_400x400.png" alt="Alpaca Finance Logo" height="200"></a>
   <br></br>
   <h2 align="center"><strong>Alpaca-Finance-Python</strong></h2>
-  <img src="https://img.shields.io/badge/Python-3.9%2B-yellow"/>&nbsp&nbsp<img src="https://img.shields.io/badge/Chain-BSC-yellow"></img>
+  <img src="https://img.shields.io/badge/Python-3.9%2B-yellow"/>&nbsp&nbsp<img src="https://img.shields.io/badge/Supported Network-BSC-yellow"></img>
     <p align="center">
-        An unofficial Python3.9+ package that models positions on the Alpaca Finance platform to simplify interaction with their smart contracts in your Python projects.
+        An unofficial Python3.9+ package that models Binance Smart Chain positions on the Alpaca Finance platform to simplify interaction with their smart contracts in your Python projects.
     </p>
     <h3><strong>Supported Position Types</strong></h3>
     <i>Automated Vaults</i><br>
 </div>
 <br>
 
-> NOTE: Codebase is currently in development and incomplete
+> NOTE: Existing users please update to the latest version of the package before using, core functionality has changed in version 1+.
 
 <!-- TABLE OF CONTENTS -->
 ### Table of Contents
@@ -36,8 +36,7 @@ This package is set up to be installed using the `pip` package manager.
     ```bash
     pip install --upgrade git+https://github.com/PathX-Projects/Alpaca-Finance-Python.git
     ```
-
-    ***Note:*** You may need to provide your git credentials depending on the repository privacy settings. In the event, if you need help generating a personal access token see [here](https://catalyst.zoho.com/help/tutorials/githubbot/generate-access-token.html)
+    <!-- ***Note:*** You may need to provide your git credentials depending on the repository privacy settings. In the event, if you need help generating a personal access token see [here](https://catalyst.zoho.com/help/tutorials/githubbot/generate-access-token.html) -->
 
 2. After install, the package will be available to you in your local Python environment as ***alpaca_finance***
 
@@ -47,7 +46,9 @@ ___
 
 ## Usage
 
-How to use the package:
+How to use the package
+
+### Automated Vaults:
 
 1. Import the package into your Python script:
     ```python
@@ -61,8 +62,6 @@ How to use the package:
     provider = get_web3_provider("your_rpc_url")
     ```
 
-### Automated Vaults:
-
 3. 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
@@ -78,32 +77,73 @@ How to use the package:
     position = AutomatedVaultPosition(position_key="n3x-BNBBUSD-PCS1", owner_wallet_address="0x...", owner_private_key="123abc456efg789hij...")
     ```
 4. Use your position instance to interact with Alpaca Finance:
-    ```python
+    - 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)
+    ```python    
     """ Informational Methods (Private Key not Required) """
 
+    # Get the asset token or stable token for the vault (BEP20Token object)
+    position.asset_token, position.stable_token
+
+
     # Get the current yields for the vault:
     position.yields()
 
+
     # Get the current vault TVL:
     position.tvl()
 
+
     # Get the current vault capacity:
     position.capacity()
 
+
     # Get the position's cost basis (entry price in USD):
     position.cost_basis()
 
+
     # Get the current position value (in USD):
     position.current_value()
 
+
     # Get the position profit/loss (PnL in USD):
     position.pnl()
 
+
     # Get the amount of shares held and the USD value of all shares held:
     position.shares()
 
+
     # get the full vault summary (See the documentation alpaca_fiance/position.py for more details):
     position.get_vault_summary()
+
+
+    """ Transactional Methods (Private Key Required) """
+
+
+    # Approve a token for deposit to the vault (only required once if never approved):
+    position.approve_token(<token_address> or <BEP20Token object>)
+
+
+    # Invest the given amount of stable and asset token into the vault:
+    position.do_invest(<stable_token_amt>, <asset_token_amt>)
+
+
+    # Withdraw the given amount of shares from the vault:
+    # Available strategies: "Minimize Trading" and "Convert All" (as shown on the webapp)
+
+    # Using the "Minimize Trading" strategy (default, so not necessary to specify strategy):
+    position.do_withdraw(<shares_amt>)
+    # Using the "Convert All" strategy (must specify, and provide the percentage of stable token to receive):
+    position.do_withdraw(<shares_amt>, <pct_stable_token>, strategy="Convert All")  
+
+
+    # Close a position (remove all shares):
+
+    # (default) Using the "Minimize Trading" strategy:
+    position.do_close()
+    # Optionally specify the "Convert All" strategy:
+    position.do_close(<pct_stable_token>, strategy="Convert All")
     ```
 
 ___

alpaca_finance/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

alpaca_finance/automated_vault/contracts.py

@@ -76,8 +76,18 @@ def __init__(self, vault_address: str, w3_provider: Web3 = None, protocol: str =
         self.partialCloseMinimizeStrat = {"pancakeswap": r['SharedStrategies']["Pancakeswap"]["StrategyPartialCloseMinimizeTrading"],
                                           "biswap": r['SharedStrategies']["Biswap"]["StrategyPartialCloseMinimizeTrading"]}
 
-    def invest(self) -> web3.contract.ContractFunction:
-        pass
+    def invest(self, stableTokenAmount: int, assetTokenAmount: int, shareReceiver: str) -> web3.contract.ContractFunction:
+        """Invest the specified token into the vault"""
+
+        minShareReceive = 0  # Slippage
+
+        _calldata = encode_abi(
+            ["uint256"],
+            [25]
+        )
+
+        return self.contract.functions.deposit(stableTokenAmount, assetTokenAmount, checksum(shareReceiver),
+                                               minShareReceive, _calldata)
 
     def withdraw(self, shares: int) -> web3.contract.ContractFunction:
         """

alpaca_finance/automated_vault/position.py

@@ -1,4 +1,4 @@
-from typing import Optional, Union
+from typing import Union, Optional
 from math import floor
 
 from ..util import get_entry_prices, get_web3_provider, get_vault_addresses
@@ -20,6 +20,8 @@ def __init__(self, position_key: str, owner_wallet_address: str, owner_wallet_ke
             self.w3_provider = get_web3_provider(DEFAULT_BSC_RPC_URL)
         else:
             self.w3_provider = w3_provider
+        if self.w3_provider.eth.chainId != 56:
+            raise ValueError("This package currently supports positions on the Binance Smart Chain (BSC - 56) network only")
 
         summary = self.get_vault_summary(position_key.lower())
 
@@ -45,8 +47,19 @@ def __init__(self, position_key: str, owner_wallet_address: str, owner_wallet_ke
 
     """ ------------------ Transactional Methods (Requires private wallet key) ------------------ """
 
-    def do_invest(self) -> TransactionReceipt:
-        raise NotImplementedError
+    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
+        :return:
+        """
+        assert stable_token_amt > 0 or asset_token_amt > 0, \
+            "Please provide an investment value for either the stable or asset tokens"
+
+        return self._execute(self.vault.invest(stable_token_amt, asset_token_amt, shareReceiver=self.owner_address))
 
     def do_withdraw(self, shares: int, pct_stable: float = None, strategy: str = "Minimize Trading") -> TransactionReceipt:
         """
@@ -80,6 +93,20 @@ def do_close(self, pct_stable: float = None, strategy: str = "Minimize Trading")
         """
         return self.do_withdraw(shares=self.shares()[0], pct_stable=pct_stable, strategy=strategy)
 
+    def do_approve_deposit_token(self, token: Union[BEP20Token, str], amount: int = None) -> TransactionReceipt:
+        """
+        Approves the given token for deposit into an Automated Vault.
+
+        :param token: Optional - either the BEP20Token object, or the token address (str)
+        :param amount: The amount of token to approve, default = maximum
+        """
+        if type(token) != BEP20Token:
+            token = BEP20Token(token)
+
+        func_call = token.prepare_approve(self.address, amount)
+        return self._execute(func_call)
+
+
     """ ---------------- Informational Methods (Private wallet key not required) ---------------- """
 
     def get_vault_summary(self, position_key: str = None) -> AttrDict:
@@ -214,7 +241,7 @@ def _execute(self, function_call: web3.contract.ContractFunction) -> Transaction
             'gasPrice': 5000000000,
             'nonce': self.w3_provider.eth.get_transaction_count(self.owner_address),
         })
-        print(txn)
+        # print(txn)
 
         signed_txn = self.w3_provider.eth.account.sign_transaction(
             txn, private_key=self.owner_key
@@ -278,7 +305,7 @@ 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)