Tinyman consists of two main components: Tinyman protocol and Tinyman platform. **Tinyman Protocol** is a smart contract set that operates as an Automated Market-Maker on the Algorand blockchain. **Tinyman Platform** is the web interface that enables users to interact with the Tinyman protocol through the tinyman.org domain. ## Tinyman Protocol Tinyman is a non-custodian decentralized exchange on Algorand that works with the Automated Market Maker(AMM) approach, specifically with the Constant Product Formula. This model is considered more suitable for trading on blockchain thanks to its capability to provide liquidity at all times. To read more about the differences between AMM and the order book mode, please refer to LINK. Tinyman AMM v2 protocol was developed and deployed by the Tinyman team on the Algorand blockchain. Tinyman [contracts](/contracts) are written in [Tealish](https://github.com/tinymanorg/tealish) for AVM V7. The Tinyman development team chose Algorand as the foundation for their project due to its compatibility with Tinyman's values and advanced technological capabilities. Algorand's commitment to scalability, security, and decentralization, as well as its ability to handle a high volume of transactions efficiently, made it an ideal choice for the team. ## Tinyman Platform Facilitating on-chain interactions for Tinyman users, the Tinyman platform is comprised of a web app that runs on [tinyman.org](https://tinyman.org) domain and its additional tools such as: * Tinyman protocol * [SDKs](/v2-integration/official-sdks) * Widgets * Tealish * ASA icons platform on [asa-list.tinyman.org](https://asa-list.tinyman.org) * Social Media Channels All components of the Tinyman platform are managed by the Tinyman team.\
## Tinyman Core Principles The design of the Tinyman AMM v2 protocol is based on the following principles: **Open-source:** The Tinyman AMM v2 protocol is open-source, meaning that the entire codebase is available for review by anyone interested in trading on or adding funds to the protocol. This transparency allows all users to validate the operating system, whether they are interacting directly with the smart contracts or using the Tinyman platform. We encourage all users to review the codebase and related documents to ensure complete understanding and confidence in the system. **Decentralized:** Decentralization is a core principle of Tinyman. The platform has no control over the funds that users add and cannot access any of the assets in pools. All assets are held in the contracts deployed on the decentralized Algorand blockchain, ensuring that the system is fully decentralized and not subject to the control of any single entity. **Permissionless:** Core Tinyman functionalities can be initiated by any Algorand address, granted the contract's task requirements are met. During any stage of these operations, no Algorand address or entity, including Tinyman itself, can disable access or revert transactions. **Immutable:** Tinyman protocols, rules, and parameters are fixed and cannot be modified once deployed on the blockchain. The use of immutability in Tinyman helps to ensure the integrity and security of the system, as it prevents any unauthorized changes or tampering with the system's functioning. # Protocol Specification Tinyman AMM V2 is a Constant Product Market Maker. It is mathematically similar to Tinyman V1 which in turn was modeled on Uniswap V2. The contract and protocol design for Tinyman AMM V2 is significantly different from V1 as it uses more recent features of the Algorand Virtual Machine. {% content-ref url="/pages/pVna3G3NTPShGBCeoAZx" %} [Pool](/protocol-specification/pool) {% endcontent-ref %} {% content-ref url="/pages/S0OxRQn6f19zMXQqTjoy" %} [Swap](/protocol-specification/swap) {% endcontent-ref %} {% content-ref url="/pages/3ayJCioT4SAnBhcjo6kv" %} [Fees](/protocol-specification/fees) {% endcontent-ref %} {% content-ref url="/pages/xvPYQRY3M8WXZMEtpygG" %} [Flash Loan](/protocol-specification/flash-loan) {% endcontent-ref %} {% content-ref url="/pages/ylc9j1pHX69GiiCV5ZR8" %} [Flash Swap](/protocol-specification/flash-swap) {% endcontent-ref %} {% content-ref url="/pages/slwrdmGbjPZhhrEF0lpD" %} [Additional Notes](/protocol-specification/additional-notes) {% endcontent-ref %} # Pool An AMM based decentralized exchange is made up of a number of ‘Pools’, with one pool per asset pair. Users can swap assets through these pools by sending some of one asset and receiving the equivalent value of the other asset. The funds in the pools are owned by ‘Liquidity Providers’. Each liquidity provider contributes and retains ownership of a share of the pool’s funds. The liquidity provider receives ‘Pool Tokens’ to represent their share of the pool. They can reclaim their assets at any time by returning the pool tokens. Each Pool is an Algorand Account. The accounts hold the assets and state related to the pool. A single stateful Algorand Application contains all the logic that controls the asset transfers and state management of the pools. Each Pool has a number of local state variables which are updated during every operation. The asset reserves (liquidity) of the pool are tracked in the local state and not determined dynamically from the account balances. This means that ‘donations’ to the pool or Algo making up the minimum balance do not contribute to the asset reserves. If assets are transferred to the pool account with transactions that are not part of a documented group the assets will be lost. These assets are called “extra” and are only transferable to the fee collector. They will not affect the liquidity of the pool or the shares of the liquidity providers. {% content-ref url="/pages/5NUIGQ79qZmcfGOONpKW" %} [Pool Creation](/protocol-specification/pool/pool-creation) {% endcontent-ref %} {% content-ref url="/pages/LVpghIKStlSOc0Iq288Q" %} [Adding Liquidity](/protocol-specification/pool/adding-liquidity) {% endcontent-ref %} {% content-ref url="/pages/dRd1KyIqrjQiYuOpWthy" %} [Removing Liquidity](/protocol-specification/pool/removing-liquidity) {% endcontent-ref %} # Pool Creation Pools are created with two separate operations; Bootstrap & Add Initial Liquidity. A pool is created as a [Smart Signature Contract Account](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/smartsigs/modes/#contract-account). The Smart Signature is derived from a standard template but it is unique per pool because it contains the ids of the pair of assets. ## Bootstrap The account is turned into a pool by issuing an Application Call transaction to the AMM app. This transaction opts the account into the app and also rekeys the contract account to the App account. \ As a contract account, this transaction must be signed by the associated Smart Signature. After this transaction is confirmed the Smart Signature no longer has authority over the account as it has been rekeyed. Instead, the AMM App has full authority over the pool account. During the Bootstrap operation, the app creates the Pool Token asset and transfers the total supply to the pool account. These are done with Inner Transactions. All pool token assets are created by the app account so that there is a single well-known creator address of Tinyman AMM V2 pool tokens. The Reserve address of the pool token asset is set to the pool address.\ \ The Bootstrap operation requires some Algo to cover the minimum balances for the pool account (Formula I), asset creation (100000 micro Algo), and transaction fees. This Algo must be supplied to the pool prior to the Bootstrap Application Call. It will usually be in the same group but this is not required. [Transaction Details for bootstrap](/v2-integration/protocol-methods/bootstrap) # Adding Liquidity Funds are added to the pool with Asset Transfer transactions together with an Application Call. Pool tokens are sent to the user by the pool using an inner transaction. There are two methods for adding liquidity. ## **Adding Initial Liquidity** If the pool has no liquidity then the first user to add liquidity is free to set the ratio between the two assets. If the pool has any liquidity this transaction fails and the user should use the Adding Subsequent Liquidity method. The formula to determine the number of pool tokens for initial liquidity is [Formula II.A](https://docs.tinyman.org/protocol-specification/pool/pages/RArypJMatkCdksZvFhuW#a.-adding-initial-liquidity). [Transaction Details for add\_initial\_liquidity](/v2-integration/protocol-methods/add-initial-liquidity) ## **Adding Subsequent Liquidity** The formula to determine the number of pool tokens for subsequent liquidity is [Formula II.B](https://docs.tinyman.org/protocol-specification/pool/pages/RArypJMatkCdksZvFhuW#b.-adding-subsequent-liquidity). The protocol supports adding liquidity in a flexible way so that the user does not have to provide amounts of assets at exactly the current pool ratio. Instead, it supports a continuum between liquidity at exactly the current ratio and all liquidity in a single asset. This is achieved by internal implicit swaps where necessary. A swap fee is charged on the amount that must be swapped. The value of this fee is reduced from the pool tokens output. If the user does provide liquidity at exactly the current ratio then there will be no swap fee and pool tokens will be output for the entirety of the liquidity provided. A special case of providing liquidity in a flexible way is providing liquidity in only one single asset. In this case the user does not need to transfer a zero amount but can instead omit the transfer transaction entirely. When providing liquidity at a ratio different from the current pool ratio the user must be aware of the loss of value due to both price impact and fees of the implicit swap. The user can pre-calculate the expected value of pool tokens accounting for these and provide the min\_output parameter to ensure the amount of pool tokens output matches their expectations. This can protect the user from sudden price changes between the time of signing and executing the transaction. ### **Adding liquidity with two assets** When adding liquidity with two assets two transfer transactions are required in addition to the application call transaction. The 2nd application arg must be the byte string “flexible” in this case. ### **Adding liquidity with a single asset** When adding liquidity with one asset one transfer transaction is required in addition to the application call transaction. The 2nd application arg must be the byte string “single” in this case. [Transaction Details for add\_liquidity](/v2-integration/protocol-methods/add-subsequent-liquidity) # Removing Liquidity Liquidity providers can remove funds from the pool with an Asset Transfer of pool tokens and an Application Call. Amounts of each asset are sent to the user by the pool using two inner transactions. The amount of each asset received is proportional to the pool tokens returned and dependent on the current ratio of the pool. See [Formula III.A](https://docs.tinyman.org/protocol-specification/pool/pages/RArypJMatkCdksZvFhuW#a.-multiple-asset-out). ## **Removing liquidity as a single asset** The protocol supports removing liquidity as a single asset from pools by combining removing liquidity with an internal swap calculation. The entirety of one side of the liquidity will be swapped into the other asset. A swap fee is charged on this amount and deducted from the output. See [Formula III.B](https://docs.tinyman.org/protocol-specification/pool/pages/RArypJMatkCdksZvFhuW#b.-single-asset-out). When using this convenience method the user must be aware of the loss of value due to both price impact and fees of the implicit swap. The user can pre-calculate the expected output accounting for these and provide the min\_output parameter to ensure the amount of output matches their expectations. This can protect the user from sudden price changes between the time of signing and executing the transaction. # Swap Swaps are made with an Asset Transfer transaction together with an Application Call. An amount of the other asset is sent to the user by the pool using an inner transaction. The type of swap may be either fixed-input or fixed-output. If the type is fixed-output an extra inner transaction is sent to return any change from the input amount to the user (see below). A fixed-output swap has a higher transaction fee because it requires one extra inner transaction. A swap fee is charged on all swaps. The fee is set per pool as basis points. This fee is deducted from the input amount before applying the swap formula to calculate the output. The formulae for fixed-input and fixed-output swaps are described in [Formula IV.A & IV.B](https://docs.tinyman.org/protocol-specification/pages/RArypJMatkCdksZvFhuW#iv.-swapping) respectively. ## **Slippage Tolerance** Swaps have slippage tolerance to allow for changes to the exchange rate between the time the swap was prepared and the swap was executed. For a fixed-input swap, a minimum output amount is included in the Application Call arguments. If the calculated output amount is less than this amount the swap will fail. For a fixed-output swap, the slippage tolerance is included in the input amount and the exact output amount is specified in the arguments. If the calculated input amount required to achieve the target output amount is less than the provided input amount the swap fails. If it is greater then the change is returned to the user by an inner transaction. [Transaction Details for swap](/v2-integration/protocol-methods/swap) # Fees Tinyman charges fees on swaps, loans and internal swap operations. A portion of this fee is allocated to the protocol (Tinyman) and the remainder is allocated to the liquidity providers by adding to the pool reserves. The fee rate and the protocol fee fraction portion are configurable parameters on each pool. The total fee rate can be set in the range from 0.01% to 1% (1 to 100 basis points), the protocol fee fraction can be set as 1/n in the range from 1/3 to 1/10. The default fee rate is %0.3 and protocol fee fraction is 1/6 (0.05% of total input). These defaults are the same as the Tinyman V1. Pools have a single fee setting and the same rate is applied to all swap, loan and internal swap operations. The protocol fees accumulate in both assets. They can be claimed in full at any time by any user that issues an appropriate Application Call. The accumulated amounts of both assets are transferred by inner transactions to the fee collector. The fee collector is specified by a global state variable of the App (fee\_collector). The fee\_collector can be set by the global fee\_manager address. Fee parameters can be set by the global fee\_setter address. The fee\_setter address can be set by the global fee\_manager address. The fee\_manager address can be set by the current fee\_manager address. ## **Swap Fees** Swap fees are collected from the input assets. **Examples:** **A. Fixed Input** If the input amount is 5000A, fee is 5000\*fee rate AssetA. If the fee rate is 0.3%, total fee is 15 AssetA, pooler fee is 13 AssetA and protocol fee is 2 AssetA. If the input amount is 20000A, fee is 20000A\*fee rate AssetA. If the fee rate is 0.3%, total fee is 60 AssetA and protocol fee is 10 AssetA. \ **B. Fixed Output** In this method, the extra amount added because of the slippage is returned back to the users with an inner transaction. The input amount is calculated by subtracting the extra amount from the transferred amount and the fee is applied to this amount. If the transferred amount is 1005A, and extra amount is 5, the fee is applied to 1000 AssetA. ## **Flash Loan Fees** The fee rate is the same with the swap fee rate of the pool. It is applied to the loan amounts. The repayment must be equal or greater than the total of loan amount and fee. **Examples:** **A. Loan single asset** If the loan is 3000 AssetA, fee is 3000\*fee rate AssetA. It is 9 AssetA if the fee rate is 0.3%, so minimum repayment amount is 3009 AssetA. **B. Loan multiple assets** If the loan is 3000 AssetA and 5000 AssetB, fee is 3000\*fee rate AssetA and 5000\*fee rate AssetB. The minimum repayment amounts are 3009 AssetA and 5015 AssetB, if the fee rate is 0.3%. ## **Flash Swap Fees** The fee calculation is the same as swap. The same swap fee rate is applied to input amounts. **Examples:** **A. Pay in single asset** If the payment is 3000 AssetA, the fee is 3000\*fee rate AssetA. **B. Pay in multiple assets** If the payment is 1000 AssetA and 2000 AssetB, the fees are 1000\*fee rate AssetA and 2000\*fee rate AssetB. ## **Swap Router Fees** The swap router doesn’t charge additional fees. Tinyman AMM V2 fee policy applies to swaps. Using the swap router requires 3 more transactions than 2 swaps and 6 more transactions than a single swap. API is aware of this difference and makes suggestions accordingly. The total transaction fee is converted from Algo to input asset amount using the price information, calculated by pool reserves. However, if this conversion is impossible, the transaction fee isn’t included in the calculation. All transaction fees must be paid by the sender of any of the outer transactions. The inner transaction fees are not paid by the swap router app account. # Flash Loan Flash loan allows users to borrow single or multiple assets with no collateral with the condition of paying it back within the same transaction group. It allows advanced users to create a custom transaction group to generate a profit without an initial capital. Flash loan requires two application calls. The first one is for requesting a loan from the pool and the second one is for verifying the repayment. The repayments must be made in the same asset. The repayment amount should cover the loan amount and fee. The swap fee rate applies to loan amounts. With the first app call users specify the amount of loans in terms of asset 1 and asset 2 and group index difference between first and second application calls. Loan amounts cannot exceed the pool reserves. Requested assets are transferred to the user using inner transactions. Verification calls check the repayment amounts. The transaction fails if they don’t cover the loan amount and fee. Repayments should be placed just before the verification app call and the contract checks the transfer amounts. Any extra payments are considered donations to pools. Flash loan transactions can appear anywhere within a transaction group and a single group may contain multiple flash loans. Users can use the same pool freely between the two application calls and do a swap. Unlike Flash Swap (below) usage of the pool is not restricted. # Flash Swap Flash swap has similarities to swap and flash loan. It is designed for advanced users. They can create a custom transaction group, borrow assets from the pool with an application call and make a profit (arbitrage, collateral swap etc.), pay it back within the same transaction group and make another application call to verify the payment. If the payment amount is insufficient all transactions in the atomic group fail. It allows users to generate profit without risk and collateral. Unlike the flash loan, users are free to pay back in both assets as long as the final pool invariant increases and covers the fee. This can allow for more efficient transactions in some scenarios compared to the Flash Loan. In the regular swap, the user transfers input assets to the pool first and then receives the output assets. Flash swap allows users to change this order. They can receive the output assets first, and use these assets to make a profit, and transfer input assets to the pool. In this scenario, the applied fee is exactly the same as the swap and the fee is applied to input assets and collected in terms of input assets. If users receive 500 AssetA and send 1000 AssetB, fee amount will be 3 AssetB with default fee rate 0.3% (1000\*0.003=3). Additionally, similar to flash loan, flash swap allows users to borrow a single asset or both assets of the pool. Unlike the flash loan, users are free to pay back in both assets as long as the final pool invariant increases and covers the fee. Fees are applied to all input assets. If the repayment is made as 1000 AssetA and 2000 AssetB, the fee is collected in both assets as 3 AssetA and 6 AssetB. If the repayment is made in a single asset such as 3000 AssetB, the fee is 9 AssetB. With the first app call, users specify the amount of loans in terms of asset 1 and asset 2 and group index difference between first and second (verification) application calls. Loan amounts cannot exceed the pool reserves. Requested assets are transferred to the user using inner transactions. The verification calls check the initial and final invariant. Repayments must be made between two app calls. The app checks the final balance to determine the paid amounts and doesn’t check a particular transfer so users can make multiple inner and outer transactions. Any extra payments are considered as donations to the pools. The pool is locked between the two application calls and no operation (swap, add & remove liquidity etc.) is allowed. These operations can be used before or after the flash swap in the same transaction group however. # Additional Notes ## **Donations** Any assets that are in the pool accounts but not part of the reserves, protocol fees or minimum Algo balance are claimable to the fee\_collector address. Algorand Participation Rewards that accumulate in accounts holding Algo are considered donations to the pool and do not contribute to the pool reserves in AMM V2 (unlike V1). As of [2022/05/14 the Participation Rewards program is finished](https://algorand.foundation/faq#participation-rewards-) and no further rewards are planned to be distributed by this mechanism. In the event that this mechanism is re-enabled in the future the pool accounts would accumulate rewards that would be claimable by the fee\_collector address. It would be up to the protocols managers (development team or DAO) to decide how those rewards should be used. ## **Algo Pools** The AMM V2 protocol supports ASA-Algo pools just like V1. All references to ‘Assets’ in this document equally apply to Algo. The transaction details differ slightly whenever Algo is involved as Payment transactions are used instead of Asset Transfer. ## **Transaction Fees** All transaction fees must be paid by the sender of any of the outer transactions of an operation. The inner transaction fees cannot be paid by the pool account and app account. ## **Users** This document refers to ‘Users’ as the senders of assets and transactions to the pool and receivers of assets from the pool. The protocol does not place any restriction on the type of account that initiates a pool operation and therefore supports operations made by application accounts in the same way as regular accounts. Additionally there is no requirement that the sender of all transactions in an operation group is the same account. The receiver of assets (Pool Tokens, swapped assets, removed assets, change, etc) is always the sender of the Application Call. ## **Transaction Groups & Composability** Each operation requires multiple transactions that must be part of the same atomic group. The exact indices of the transactions within the group or the size of the group is not specified by the protocol however so it is possible to create groups containing additional transactions before or after a swap for example. However relative indexing is used so the relative location of transactions within the group is specified and must be adhered to. Operation transaction groups may also be created as inner transactions from within another Application. The only exception to this is the Bootstrap operation for creating pools, which requires a Smart Signature that cannot be used from an inner transaction. ## **Pool Discovery** Clients can discover the existence of pools in either of two ways; 1. Every pool account is opted into the Tinyman App. Any account opted into this app is a valid pool. A list of pool accounts can therefore be retrieved from an Algorand Indexer or other block follower. The [local state](/v2-integration/state-data#local-state-pool) of these accounts gives the details of the pool. 2. The pool account address can be computed from the LogicSig template. # FAQ {% content-ref url="/pages/mdAOSSqQnO7Xh2CfAR77" %} [Migration FAQ](/faq/migration-faq) {% endcontent-ref %} ## Introduction ### What is Tinyman? Tinyman is a decentralized protocol on the Algorand blockchain that enables users to trade or swap Assets at market rates. The web app ([app.tinyman.org](http://app.tinyman.org)) is a visual interface for interacting with a set of smart contracts deployed to the Algorand blockchain. ### What are Tinyman’s design principles? Tinyman protocol is open-source, decentralized, permissionless, persistent, non-custodian, and immutable (non-upgradable). ### What is Algorand and ALGO? Algorand is a blockchain launched in 2018 to solve the “blockchain-trilemma” with a fast, secure, decentralized and scalable framework built with PPoS (Pure Proof of Stake) consensus mechanism. Tinyman V2 smart contracts are deployed on Algorand blockhain.\ ALGO is the native currency of the Algorand blockchain. ### What is Algorand Standard Asset? Algorand Standard Assets (ASA) provide a standardized, Layer-1 mechanism to represent any type of Asset on the Algorand blockchain. Only ASAs and ALGO are tradable assets on Tinyman. ### How does Tinyman work? Tinyman protocol works with smart contracts that allow users to swap assets, provide liquidity and borrow/pay flash loans. Tinyman smart contracts are built with the Automated Market Maker(AMM) mechanism, specifically the Constant Product Formula. ### What is an AMM - Automated Market Maker? Automated market makers (AMM) are a type of decentralized exchange (DEX) that pool liquidity from users and allow digital assets to be traded automatically and without permission. AMMs use smart contracts to provide deep liquidity, low transaction fees, and uninterrupted access for all users. They offer a highly efficient and reliable way to trade digital assets on the blockchain. ### Who can use Tinyman? Any individual or organization interested in trading or supplying liquidity on DeFi can use Tinyman. ### How can users interact with Tinyman? Users can interact with Tinyman pools using either of three methods: 1. Manually/programmatically creating, signing and submitting a set of transactions that satisfy the smart contracts 2. Signing and submitting the transactions created by the helper functions of the Tinyman Python SDK and Tinyman JS SDK. 3. Using the web app to do the swap, signing the transactions with a wallet browser extension. ### How can a user connect to Tinyman? Which wallets are available currently? Users can access Tinyman using their Algorand wallet accounts. Currently: * [Pera Wallet,](https://perawallet.app/) * [MyAlgoWallet,](https://wallet.myalgo.com/access) * [Exodus Wallet,](https://www.exodus.com/) * [Defly,](https://defly.app/) * [Fireblocks](https://www.fireblocks.com/) are supported on the Tinyman web app. In addition, Tinyman supports the * Pera Connect, * Wallet Connect, * AlgoSigner connection modals. For the latest wallet list, you may check the “Connect to a wallet” button on app.tinyman.org Tinyman protocol and platform can operate with Ledger Wallets too. These users are encouraged to follow the latest updates to their ledgers as older versions can frequently experience issues with Tinyman. You may follow Ledger’s page for the latest updates:
# Fees Current Tinyman and Algorand fees incurred for each function ## Swapping A fee of 0.3% is added to all swaps. * 5/6ths of this fee (0.25%) is paid to Poolers * 1/6th of this fee (0.05%) is paid to the protocol (Tinyman Treasury) **Fixed input swap:**\ Algorand transaction fees: 4 \* min fee = 0.004 Algo **Fixed output swap:**\ Algorand transaction fees: 5 \* min fee = 0.005 Algo ## Adding & Removing Liquidity There are no extra fees charged by Tinyman for Minting or Burning. **Adding Initial liquidity:**\ Algorand transaction fees: 4 \* min fee = 0.004 Algo **Adding subsequent liquidity for flexible:**\ Algorand transaction fees: 5 \* min fee = 0.005 Algo **Adding subsequent liquidity for single asset:**\ Algorand transaction fees: 4 \* min fee = 0.004 Algo **Removing liquidity for both multiple assets and single asset:**\ Algorand transaction fees: 4 \* min fee = 0.004 Algo ## Pool Creation (Bootstrap) There are no extra fees charged by Tinyman for Pool Creation. There are additional Algo costs to cover the minimum balance required for the Pool account:\ ASA-ASA Pool: 1.043 Algo\ ASA-Algo Pool: 0.943 Algo Algorand transaction fees: \ ASA-ASA Pool: 7 \* min fee = 0.007 Algo\ ASA-Algo Pool: 6 \* min fee = 0.006 Algo **Total costs for Pool Creation:**\ ASA-ASA Pool: 1.05 Algo\ ASA-Algo Pool: 0.949 Algo ## Flash Loan A fee of 0.3% is added to flash loans. * 5/6ths of this fee (0.25%) is paid to Poolers * 1/6th of this fee (0.05%) is paid to the protocol (Tinyman Treasury) Algorand transaction fees: 4 \* min fee = 0.004 Algo ## Flash Swaps A fee of 0.3% is added to flash loans. * 5/6ths of this fee (0.25%) is paid to Poolers * 1/6th of this fee (0.05%) is paid to the protocol (Tinyman Treasury) Algorand transaction fees: 4 \* min fee = 0.004 Algo ## Variable Fees Tinyman V2 is introducing new governance functionality that will allow liquidity providers (LPs) to set the percentage of fees they want to collect for their pool up to a maximum of 5%. The current fee structure will remain unchanged until the governance feature is activated and put up for a vote. At that point, LPs will be able to propose changes to the fee structure through the governance process. Until then, the fee structure will continue as is. # Permissioned Methods Manager Functionality The protocol includes a number of permissioned methods. These are methods that can only be called by specific addresses. In this section we describe what these methods can and cannot do. {% content-ref url="/pages/tT8M0vLpxjsdubOEoBTq" %} [Roles](/permissioned-methods/roles) {% endcontent-ref %} {% content-ref url="/pages/kwaP6mx96Fq1owwOwfQ8" %} [Methods](/permissioned-methods/methods) {% endcontent-ref %} {% content-ref url="/pages/wCK0IKl0CvIWlZMVGJ9q" %} [Related Non-Permissioned Methods](/permissioned-methods/related-non-permissioned-methods) {% endcontent-ref %} # Roles The fee\_manager, fee\_setter and fee\_collector are distinct roles in the protocol. Each of these are mutable. ## **Fee Collector** The fee\_collector is expected to be a single signature account used by an off-chain system to actively manage the accumulated protocol fees and extras. There is a not insignificant chance that this account could become compromised so in order to protect future earnings of the protocol this account must be replaceable by a higher authority - the fee\_manager. ## **Fee Setter** The fee\_setter is expected to initially be a multisig account but over time it may transition to a system account for an automated process or a contract account governed by voting. To facilitate these changes of use and to protect against compromised keys the fee\_setter is configurable only by the fee\_manager. ## **Fee Manager** The fee\_manager is expected to be a multisig account initially, and potentially a contract account governed by voting in the future. It is assumed that this account is never compromised. The protocol requires that the role can be transferred between accounts. The fee\_manager, fee\_setter and fee\_collector roles are all initialized to the creator address of the application. This is assumed to be a multisig. These roles are global - they cannot be defined separately for different pools. There are no other roles or management capabilities defined in the protocol. There is no capability to pause/lock/close/empty any pool and there is no capability to upgrade the application.
# Methods ## **Set Fee Collector** This method is callable by the fee\_manager. It updates the global state value of fee\_collector to a new address. ## **Set Fee Setter** This method is callable by the fee\_manager. It updates the global state value of fee\_setter to a new address. ## **Set Fee** This method is callable by the fee\_setter. It updates the pool local state values of total\_fee\_share and protocol\_fee\_ratio to new values. The protocol enforces limits on the allowable values for each of these. This allows the swap fees of each pool to vary over time without moving or fragmenting liquidity. It is intended that these changes will be made based on sound market analysis for the benefit of the poolers and protocol. ## **Set Fee Manager** This method is callable by the fee\_manager. It updates the global state value of fee\_manager to a new address. # Related Non-Permissioned Methods ## **Claim Fees** This method is callable by any address. It transfers all accumulated protocol fees to the fee\_collector account. This operation does not affect the liquidity of the pool. ## **Claim Extra** This method is callable by any address. It allows transferring the extra asset and Algo amounts from application or pool accounts to the fee\_collector account. This operation does not affect the liquidity of the pool. “extra amounts” are defined as amounts held in the pool account that are not part of the asset reserves, protocol fees or minimum balance requirement. # Formulae ## I. Pool Minimum Balance Ref: [Minimum balance requirement for a smart contract](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#minimum-balance-requirement-for-a-smart-contract) Local state uint count: 12 Local state byte slice count: 2 ### A. ASA-ASA Pool 100000 (Accounts on Algorand require a minimum balance of 100,000 micro Algo)\ \+ 100000 ASA 1 (Asset Optin)\ \+ 100000 ASA 2 (Asset Optin)\ \+ 100000 Pool Token (Asset Optin)\ \+ 542000 App Optin (100000 + (25000+3500)\*12 + (25000+25000)\*2)\ \= 942000 micro Algo ### B. ASA-ALGO Pool 100000 (Accounts on Algorand require a minimum balance of 100,000 micro Algo)\ \+ 100000 ASA 1 (Asset Optin)\ \+ 100,000 ASA 2 (Asset Optin)\ \+ 100000 Pool Token (Asset Optin)\ \+ 542000 App Optin (100000 + (25000+3500)\*12 + (25000+25000)\*2)\ \= 842000 micro Algo ## II. Adding Liquidity ### **A. Adding Initial Liquidity** Issued Pool Tokens = floor(sqrt(Asset1 Amount \* Asset2 Amount))\ Locked Pool Tokens= 1000\ Pool Token Output = Issued Pool Tokens - Locked Pool Tokens ### **B. Adding Subsequent Liquidity** The same formula applies to single and flexible modes. Old K = Asset1 Reserves \* Asset2 Reserves\ New K = (Asset1 Reserves + Asset1 Amount) \* (Asset2 Reserves + Asset2 Amount)\ R = sqrt(Old K) / Issued Pool Tokens\ New Issued Pool Tokens = sqrt(New K) / R\ New Issued Pool Tokens = sqrt(New K) / ( sqrt(Old K) / Issued Pool Tokens)\ New Issued Pool Tokens = sqrt((New K \* Issued Pool Tokens\* Issued Pool Tokens) / Old K) Pool Tokens Out = New Issued Pool Tokens - Old Issued Pool Tokens\ New Asset1 Reserves = Old Asset1 Reserves + Asset1 Amount\ New Asset2 Reserves = Old Asset1 Reserves + Asset2 Amount Calculated Asset1 Amount = floor((Pool Tokens Out \* New Asset1 Reserves) / New Issued Pool Tokens)\ Calculated Asset2 Amount =floor((Pool Tokens Out \*New Asset2 Reserves) / New Issued Pool Tokens)\ Asset1 Swap Amount = Asset1 Amount - Calculated Asset1 Amount\ Asset2 Swap Amount = Asset2 Amount - Calculated Asset2 Amount\ Swap Amount = Max(Asset1 Swap Amount, Asset2 Swap Amount) Total Fee Amount = (Swap Amount \* Total Fee Share) / (10000 - Total Fee Share)\ Protocol Fee Amount = Total Fee Amount / Protocol Fee Ratio\ Poolers Fee Amount = Total Fee Amount - Protocol Fee Amount Asset1 Swap Amount > Asset2 Swap Amount:\ Fee As Pool Tokens = (Total Fee Amount \* New Issued Pool Tokens) / (New Asset1 Reserves \* 2)\ New Asset1 Reserves = New Asset1 Reserves - Protocol Fee Amount\ Pool Tokens Out = Pool Tokens Out - Fee As Pool Tokens Asset2 Swap Amount > Asset1 Swap Amount:\ Fee As Pool Tokens = (Total Fee Amount \* New Issued Pool Tokens) / (New Asset2 Reserves \* 2)\ New Asset2 Reserves = New Asset2 Reserves - Protocol Fee Amount\ Pool Tokens Out = Pool Tokens Out - Fee As Pool Tokens ## III. Removing Liquidity ### **A. Multiple Asset Out** #### a. Remove all circulating pool tokens Issued Pool Tokens == Locked Pool Tokens + Removed Pool Tokens\ Asset1 Output = Asset1 Reserves\ Asset2 Output = Asset2 Reserves #### b. Otherwise Issued Pool Tokens > Locked Pool Tokens + Removed Pool Tokens\ Asset1 Output= floor(Removed Pool Token Amount \* Asset1 Reserves / Issued Pool Tokens)\ Asset2 Output= floor(Removed Pool Token Amount \* Asset2 Reserves / Issued Pool Tokens) ### **B. Single Asset Out** Calculate the Asset1 Output and Asset2 Output as multiple assets out and convert an asset to desired output by doing an internal swap (fixed-input swap). #### a. Asset 1 Out Input Amount = Asset2 Output\ Swap Output = FixedInputSwap(Input Amount)\ Asset1 Output=Asset1 Output + Swap Output\ Asset2 Output=0 #### b. Asset 2 Out Input Amount = Asset1 Output\ Swap Output = FixedInputSwap(Input Amount)\ Asset2 Output=Asset2 Output + Swap Output\ Asset1 Output=0 ## IV. Swapping ### **A. Fixed Input** Total Fee = floor((Input Amount \* Total Fee Share) / 10000)\ Protocol Fee = floor(Total Fee / Protocol Fee Ratio)\ Poolers Fee = Total Fee - Protocol Fee\ Swap Amount = Input Amount - Total Fee\ K = Input Supply \* Output Supply\ Swap Output = Output Supply - (floor(K / (Input Supply + Swap Amount)) + 1) ### **B. Fixed Output** Swap Amount = (floor(K / (Output Supply - Output Amount)) + 1) - Input Supply\ Input Amount = floor((Swap Amount \* 10000) / (10000 - Total Fee Share))\ Total Fee = Input Amount - Swap Amount\ Protocol Fee = floor(Total Fee / Protocol Fee Ratio)\ Poolers Fee = Total Fee - Protocol Fee\ Change = Input Transfer Amount - Input Amount ## V. Flash Loan Applies to both assets. Total Fee = floor((Loan Amount \* Total Fee Share) / 10000)\ Protocol Fee = floor(Total Fee / Protocol Fee Ratio)\ Poolers Fee = Total Fee - Protocol Fee\ Expected Repayment Amount = Loan Amount + Total Fee\ Donation Amount = Repayment Transfer Amount - Expected Repayment Amount ## VI. Flash Swap Applies to both assets. Input Amount= Transfer Amount (Final Balance - Initial Balance) **Note:** The rest is the same with fixed input swap. Total Fee = floor((Input Amount \* Total Fee Share) / 10000)\ Protocol Fee = floor(Total Fee / Protocol Fee Ratio)\ Poolers Fee = Total Fee - Protocol Fee # Disclaimer Your use of the Tinyman protocol involves various risks, including, but not limited to, losses while digital assets are being supplied to the Tinyman protocol and losses due to the fluctuation of prices of tokens in a trading pair or liquidity pool. Before using the Tinyman protocol, you should review the relevant documentation to understand how the Tinyman protocol works. You are responsible for doing your diligence on the risks involved. AS DESCRIBED IN THE TINYMAN PROTOCOL LICENSES, THE TINYMAN PROTOCOL IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND. Although TM Distributed Development Ltd. ( "Tinyman" ) developed much of the initial code for the Tinyman protocol, it does not provide, own, or control the Tinyman protocol, which is run by smart contracts deployed on the Algorand blockchain. Accordingly, no developer or entity involved in creating the Tinyman protocol will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Tinyman protocol, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value. # Contracts Source code on Github:
| TINY Token - Allocations | Share | Amount | Details |
|---|---|---|---|
| 1. Investors | 30.65% | 306,500,00 | 10-12% upfront 1-year cliff 18-month linear vesting |
| 1.1 Seed Round | 25.25% | 258,5M | |
| 1.2 Strategic Round | 4.80% | 48M | |
| 2. Tinyman Protocol | 34.35% | 343,500,000 | 15% upfront 1-year cliff 2-year linear vesting |
| 2.1 Team and Partners | 14.40% | 144M | |
| 2.2 Ecosystem Support Part. | 6.95% | 69,5M | |
| 2.3 Reserve Tinyman Cont. | 13.00% | 130M | |
| 3. Community | 35.00% | 350,000,000 | Airdrop + 4-year linear vesting |
| 3.1 Airdrop | 5.00% | 50M | |
| 3.2 Governance Rewards | 18.00% | 180M | |
| 3.3 Liquidity Mining Rewards | 12.00% | 120M | |
| TOTAL | 100% | 1,000,000,00 |
# Governance Details # Overview
Tinyman Governance Workflow
\
# Governance Vault ## Overview Tinyman Governance Vault is a smart contract that holds and manages the TINY tokens being staked for governance. When a user stakes their TINY tokens, they are transferred to the governance vault contract. The governance vault is responsible for managing the lockup period, participating in governance proposals, and continuous stake rewards. The longer a user stakes their tokens, the more voting power they accumulate. However, there is also a time decay factor. As the unlock period gets closer, the voting power diminishes.
Governance Vault
### Locking Duration: * Users will have pre-defined time period options to lock their tokens to the governance vault. * 1 Month = 4 Weeks (Minimum commitment) * 3 Months = 12 Weeks * 6 Months = 24 Weeks * 1 Year = 52 Weeks * 2 Years = 104 Weeks * 3 Years = 156 Weeks * 4 Years = 208 Weeks (Maximum commitment) * There is no withdrawal during the active lock period. When a user stakes their TINY tokens, they are locked up for the period of their choosing, which can range from 1 month to 4 years. During this time, the user's tokens cannot be transferred or sold, and they are not available for trading. * The governance vault contract tracks the lockup period and prevents users from withdrawing their tokens before it ends. * Once the lockup period has ended, users can withdraw their staked TINY tokens, and they become available for trading. * When users lock TINY tokens, they will be able to see their voting power and estimated governance rewards over time. ### Locking Amount: * There is a minimum limit for locking tokens to the governance vault: 10 TINY * There is no maximum token limit to having a commitment; it is unlimited. * The same rule applies to updating/extending an existing commitment. Users should update their commitment with at least 10 TINY tokens. ### Extending the governance commitment: * When users stake their TINY tokens, they are locked up for a period of time. However, they can update their commits to increase their voting power. * There will be 3 forms of extending the commitment: (Amount x Duration) * Case1: Increasing the amount for the same duration * Case2: The same amount for a longer duration * Case3: Increasing the amount for a longer duration * E.g. Existing Commitment: 1000 TINY x 1-year * Case1 – Updated Amount: 2000 TINY x 1-year * Case2 – Updated Duration: 1000 TINY x 2-year * Case3 – Updated the two: 2000 TINY x 2-year * The minimum limit for locking tokens is also valid for extending the commitment. * Updating the commitment is a unidirectional action, with a positive impact: * There is no withdrawal during the active lock period. * There is no decrease in the locked amount. * There is no shortening of the time duration of the commitment. * When users extend their commitment, the governance system grants them a new level of Tiny Power, increasing their share of the governance rewards and voting power in the governance process. * Updated Power will be valid for the upcoming governance reward cycle. * Additionally, the updated voting power will apply only to future governance proposals, not to any existing or active proposals. ## Tiny Power * TINY Power, is a concept within the Tinyman Governance system. * It is a measure of a user's commitment to the governance process and is determined by the number of tokens committed and the duration of the commitment. (TINY Power = Committed Amount x Commitment Duration) * The TINY Power affects the portion of governance rewards that users receive, as well as increasing their voting power in the governance process. * This incentivizes users to make longer commitments to the governance system, as it allows them to have a greater say in the decision-making process and receive greater rewards. * **Formula**: TINY Power = “Committed Amount / 208 x Remaining Weeks” * The number of tokens to be locked directly increases TINY Power. * The locking duration also directly increases TINY Power. * As the unlock period gets closer, the TINY Power diminishes gradually.
Tiny Power (over time)
\
# Governance Rewards * Staking TINY tokens in the governance vault allows users to earn staking rewards on an ongoing basis. (Stake $TINY, Earn $TINY) * Longer commitments will result in higher TINY Power, which will be rewarded more. * The rewards will be distributed to the governors based on their shares in locked tokens. * These structures are designed to encourage long-term participation in the governance process. * There will be a fixed amount of TINY tokens allocated each week for 4 years to be distributed to governors under this initiative. * 1st Year – 1000K TINY Token per Week * 2nd Year – 900K TINY Token per Week * 3rd Year – 700K TINY Token per Week * Tokens will be unlocked in weekly cycles * Users will receive the rewards based on their share of total locked tokens in the Governance vault. (TINY Power) * Rewards are distributed daily and can be claimed on a weekly basis. * Governors can claim the Governance Rewards they are qualified for at any time. * When users update their commitment in the governance vault, they will start earning staking rewards based on the new commitment from the next cycle, typically within a day.
| TINY Rewards | Share | Total Amount | Monthly Allocation |
| Year 1 | 27.00% | 32,400,000.00 | 2,700,000.00 |
| Year 2 | 24.00% | 28,800,000.00 | 2,400,000.00 |
| Year 3 | 21.00% | 25,200,000.00 | 2,100,000.00 |
| Year 4 | 18.00% | 21,600,000.00 | 1,800,000.00 |
| Later | 10.00% | 12,000,000.00 | |
| TOTAL | 100.00% | 120,000,000.00 |
# Protocol Methods This section describes the transaction groups for each method of the protocol. Where more than one transaction is required they must appear in an atomic group. The exact indices within the group are not important unless specified. However, the relative positions of transactions for each method are important. The transaction order may not change and no other transactions may appear between the transactions of each method. Where user\_address is specified the same address must be used for all instances within a method. any\_address can be any value. {% content-ref url="/pages/ndyYpsCSMpJIfDtxB53l" %} [Bootstrap](/v2-integration/protocol-methods/bootstrap) {% endcontent-ref %} {% content-ref url="/pages/zWVGS6XaWy5jIg9Nq98W" %} [Add Initial Liquidity](/v2-integration/protocol-methods/add-initial-liquidity) {% endcontent-ref %} {% content-ref url="/pages/eVfHvJDYukcSWUMBJlci" %} [Add Subsequent Liquidity](/v2-integration/protocol-methods/add-subsequent-liquidity) {% endcontent-ref %} {% content-ref url="/pages/QgMlcr5nD13sERf5aZtG" %} [Remove Liquidity](/v2-integration/protocol-methods/remove-liquidity) {% endcontent-ref %} {% content-ref url="/pages/chdMmFTDopXD6Al1IKHd" %} [Swap](/v2-integration/protocol-methods/swap) {% endcontent-ref %} {% content-ref url="/pages/PE8p4ctw5ZMCurkRWXOr" %} [Flash Loan](/v2-integration/protocol-methods/flash-loan) {% endcontent-ref %} {% content-ref url="/pages/Hh0Zw8IqAF1aYryptkTy" %} [Flash Swap](/v2-integration/protocol-methods/flash-swap) {% endcontent-ref %} {% content-ref url="/pages/QEnxPyDyBrPYQyg7zbob" %} [State Data](/v2-integration/state-data) {% endcontent-ref %} {% content-ref url="/pages/E7Qx06KdjUmOZfIWyBUx" %} [Oracle Data](/v2-integration/oracle-data) {% endcontent-ref %} # Bootstrap ### **Transactions** **Pay:** Sender: any\_address\ Receiver: pool\_address\ Amount:\ Pool minimum balance ([Formula I](https://docs.tinyman.org/v2-integration/protocol-methods/pages/RArypJMatkCdksZvFhuW#i.-pool-minimum-balance))\ \+ Transaction fee of the app call\ \+ 100000 (min transaction fee for asset creation) **AppCall:** Sender: pool\_address (Logic Sig)\ Index: tinyman\_amm\_v2\_app\_id\ OnComplete: OptIn\ App Args: \[“bootstrap”]\ Foreign Assets: \[asset\_1\_id, asset\_2\_id]\ RekeyTo: tinyman\_amm\_v2\_app\_address\ Fee: (7 \* min\_fee) (Note: 6 \* min\_fee if asset 2 is Algo) ### **Side Effects** #### **Local State Changes** 1. pool\_token\_asset\_id 2. asset\_1\_id 3. asset\_2\_id 4. total\_fee\_share 5. protocol\_fee\_ratio 6. asset\_1\_reserves 7. asset\_2\_reserves 8. issued\_pool\_tokens 9. asset\_1\_protocol\_fees 10. asset\_2\_protocol\_fees 11. lock 12. asset\_1\_cumulative\_price 13. asset\_2\_cumulative\_price 14. cumulative\_price\_update\_timestamp #### **Inner Transactions** **1. Pay:** Sender: pool\_address\ Receiver: tinyman\_amm\_v2\_app\_address\ Amount: 100\_000\ Fee: 0 **2. AssetConfig:** Sender: tinyman\_amm\_v2\_app\_address\ UnitName: “TMPOOL2”\ Name: “TinymanPool2.0 {asset\_1\_unit\_name}-{asset\_2\_unit\_name}”\ MetadataHash: “{asset\_1\_id}{asset\_2\_id}{trailing zeros}”\ uint64 (8 bytes) + uint64 (8 bytes) + zeros (16 bytes)\ Total: 18446744073709551615\ Reserve: pool\_address\ Decimals: 6\ URL: “
Swap Widget Example
Swap Settings
Styling
# How to export your Widget There are two main ways of handling transaction signing: Local Signer and Parent Signer. It is controlled by the "Use wallet connection inside the widget - Local Signer" switch on the export page. This choice determines the implementation method; ### 1. Local Signer Local Signer, is an option with a separate session within the Widget for those looking for simplified implementation. The widget handles the wallet connection and the transaction signing. ### Steps 1. Configure the widget according to your preferences. 2. Copy the iframe embed code. 3. Paste the code in your application code. 4. That’s it! ### 2. Parent Signer: Parent Signer, is a more advanced option and aims to use the existing Parent App's session; it does not need a separate session for the users. If you want to use your existing wallet connection in the widget, you need to install our JS SDK for easy integration. ### Steps 1. First, install the SDK with npm: ``` npm install @tinymanorg/tinyman-swap-widget-sdk ``` 2. (optional) To get the function parameters easily, you can copy the `Parameters Object` on the export page. 3. Then, you should use `generateIframeUrl` to generate the iframe URL, for example: ``` const widgetIframeUrl = WidgetController.generateWidgetIframeUrl({ platformName: "Platform name", // should be `true` if you will use your own wallet useParentSigner: true, // :exclamation:update `accountAddress` value with the real value of the connected account address accountAddress: "ADDRESS_OF_SIGNER_ACCOUNT", network: "testnet", // "testnet" or "mainnet" themeVariables: { shouldDisplayTinymanLogo: true // you can customize more styles, please refer to configuration page }, parentUrlOrigin: window.location.origin, // or your app url origin e.g. "https://myapp.com" assetIds: [0, 10458941] }); ``` 4. Use this URL to add the iframe element to your page: ``` ``` 5. Now you should be able to see the widget on your page, but still, you need to establish communication between the application and the widget. We use the `postMessage` API for this. Create an instance of `WidgetController` and set up event listeners with your own callbacks. This way, your application will get a message when the widget needs a signature on a transaction, or when there is an error. And you can send the transaction back to the widget after it’s signed. Please follow our quick start guide here:
# Trigger Orders & Recurring Orders ### Overview Tinyman is introducing two powerful trading features on its decentralized exchange: Trigger Orders (Limit Orders) and Recurring Orders (DCA). These tools allow users to trade more strategically, automate purchases, and stay fully in control — all with the speed, security, and transparency of the Algorand blockchain. ### 1. Trigger Orders #### Description A Trigger Order (also known as Limit Order) lets users buy or sell a token at a specific price. The trade will only execute if the market reaches the price set by the user, within a timeframe they choose. #### Benefits * Set your preferred price for buy/sell orders * Trade passively and strategically * Avoid constant price monitoring * Maintain full custody of funds at all times #### Expiration Options Users can choose when the order should expire: * Never * After 10 minutes * After 1 hour * After 1 day * After 3 days * After 7 days * After 30 days If the price condition is not met before the expiration, the order is canceled and the funds are returned to the user’s wallet. #### Minimum Trade Amount * $5 USD equivalent per order #### Fees * A 0.15% fee is charged when a Trigger Order is successfully executed. * TINY governors enjoy a discounted fee of 0,1%. In order to be eligible, TINY governors need to hold a TINY power of at least 5000 #### Execution Flow * When a user places a Trigger Order, the funds are locked into a dedicated smart contract. * If the price target is reached, the order is executed and tokens are sent directly to the user’s wallet. * If canceled or expired, the original funds are returned. * Partial fills: If only part of the order is filled, the user will be able to claim the completed portion at a later stage (feature coming soon). * Users can cancel the order at any time and funds will be returned to their wallet. #### Example Use Case A user places a Trigger Order to buy ALGO at $0.16, set to expire in 1 day.\ They commit $25 to the order, meeting the $5 minimum.\ If ALGO reaches $0.16 within 24 hours, the order executes automatically.\ If not, it expires and the $25 is returned. ### 2. Recurring Orders (DCA) #### Description A Recurring Order (also known as Dollar Cost Averaging) allows users to automate regular purchases of a token at predefined intervals. This strategy is especially useful for long-term accumulation and reducing exposure to short-term volatility. #### Benefits * Automate recurring token buys * Reduce impact of market volatility * Ideal for long-term investors * Fully non-custodial and on-chain #### Configuration Options Users can define: * Interval between orders: * Every minute * Every hour * Every day * Every week * Every month * Number of executions (e.g., 5 purchases over 5 days) * Price range (optional): * Users can specify a price range within which the recurring orders are allowed to execute. * This ensures that purchases are only made when the asset price is within a target zone, adding an extra layer of strategy. #### Minimum Order Amount * Each recurring execution must be at least $5 USD * The total recurring order value must be at least $10 USD * Example: If a user wants to schedule 5 recurring orders, they must commit at least $25 (5 x $5) #### Fees * A 0.15% fee is charged when a Recurring Order is successfully executed. * TINY governors enjoy a discounted fee of 0,1%. In order to be eligible, TINY governors need to hold a TINY power of at least 5000 #### Execution Flow * Full order value is deposited into a smart contract at creation * The contract executes trades at the defined intervals and within the allowed price range * After each execution, tokens are delivered directly to the user's wallet * Orders can be canceled at any time, and unused funds will be returned #### Example Use Case A user sets up a Recurring Order to buy $10 of ALGO every day for 5 days, only if ALGO trades between $0.15 and $0.18.\ They commit $50 total, satisfying the $10 minimum per execution.\ Each day, if ALGO's price is within range, $10 is used to purchase tokens.\ After 5 days or 5 successful executions, the order completes automatically. ### 3. Security Security is a top priority at Tinyman. Both Limit Orders and Recurring Orders are built on secure, transparent smart contracts. * All contracts are internally reviewed and tested * The contracts are open source * The contracts are upgradable with user consent only * Isolated smart contracts: each user has their own contract account, holding only the associated funds — no pooled risks * Users retain full control over their assets at all times * Transactions and states are fully on-chain and auditable * All orders are executed atomically, ensuring there can be no loss of funds to partial execution * Recurring Orders use the existing Tinyman Swap Router to ensure trades are made at the market price. * The contracts ensure Recurring Order executions are not at risk of sandwich attacks ### 4. Early Access for TINY Governors Tinyman prioritizes community governance. TINY Governors — users who lock TINY in governance — will get early access to both Trigger Orders and Recurring Orders. #### Eligibility * Locking at least 5,000 TINY Power is required for early access #### Additional Governance Benefits * Weekly TINY rewards for participation * Voting rights on farming rewards and protocol upgrades * Early access to future feature rollouts * Boosted staking: stake ALGO in the Stakepool, restake tALGO as a Governor, and earn additional TINY rewards on top of your ALGO staking returns ### 5. Additional Considerations * Trigger Orders & Recurring Orders are executed on a best effort basis. Off-chain components are required for triggering execution and despite redundancy these may fail to execute. * Trigger Orders might not execute even when the trigger price is reached. This can be due to a number of factors including the trigger price falling again within a short timespan, the price impact of the order and the volume of orders. * Note this is not an orderbook system. The orders are executed on the Tinyman AMM where the price moves independently of the trigger orders. * Smaller order amounts have higher probability of successful execution than larger ones. # Liquid Staking ### Overview of Liquid Staking The liquid staking solution enables users to stake ALGO directly into the Tinyman Stake Pool through the Tinyman UI. By participating in staking, users contribute to the security and decentralization of the Algorand blockchain while earning staking rewards. ### Staking Rewards Staking rewards are distributed in ALGO. The total rewards earned per ALGO decrease as more ALGO are staked, resulting in a lower Annual Percentage Rate (APR). Rewards for tALGO are derived from two primary sources: 1. Block fees - 50% of transaction fees will be paid out as block reward 2. Algorand Foundation-funded supplementary bonus - Starting at 10 Algo per block, this bonus will decay by 1% every 1 million blocks. The Foundation has committed to providing bonus rewards for a period of 24 months. ### Fee Structure Tinyman employs a fee structure that automatically deducts a portion of the staking rewards to support the protocol's sustainability. A fee of 8% is applied to the total block rewards before distribution to users. The remaining rewards are added to the tALGO value. ### Liquid Staking Process Upon staking ALGO, users receive tALGO in return. tALGO is a liquid token that can be traded or transferred and can be utilized for additional yield opportunities, such as re-staking, liquidity provision, and farming. Importantly, tALGO automatically accrues Algorand staking rewards without requiring active management. ### Unstaking tALGO tALGO can be redeemed for ALGO at any time, with no lock-up periods or penalties. Upon redemption, users receive the initial ALGO amount along with any accrued staking rewards. ### Re-Staking tALGO Users have the option to re-stake tALGO. Upon re-staking, stALGO is issued at a 1:1 ratio. stALGO represents the re-staked tALGO and allows for the earning of additional TINY rewards. While stALGO remains in the user's wallet, it cannot be transferred or traded. Holding stALGO enables continuous accumulation of TINY rewards, which can be claimed at any time from the re-staking page—unstaking is not required to access these rewards. Re-staking provides an opportunity to generate extra yield without active management. ### Re-Staking Requirements To re-stake tALGO, a minimum of 5000 TINY power is required, which can be earned by locking TINY tokens in governance. Locking TINY qualifies users as Tinyman governors and provides various benefits, including additional TINY rewards and voting rights. For further details, please refer to this [link](https://docs.tinyman.org/token-and-governance/governance-details/governance-vault). ### Unstaking stALGO stALGO can be unstaked at any time and redeemed for tALGO on a 1:1 basis. Any accrued TINY rewards can be claimed at any time. A minimum of 5000 TINY power is required in order to claim TINY rewards. ### Swapping ALGO When a user swaps ALGO to tALGO, the "stake ALGO" process is applied, staking the ALGO and issuing tALGO. When a user swaps tALGO back to ALGO, the "unstake tALGO" process is applied, unstaking the tALGO and returning the original ALGO. ### Implementation Details & Contracts The contract sources are available to view in the Github repo. The repo also contains [audit reports](https://github.com/tinymanorg/tinyman-consensus-staking/tree/main/audits) and the [protocol specification](https://github.com/tinymanorg/tinyman-consensus-staking/blob/main/docs/Tinyman_Liquid_Staking_Protocol_Specification.pdf). Github repo:
# FAQ *Tinyman is in ongoing development and the following FAQs will continue to be updated as the Tinyman protocol continues to be defined.* ## **What service does Tinyman offer?** Tinyman enables users to trade/swap Assets (Tokens/Currencies) at market rates. ## Who are the users of Tinyman? There are two classes of users of Tinyman: Swappers who trade assets and Poolers who provide asset liquidity for the trading Pools. Poolers are individuals/organisations who hold reasonably large amounts of assets. Swappers are individuals/organizations who wish to exchange tokens. They may be interested in doing this in an automated way with bots or they may use an app interface. ## What are Pools? Pools are Accounts holding two different Assets contributed by Poolers. Swappers transfer assets to and from pools. ## Who sets the exchange rates? The exchange rate for a swap is determined from the ratio of the pair of Assets in the Pool and the amount to be swapped. The precise rate will be different for every transaction but will always ensure the total product of the Pool stays constant (+ fees). This type of exchange is known as a Constant Product Market Maker, a type of Automated Market Maker. ## How is the exchange rate enforced? The smart contracts of the Pool ensure that only a group of transactions for the correct amounts succeed. ## Why do Poolers provide assets? In return for providing assets, they receive a share of transaction fees. ## How are Poolers fee shares calculated? A Pooler is issued an amount of Pool Token proportional to their Pool contribution. This can be cashed in at any time in return for a portion of the Pools assets. ## How often does the Pooler receive fees? Poolers only receive fees when they withdraw liquidity (assets) from the Pool by exchanging their Pool Tokens. ## Who controls withdrawals from the Pools? The assets are held in a contract account that only allows withdrawals in two cases: 1. As one transaction of a swap where an equal value of the other asset is deposited 2. As one transaction of a withdrawal where an equal value of Pool Tokens are deposited ## Who owns the assets in a Pool? Only the Pool Token holders have the right to withdraw assets and only in proportion to their contribution so they collectively own the Pool assets. ## Can a Pooler withdraw one asset from a Pool? No, the Pool’s balance must be maintained so an equal value of both currencies must be withdrawn in exchange for Pool Tokens. ## How does a Swapper interact with Tinyman? A Swapper may swap assets with the Tinyman pools using either of three methods: 1. Manually/programatically creating, signing and submitting a set of transactions that satisfy the smart contracts 2. Signing and submitting the transactions created by the helper functions of the Tinyman JS library 3. Using the web app interface to do the swap, signing the transactions with a wallet browser extension. Current available wallets and browser extensions are [Pera Wallet](https://perawallet.app/), [My Algo Wallet](https://wallet.myalgo.com/), [Exodus Wallet](https://www.exodus.com/), [Defly](https://defly.app/), [Fireblocks](https://www.fireblocks.com/) and other WalletConnect and AlgoSigner compatible wallets. ## How does a Pooler interact with Tinyman? Using any of the 3 methods described above for Swappers. ## How can I connect to Tinyman with my Ledger account? Wallets that support atomic transactions for Ledger accounts can operate flawlessly with the Tinyman platform. At the moment only My Algo Wallet supports this. Hopefully other wallets will support this in the near future. ## How will the exchange rate track the general market rate? Certain Swappers will monitor discrepancies between Tinyman rates and rates on other exchanges and trade these to their profit until the rates are equalized. This is known as arbitrage trading. ## How are Pools created? Pools are created by submitting a specific set of transactions. The logic of the contracts ensures that only one Tinyman Pool can exist for a pair of assets. ## Who can create Pools? Anyone can create a Pool by issuing the correct set of transactions. ## Can Pools be created for any pair of Algorand Standard Assets? Yes, the protocol is fully permissionless so no restrictions are in place. However it is not at all advisable to create pools with assets that have a low total supply. Pools should not be created with assets that represent collectables, NFTs or similar.\ The system is designed with the expectation that the minimum input and output amount of a swap is 1000 microunits. Swapping smaller amounts than this may lead to rounding errors that negatively affect users. ## Can Pools be created with Algo as one of the ‘assets’? Yes. Algo is not an ASA but it may be used as one of the assets in a Pool. ## Can Tinyman be used to swap NFTs? No, AMM protocols like Tinyman are not suitable for swapping assets like NFTs. ## How is the exchange rate set at the time of Pool creation? The Pool creation contracts do not enforce an exchange rate as they have no knowledge of the current market rates. However, it is in the Pooler's interest to ensure the ratio of assets deposits matches the market rates. Pools can always be traded against from both sides so Swappers will take advantage of any rates that don't match the overall market. ## What currency/asset is the swap fee paid in? The fee is paid in the currency of input/sell asset. The fee amount is added to the liquidity in the pool. ## Does the platform/protocol earn fees? The platform earns fees at %0.05 of the input amount. Pool tokens are allocated to the protocol representing the platform's share of each swap. ## Who will control the protocol fee account? The protocol fee account will eventually be controlled by a governance process encoded in smart contracts. Holders of a governance token will be able to participate in this process and control how the fee account’s assets are used. The details of this governance system are TBD. It will not be in place at the time of the initial product launch. The protocol fees are claimable only by the creator of the Tinyman Validator app, a MultiSig account controlled by team members. ## Can Pool tokens be traded? Yes they are standard assets and can be traded freely. Only the pool token is necessary to redeem liquidity from the associated Pool. ## Can't the Tinyman team change the rules of contracts and take all the assets? No. The contracts will be published with rules that forbid anyone to change them. The team will have no way of taking assets from Pool accounts or modifying any of the contract code. ## Does that mean the Tinyman product will never change or improve? No. The contracts themselves cannot be updated but the interface may be improved and may even interact with new contracts. If the team persuades the community that the new contracts offer advantages, the Poolers will want to move their assets to the new accounts. The old contracts will still exist and Swappers and Poolers will still be free to use them as they wish. ## What transactions are needed for a Swap? A Swap is made by transferring some of "Asset A" to a Pool and transferring some of "Asset B" from the Pool. Algorand smart contracts only allow or reject transactions but do not initiate any transfers themselves. The Tinyman SDK/Web App will prepare a group of transactions that will be approved by the Tinyman smart contracts. The specific group of transactions needed for a Swap are as follows: 0: Pay - pay fees in Algo from Swapper to Pool 1: App Call - NoOp call to Pair App with args 'swap' 2: AssetTransfer - transfer sell asset from Swapper to Pool 3: AssetTransfer - transfer buy asset from Pool to Swapper The app call transaction (1) verifies that the amounts of transactions 2 and 3 satisfy the constraint of the Pool. The Pay transaction (0) is required to transfer enough Algos to the Pool to cover the fees of transactions 1 and 3. Transactions 0 and 2 must be signed by the Swapper. ## What happens if the Pool exchange rate changes between the time of preparing the transactions and execution (slippage)? This will be a common occurrence in Pools with high volume. Tinyman handles this by including slippage tolerance in the preparation of the transactions to reduce the possibility of asking for more of an asset than allowed by the rate. If the initial set of swap transactions succeed, the minimum amount will be received. The Pool will likely hold some excess that can be reclaimed with a subsequent transaction. The excess is redeemed with a Redeem transaction group.
## What transactions are needed to Redeem excess? The specific group of transactions needed for a Redeem is as follows: 0: Pay - pay fees in Algo from Swapper to Pool 1: App Call - NoOp call to Pair App with args 'redeem' 2: AssetTransfer - transfer asset from Pool to Swapper The app call transaction (1) verifies that the amount in transaction 2 is the same as the amount of excess stored in the Pool for the Swapper. The Pay transaction (0) is required to transfer enough Algos to the Pool to cover the fees of transactions 1 and 2. Transaction 0 must be signed by the Swapper. ## Is Excess a type of reward or profit? No, excess is simply an IOU or change from some operations with the pool due to slippage tolerance. Read more about it [here](/tinyman-v1/tinyman-amm-basics/slippage-and-excess). ## Are any additional transactions required to Swap on Tinyman? The Swapper must Opt-In to the Tinyman Validation app once. They must also Opt-In to receive Assets that they have not previously received. As with all Apps and Assets on Algorand, each Opt-In increases the minimum balance of Algos required. This is not a fee but a minimum balance that must be held. ## How does the Swapper know the correct amounts to include in their Swap transactions? The Tinyman SDK/Web App will calculate these based on the Swapper input amounts using information retrieved from the network on the current asset amounts held by the Pool account. The formula to determine the swap amounts including fees is publicly known and encoded in the SDK/Web App. ## How does Tinyman mark Assets as Verified? Tinyman does not "Verify" any Asset and does not play any role in the verification process. This process is done by Algorand. Tinyman only pulls this verification information from the Algorand Wallet. Beware that Algorand's official verification mark is different than the verification mark in [http://algoexplorer.io](http://algoexplorer.io/). ## **What is impermanent loss?** CoinMarketCap defines impermanent loss as “the temporary loss of funds occasionally experienced by liquidity providers because of volatility in a trading pair.” To put this into perspective, if you are holding an LP token, and one of the assets depreciates in value in the short term, but gradually returns to the original price, then you would have lost value "impermanently." Alternatively, if the same asset appreciated in value before reverting to the mean, you would have had "impermanent gains." These metrics can help liquidity providers balance their portfolios for optimal ratios. For instance, if you think a token will appreciate, and then revert to the mean, you might provide liquidity before it appreciates, just to accumulate the fees for that duration.\ \ If you'd like to learn more about impermanent loss, the following articles may be useful:\
## Does Tinyman earn commission when I add Algo with Moonpay? No, Tinyman has setup an integration with Moonpay with 0 fees/commission for Tinyman. This integration is provided purely as a convience for Tinyman users. ## **How can I get help with buying Algo with Moonpay ?** For any issues related to Moonpay please checkout their support page here:
# Design Doc This document outlines the design for a permissionless distributed exchange on Algorand conducted by an automated market maker (AMM). This document outlines the design for a permissionless distributed exchange on Algorand conducted by an automated market maker (AMM). This exchange is modeled after [Uniswap](https://uniswap.org/docs/v2/protocol-overview/how-uniswap-works) on Ethereum. The AMM will be implemented on-chain as Algorand TEAL smart contracts. ### Terminology * Pools - liquidity pools holding 2 assets * Poolers - users who provide assets to the Pools * Swappers - users who trade/swap assets through Pools * Assets - Algorand Standard Assets (ASAs) and Algo * Liquidity Token - An ASA that represents a share of the value of a Pool ### Assumptions * The exchange will be permissionless, meaning that anyone can use it. * The exchange is fully decentralized and immutable - nobody can update/delete/freeze the Pools or assets. * The exchange is non-custodial. Only the Poolers have access to their shares of the Pools. * The AMM will be a [constant product market maker](https://github.com/runtimeverification/verified-smart-contracts/blob/uniswap/uniswap/x-y-k.pdf), like Uniswap. * The Pools hold assets in a 50/50 ratio. * The AMM will allow exchange between pairs of Algorand Standard Assets (ASAs) or ASA and Algo. * The ASAs should have high liquidity - a large total supply (not NFTs or collectables). * The minimum swap/mint/burn size is expected to be 1000 microunits. * A percentage based fee is charged on every trade, called the swap fee. This fee increases a Pool’s liquidity and benefits liquidity providers (Poolers). ### Users This exchange is designed to be used by two parties: Swappers and Poolers (liquidity providers). * Swappers - use the exchange to swap one asset for another. * Poolers - contribute assets to a Pool in the exchange, and in return, they are given liquidity tokens. * Liquidity tokens can be returned at any time to the Pool for a proportion of the Pool’s assets equal to the proportion of liquidity tokens being returned. ### Architecture Liquidity Pools are implemented as contract accounts controlled by LogicSignatures. A stateful smart contract, the Validator app, implements the validation and state changing logic for all Pools. The Validator app is deployed to the network by the Tinyman team. The Pool contract accounts are created from the Pool LogicSig template by the first Pooler who wishes to provide liquidity.  #### Validator App * Stateful smart contract * Created by Tinyman core team * Fully immutable * No updates allowed * No deletion allowed * No global state * Local state in Pool, Pooler, Swapper accounts (16 ints, 0 bytes) * Contains validation and state manipulation logic for all operations #### Pool Logic Signature Template * A stateless smart contract template * Template variables for asset 1 and asset 2 ids * Pool contract account address retrieved by hashing the completed template * Contains logic to ensure only transactions part of expected transaction groups are signed * Delegates most logic responsibility to the Validator app by ensuring the transaction group contains a call to the Validator App with appropriate arguments #### Pool Contract Account * One Pool account per asset pair * Exclusively controlled by the Pool Logic Signature (No associated private key) * Creates/owns the Liquidity Token asset for the Pool #### Liquidity Token Asset * An Algorand Standard Asset (ASA) * One liquidity token asset per Pool * Created by the Pool * Fully permissionless * No freeze permission * No clawback permission * No management permission ## Operations This section describes how Pools are found, created, and used. ### Lookup In order to use a Pool, users must know the address of the LogicSig account. To get the address of the Pool LogicSig account, we make its TEAL contract template publicly available. Users can then fill out the template with the two assets IDs that they want to exchange and then hash it to get its address. This provides a deterministic way to find the address of a Pool and ensures that only one Pool exists for an asset pair. Once the user knows the Pool LogicSig account address, they can query the account state to find the only asset created by the Pool, the Liquidity Token. The current balances (and thus exchange rate) of the Pool are found by querying the Pool account state to find the asset balances and the Validator app local state. This information can be combined to retrieve the current balances and exchange rate. ### Creation In case an address for a Pool with certain assets represents an account that has not yet been created, any user can create that Pool by funding that address and executing some bootstrap transactions. The address needs funding because of the minimum balance associated with opting into the Validator App, opting into the assets, creating its own liquidity token asset, and paying for transaction fees. If there is sufficient interest in a Pool, some user should be willing to donate these funds. The account that bootstraps the Pool does not need to be the account that mints the first liquidity. These are separate operations. The bootstrapper does not have any form of ownership or privilege over the Pool. #### Bootstrap Process The goal of the bootstrap process is to allow any user to create a new Pool without the possibility that the Pool could get stuck in an invalid state. The bootstrap operation consists of a single atomic group of 5 transactions: 1. Pay Algo to cover fees and minimum balance 2. Opt-In to Validator app, with args \['bootstrap', asset1ID, asset2ID] 3. AssetConfig - create asset for liquidity token 4. Asset OptIn - Pool opt in to Asset 1 5. (Optional) Asset OptIn - Pool opt in to Asset 2 Transaction 0 must cover the minimum balance + the fees for the subsequent 3 (or 4) transactions (3 (or 4) \* 1000 microAlgo). The calculation for the minimum balance is as follows: `minBalance = 100000 // min account balance`\ `+ 100000 // min balance to create asset`\ `+ 100000 // fee + min balance to opt into asset 1`\ `+ (asset2Optin ? 100000 : 0) // min balance to opt into asset 2`\ `+ 100000 + (25000+3500)*numLocalInts`\ `+ (25000+25000)*numLocalByteSlices; // min balance to opt into validator app` The Validator App has numLocalInts=16 and numLocalByteSlices=0 so the minBalance is 956000 for a ASA-ASA pool and 856000 for a ASA-Algo pool. Transactions 1-4 must be signed by the Pool LogicSig which will verify that the provided values are correct. The Validator app will store the asset IDs in its local state in the Pool account, so that they can be referenced later. Because this is an atomic group, if any of these transactions do not meet the criteria defined in the Validator contract or the Pool LogicSig contract, all transactions will fail. Once the Pool account is created and bootstrapped, the Pool is ready to mint liquidity tokens. ### Mint Liquidity A user (Pooler) can mint liquidity by contributing equivalent values of each asset in a pair to that pair’s Pool account. In return, the Pool rewards the user with liquidity tokens in proportion to the amount of assets they contributed. The initial liquidity token amount is calculated as the geometric mean of the two asset amounts provided: `initial liquidity token amount = sqrt(asset1 * asset2)` The first 1000 units of the liquidity token are ‘locked’ to prevent rounding errors in the calculation so the first minter receives `sqrt(asset1 * asset2) - 1000` liquidity tokens. Subsequent minting should maintain the current ratio of the two assets. Liquidity tokens are minted according to the following formula: `liquidity_token_out = Min(`\ `(asset1_amount / asset1_supply) * issued_liquidity_tokens,`\ `(asset2_amount / asset2_supply) * issued_liquidity_tokens`\ `)` Note: A Pooler may provide assets in another ratio but they will only be minted liquidity tokens for the smaller amount so they would effectively be providing a donation to the Pool. Aside from Algorand transaction fees, there are no fees charged to Poolers for minting. ### Burn Liquidity Any user in possession of liquidity tokens can ‘burn’ them (some or all) at any time by exchanging them with the Pool for the corresponding proportion of the Pool’s assets. For example, if a Pool has a balance of 10 asset A, 100 asset B and has issued 10 outstanding liquidity tokens, 1 liquidity token can be burnt for 1 asset A and 10 asset B. The Pool would then have a balance of 9 asset A, 90 asset B and have issued 9 outstanding liquidity tokens. If a user wants to mint/burn liquidity and only wants to send/receive one asset from a pair, a convenience method can be implemented that swaps half the amount of the asset for them before a mint or after a burn. This method will only be practical for insignificant amounts of liquidity, since larger additions/subtractions would skew the exchange rate unfavorably. Aside from Algorand transaction fees, there are no fees charged to Poolers for burning. The asset out amounts are calculated as follows: `asset1_out = asset1_supply * (burn_amount / issued_liquidity_tokens)`\ `asset2_out = asset2_supply * (burn_amount / issued_liquidity_tokens)` ### Swap Given a Pool account for assets A and B that has non-zero liquidity, a user can use this Pool to swap some amount of asset A for asset B, or some amount of asset B for asset A. The exact exchange rate is determined by the ratio of assets A and B that the Pool account holds and the amount of assets the user wants to swap, in addition to the exchange fee. Since a swap changes the ratio of assets that the Pool account holds, every swap has an effect on the exchange rate. Small swaps on Pools with lots of liquidity have the least effect. #### Slippage Tolerance The exchange rate between a pair of assets changes constantly due to transactions in the Pool. Between the time the Swapper prepares their swap transaction and the time the swap is executed, the exchange rate may have changed, or ‘slipped’. The concept of ‘slippage tolerance’ defines how much of a slippage the Swapper is willing to tolerate. The tolerance is defined as a percentage. 0% means the Swapper does not tolerate any slippage and wants the exact quoted amounts or the transaction should fail. A slippage of 100% would allow the received amounts to drop to 0. Usually this value is somewhere around 1%. #### Swap Types There are two types of swaps that the Swapper can choose from when submitting a swap transaction group. These two types determine which side of the swap the slippage is applied to: * Fixed input swaps: this swap involves a fixed amount of the input asset and requests a variable amount of the output asset. For example, a user might want to exchange exactly 10 USDC for any amount of Planet Tokens at the current market rate. * Fixed output swaps: this swap involves a variable amount of the input asset and requests a fixed amount of the output asset. For example, a user might want to exchange any amount of USDC for exactly 50 Planet Tokens at the current market rate. #### Fixed input calculation amount\_out = (asset\_in\_amount \* 997 \* output\_supply) / ((input\_supply \* 1000) + (asset\_in\_amount \* 997)) #### Fixed output calculation amount\_in = ((asset\_out\_amount \* input\_supply \* 1000) / ((output\_supply - asset\_out\_amount) \* 997)) + 1
#### Swap Fees Aside from Algorand transaction fees, Swappers must pay a swap fee of 0.3% to the Pool. This fee is deducted from the input or output amount depending on the swap type. The fee is calculated into the swap quote returned by the Web UI or SDK. Note: The fees paid in Algo in the first transaction of a Swap transaction group cover the transaction fees of the subsequent transactions, NOT the swap fee. The swap fees increase the assets of the Pool and thus increase the value of the Pool shares owned by the Poolers. Swap fees cannot be redeemed by Poolers separately from their Pool shares. **Protocol Fees** A portion of the swap fees (1/6th) are granted to the system and are known as Protocol Fees. Liquidity tokens proportionate to 1/6th of the fee amount are minted and set aside. These are redeemable only by a specific account (the creator of the Validator App) and are intended to fund a treasury. **Protocol fee calculation for fixed input swap:** `protocol_fee_portion = asset_out_amount * 0.05%`\ `protocol_fee_portion = (asset_out_amount * 5) / 10000` The protocol is granted a share of the pool for half of this amount because it's a 50/50 pool: `protocol_fee_asset_out_amount = (asset_out_amount * 5) / 20000`\ `protocol_fee_liquidity_tokens = issued_liquidity_tokens * (protocol_fee_asset_out_amount / output_supply)` ## Implementation Algorand smart contracts have some limitations that the AMM implementation must work around. The primary one is that smart contracts cannot directly send assets to users; they can only approve or deny transactions sent by users. However, stateful smart contracts can manipulate local account state. The user interacts with a Pool by preparing a set (atomic group) of transactions specific to the operation they wish to perform. If the structure and values of all parameters of all transactions in the group match the expectations of the contracts, the operation is executed. The expected values of the parameters depend on hard coded values in the contracts and also local app state stored in the Pool account. The user must lookup the current balances and app state values to determine the correct inputs for each operation. (This is handled for the actual end user by the Web App of course.) It is expected that there will be highly concurrent use of the Pools so the Pool balances and state values will constantly be in flux. This presents a (frustrating) challenge for a user that needs to submit transactions with exactly correct values. It is highly probable that the expected values will have changed by the time the transactions are executed, even if only a couple of seconds pass. To handle this issue the Pool supports a form of slippage tolerance in Mint, Burn and Swap operations. The user specifies the minimum amount they expect to receive in the asset out transfer. The contract allows the transaction group to succeed if this can be satisfied but it also calculates and records any excess asset that is owed to the user in a fair trading scenario. This excess is stored and can be redeemed with a subsequent Redeem operation.  #### Excess and Outstanding Amounts The excess amounts for all pools are stored in the local state of the Validator app. The state keys for each asset are prefixed by the Pool address to allow for excess amounts of the same asset from multiple pools. The user must Opt-In to the Validator app so that it may store excess amounts in the local state. There is a limit of 16 state variables available. These are shared by all Pools. It is possible that a User will interact with many Pools and exhaust the available state slots available. In this case the user will be prompted to Redeem (and thus clear) excess amounts before continuing. The Pool also needs to track the total outstanding amounts of each asset that are owed to users and subtract these from the asset balances to determine the actual asset supply when calculating swap/mint/burn amounts. These outstanding amounts for each asset are held in local state variables of the Pool (one for each of asset 1, asset 2 and the liquidity token). The outstanding amounts are reduced when a user redeems assets. #### Fixed Input Swaps Instead of asking the Pool account to send the exact amount of an asset the Swapper wants from the swap, this transaction would specify the minimum amount of the asset the Swapper wants. If the swap executes, the Swapper is guaranteed to get this minimum amount by the nature of atomic transaction groups. However, in most cases when a swap executes, the amount of the asset the Swapper is due to receive would exceed the minimum amount they asked for. This excess amount would be recorded in their local state by the Validator App contract. In a subsequent transaction group, the Swapper can claim this amount from the Pool account. For example, consider a Swapper who submits a swap exchanging exactly 1 of asset A for at least 2 of asset B. When their swap transaction executes, the exchange rate is such that 1 of asset A is equivalent to 3 of asset B, so their transaction is approved and 1 unit of asset B is recorded as an excess balance in their local state. The Swapper can then submit a transaction immediately after they see the result of their swap to claim the additional 1 unit of asset B. #### Fixed Output Swaps Instead of the asset in transaction declaring the exact amount of the input asset they wish to swap, that transaction would specify the maximum amount of the asset they want to swap. The amount specified by the asset out transaction from the Pool account still represents the exact amount of the asset the Swapper wants to receive. If the desired amount of the output asset can be exchanged using less than the maximum input asset amount, this difference would be recorded in the Swapper’s local state by the Validator App contract, similar to the excess amount in a fixed input swap. This reduced amount of input assets can be claimed by the Swapper in a subsequent transaction group. For example, consider a Swapper who submits a swap exchanging at most 2 of asset A for exactly 1 of asset B. When their swap transaction executes, the exchange rate is such that 1.5 of asset A is equivalent to 1 of asset B, so their transaction is approved and 0.5 units of asset A is recorded as an excess balance in their local state. The Swapper can then submit a transaction immediately after they see the result of their swap to claim the 0.5 units of asset A that were not needed in the swap. This mechanism allows for the output assets to be sent to a different account if the sender wishes to do so and the recipient is able to receive the asset. This enables use cases like the following: I have a balance of 500 asset A and I need to pay my friend exactly 10 asset B. I can submit a fixed output swap for exactly 10 asset B in exchange for at most 500 asset A and change the recipient of the asset out transaction to my friend’s address. When the operation succeeds, my friend will receive exactly 10 asset B and I will have paid an equivalent amount of asset A. #### Liquidity A similar procedure also applies to minting and burning liquidity tokens, since frequent small fluctuations in liquidity necessitate the need to have a slippage tolerance in these situations too. #### Redeeming To redeem excess amounts from a Pool the user must submit a transaction group for the Redeem operation. This consists of a transaction to pay translation fees, a call to the Validator app and a transaction to transfer assets from the Pool to the user. The transactions will only be successful if the requested amount in the transfer is less than or equal to the current excess assets of the Pool. The redeemed amount is deducted from both the excess asset amount in the user’s local state and the outstanding asset amount in the Pool’s local state. If the excess amount for an asset is reduced to 0 by a redeem operation, the corresponding slot of local state is cleared rather than set to 0. This prevents issues with exhausting the available slots when interacting with multiple pools. The redeem operation is used by both Swappers and Poolers to claim excess amounts of Asset 1, Asset 2 and the Liquidity Token for Poolers. Aside from Algorand transaction fees, there are no fees charged to Users for redeeming. A redemption requires 3 transactions with a total fee of 3000 microAlgos (currently), so it may not always be cost effective to redeem excess amounts immediately. #### Protocol Fees The protocol Treasury account accumulates liquidity tokens proportional to 1/6th of the swap fee ( 5/10000ths of the swap value). These liquidity token assets cannot be transferred inline to the treasury account, so they are stored in a local state variable in the Pool account and added to the outstanding liquidity token amount state variable. The creator of the validator app can redeem these amounts as liquidity tokens using a ‘fees’ operation. This account is the only account that can retrieve these assets. #### Transaction Group Structure All interactions with the Pool involve the use of atomic transaction groups. These have a common basic structure to make validation easier in the contract code. * The first transaction (gtxn 0) is always a Pay transaction from the User to the Pool to pay fees for the subsequent transactions that the Pool will make. * The second transaction (gtxn 1) is always an Application Call to the validator app with at least one argument. The first argument determines the type of the operation; bootstrap, mint, burn, swap, redeem. This transaction is always signed by the Pool LogicSig. This ensures both the Validator App and the LogicSig participate in validation of the transaction group. #### Handling of Algo Algo is the native currency of Algorand and is not represented as an Algorand Standard Asset. This has some implications for the handling of Algo as one of the assets of a pair in a Pool. The general formulae remain the same for Pools with Algo, but the implementation has to explicitly handle the case. The Algo has a special asset id of 0 and this is checked in various places in the code. Transfers of Assets are made using an AssetTransfer transaction while an Algo transfer is made using a Pay transaction. This requires the code to check the fields of either AssetTransfer or Pay transactions. Similarly, the Algo balance is accessed differently from ASA balances. The Pool’s Algo asset reserves must be separated from it’s actual balance by subtracting Algo amounts that are held for other reasons. The Pool must hold a minimum balance of Algo to Opt-In to assets and the Validator app. This minimum balance is not considered part of the reserves of the Pool. Similarly, the transaction fees are transferred to the Pool in the first transaction of each group. These temporarily inflate the balance of the Pool and need to be subtracted to determine the actual reserve amount. ## User Flows ### Swapper 1. Opt-In to Validator App (once) 1. Prepare, sign, submit, wait for completion 2. Opt-In to Asset Out if necessary 1. Prepare, sign, submit, wait for completion 3. Lookup Pool info for asset pair 4. Do Swap 1. Prepare, sign, submit, wait for completion 5. Do Redeem (for excess amounts) 1. Prepare, sign, submit, wait for completion ### Pooler 1. Opt-In to Validator App (once) 1. Prepare, sign, submit, wait for completion 2. Lookup Pool info for asset pair 3. Create Pool if it doesn’t exist 1. Prepare, sign, submit, wait for completion 4. Opt-In to Pool Liquidity Token Asset 1. Prepare, sign, submit, wait for completion 5. Do Mint 1. Prepare, sign, submit, wait for completion 6. Do Redeem (for excess liquidity Token) 1. Prepare, sign, submit, wait for completion ###
# Contracts Source code on Github: