TradingPortfolio

29 nov 2021

Library "TradingPortfolio"
Simple functions for portfolio management. A portfolio is essentially
a float array with 3 positions [token, fiat, retained fiat] that gets passed around
into these functions that ensure it gets properly updated as trading ensues.

An example usage:

import hugodanielcom/TradingPortfolio/XXXX as portfolio
var float[] my_portfolio = portfolio.init(0.0, strategy.initial_capital) // Initialize the portfolio with the strategy capital
if close < 10.0
portfolio.buy(my_portfolio, 10.0, close) // Buy when the close is below 10.0
plot(portfolio.total(my_portfolio), title = "Total portfolio value")


get_balance(portfolio) Gets the number of tokens and fiat available in the supplied portfolio.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
  Returns: The tokens and fiat in a tuple [tokens, fiat]

set_balance(portfolio, new_crypto, new_fiat) Sets the portfolio number of tokens and fiat amounts. This function overrides the current values in the portfolio and sets the provided ones as the new portfolio.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    new_crypto: The new amount of tokens in the portfolio.
    new_fiat: The new amount of fiat in the portfolio
  Returns: The tokens and fiat in a tuple [tokens, fiat]

init(crypto, fiat) This function returns a clean portfolio. Start by calling this function and pass its return value as an argument to the other functions in this library.
  Parameters:
    crypto: The initial amount of tokens in the portfolio (defaults to 0.0).
    fiat: The initial amount of fiat in the portfolio (defaults to 0.0).
  Returns: The portfolio (a float[])

crypto(portfolio) Gets the number of tokens in the portfolio
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
  Returns: The amount of tokens in the portfolio

fiat(portfolio) Gets the fiat in the portfolio
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
  Returns: The amount of fiat in the portfolio

retained(portfolio) Gets the amount of reatined fiat in the portfolio. Retained fiat is not considered as part of the balance when buying/selling, but it is considered as part of the total of the portfolio.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
  Returns: The amount of retained fiat in the portfolio

retain(portfolio, fiat_to_retain) Sets the amount of fiat to retain. It removes the amount from the current fiat in the portfolio and marks it as retained.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    fiat_to_retain: The amount of fiat to remove and mark as retained.
  Returns: void

total(portfolio, token_value) Calculates the total fiat value of the portfolio. It multiplies the amount of tokens by the supplied value and adds to the result the current fiat and retained amount.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    token_value: The fiat value of a unit (1) of token
  Returns: A float that corresponds to the total fiat value of the portfolio (retained amount included)

ratio(portfolio, token_value) Calculates the ratio of tokens / fiat. The retained amount of fiat is not considered, only the active fiat being considered for trading.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    token_value: The fiat value of a unit (1) of token
  Returns: A float between 1.0 and 0.0 that corresponds to the portfolio ratio of token / fiat (i.e. 0.6 corresponds to a portfolio whose value is made by 60% tokens and 40% fiat)

can_buy(portfolio, amount, token_value) Asserts that there is enough balance to buy the requested amount of tokens.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    amount: The amount of tokens to assert that can be bought
    token_value: The fiat value of a unit (1) of token
  Returns: A boolean value, true if there is capacity to buy the amount of tokens provided.

can_sell(portfolio, amount) Asserts that there is enough token balance to sell the requested amount of tokens.
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    amount: The amount of tokens to assert that can be sold
  Returns: A boolean value, true if there is capacity to sold the amount of tokens provided.

buy(portfolio, amount, token_value) Adjusts the portfolio state to perform the equivalent of a buy operation (as in, buy the requested amount of tokens at the provided value and set the portfolio accordingly).
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    amount: The amount of tokens to buy
    token_value: The fiat value of a unit (1) of token
  Returns: A boolean value, true the requested amount of tokens was "bought" and the portfolio updated. False if nothing was changed.

sell(portfolio, amount, token_value) Adjusts the portfolio state to perform the equivalent of a sell operation (as in, sell the requested amount of tokens at the provided value and set the portfolio accordingly).
  Parameters:
    portfolio: A portfolio float[] array as created by the `init()` function.
    amount: The amount of tokens to sell
    token_value: The fiat value of a unit (1) of token
  Returns: A boolean value, true the requested amount of tokens was "sold" and the portfolio updated. False if nothing was changed.