mirror of
https://github.com/alexgo-io/alex-v1-docs.git
synced 2026-01-12 14:33:49 +08:00
new structure proposal: smart contracts, developers section (demo)
This commit is contained in:
simsbluebox
14
SUMMARY.md
14
SUMMARY.md
@@ -6,9 +6,6 @@
|
||||
|
||||
* [Our Design](trading-lending-and-borrowing/platform-architecture-that-supports-ecosystem-development.md)
|
||||
* [Trading Pool](trading-lending-and-borrowing/trading-pool/README.md)
|
||||
* [amm-pool-v2-01.clar](trading-lending-and-borrowing/trading-pool/amm-pool-v2-01.clar.md)
|
||||
* [amm-registry-v2-01.clar](trading-lending-and-borrowing/trading-pool/amm-registry-v2-01.clar.md)
|
||||
* [amm-vault-v2-01.clar](trading-lending-and-borrowing/trading-pool/amm-vault-v2-01.clar.md)
|
||||
* [Collateral Rebalancing Pool](trading-lending-and-borrowing/collateral-rebalancing-pool.md)
|
||||
* [Yield Token Pool](trading-lending-and-borrowing/automated-market-making-designed-for-lending-protocols.md)
|
||||
* [Vault](trading-lending-and-borrowing/vault.md)
|
||||
@@ -53,8 +50,13 @@
|
||||
|
||||
## 🎮 Developers
|
||||
|
||||
* [Testnet](developers/testnet.md)
|
||||
* [Environments](developers/environments/README.md)
|
||||
* [Mainnet](developers/environments/mainnet.md)
|
||||
* [Token List](developers/environments/token-list.md)
|
||||
* [Testnet](developers/environments/testnet.md)
|
||||
* [AMM Pool Mapping](developers/environments/amm-pool-mapping.md)
|
||||
* [Smart Contracts](developers/smart-contracts/README.md)
|
||||
* [Token List](developers/smart-contracts/token-list.md)
|
||||
* [AMM Pool Mapping](developers/smart-contracts/amm-pool-mapping.md)
|
||||
* [amm-pool-v2-01.clar](developers/smart-contracts/amm-pool-v2-01.clar.md)
|
||||
* [amm-registry-v2-01.clar](developers/smart-contracts/amm-registry-v2-01.clar.md)
|
||||
* [amm-vault-v2-01.clar](developers/smart-contracts/amm-vault-v2-01.clar.md)
|
||||
* [REST API](developers/api-references.md)
|
||||
|
||||
4
developers/environments/README.md
Normal file
4
developers/environments/README.md
Normal file
@@ -0,0 +1,4 @@
|
||||
# Environments
|
||||
|
||||
* [Mainnet](mainnet.md)
|
||||
* [Testnet](testnet.md)
|
||||
@@ -1,3 +1,5 @@
|
||||
<mark style="color:green;">Demo note: this document seems to be outdated. We propose to remove it.</mark>
|
||||
|
||||
# AMM Pool Mapping
|
||||
|
||||
Below table maps the pool listed on [https://app.alexlab.co/pool](https://app.alexlab.co/pool) to smart contracts with the relevant parameters
|
||||
5
developers/environments/mainnet.md
Normal file
5
developers/environments/mainnet.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# Smart Contracts
|
||||
|
||||
For the complete token list and the pool mapping, see [Token List](token-list.md) and [AMM Pool Mapping](amm-pool-mapping.md).
|
||||
|
||||
<table><thead><tr><th width="167">Contract</th><th>Address</th></tr></thead><tbody><tr><td>DAO</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao</td></tr><tr><td>Vault</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault</td></tr><tr><td>Reserve Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool</td></tr><tr><td>Launchpad</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1</td></tr><tr><td>Lottery</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery</td></tr><tr><td>Trading Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1</td></tr><tr><td>Fixed Weight Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01</td></tr><tr><td>Simple Weight Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alex</td></tr><tr><td>Swap Router</td><td>(to route between Fixed Weight Pool and Simple Weight Pool)<br>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-v1-03</td></tr><tr><td>Swap Bridge </td><td>(to route between Trading Pool and Fixed Weight Pool / Simple Weight Pool)<br>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged</td></tr><tr><td>ALEX Token</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token</td></tr><tr><td>autoALEX Token</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex</td></tr><tr><td>Bridge Endpoint</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01</td></tr><tr><td>sUSDT</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt</td></tr></tbody></table>
|
||||
@@ -1,5 +1,83 @@
|
||||
# Smart Contracts
|
||||
<mark style="color:green;">Demo note: this bridge document will be reworked as an overall ALEXGO inventory (not only the trading pool contracts).</mark>
|
||||
|
||||
For the complete token list and the pool mapping, see [Token List](token-list.md) and [AMM Pool Mapping](amm-pool-mapping.md).
|
||||
# ALEX DAO AMM Trading Pool
|
||||
|
||||
<table><thead><tr><th width="167">Contract</th><th>Address</th></tr></thead><tbody><tr><td>DAO</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.executor-dao</td></tr><tr><td>Vault</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault</td></tr><tr><td>Reserve Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-reserve-pool</td></tr><tr><td>Launchpad</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-launchpad-v1-1</td></tr><tr><td>Lottery</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-lottery</td></tr><tr><td>Trading Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1</td></tr><tr><td>Fixed Weight Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.fixed-weight-pool-v1-01</td></tr><tr><td>Simple Weight Pool</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.simple-weight-pool-alex</td></tr><tr><td>Swap Router</td><td>(to route between Fixed Weight Pool and Simple Weight Pool)<br>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-v1-03</td></tr><tr><td>Swap Bridge </td><td>(to route between Trading Pool and Fixed Weight Pool / Simple Weight Pool)<br>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.swap-helper-bridged</td></tr><tr><td>ALEX Token</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token</td></tr><tr><td>autoALEX Token</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.auto-alex</td></tr><tr><td>Bridge Endpoint</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.bridge-endpoint-v1-01</td></tr><tr><td>sUSDT</td><td>SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-susdt</td></tr></tbody></table>
|
||||
This section provides an overview of the ALEX on-chain Trading Pool and its Automated Market Making (AMM) protocol. The AMM Trading Pool protocol consists of a set of smart contracts that facilitate trading operations within the ALEX DeFi ecosystem. Below, we list these contracts, explain how they interact with each other, and describe some common technical aspects.
|
||||
|
||||
## Contracts map
|
||||
|
||||
|
||||
|
||||
### Pool: amm-pool-v2-01.clar
|
||||
|
||||
This is the primary contract in ALEX's AMM Trading Pool system. It encompasses several core operations, including pool creation, liquidity operations, LP token management, and token swapping. This contract is complemented by the two auxiliary contracts listed below.
|
||||
|
||||
[Complete technical documentation](./amm-pool-v2-01.clar.md)
|
||||
|
||||
### Registry: amm-registry-v2-01.clar
|
||||
|
||||
This contract functions as a persistence module for all pool-related information needed by the ALEX Automated Market Maker (AMM) Trading Pool system. It also manages a list of blocklisted operators.
|
||||
|
||||
[Complete technical documentation](./amm-registry-v2-01.clar.md)
|
||||
|
||||
|
||||
### Vault: amm-vault-v2-01.clar
|
||||
|
||||
The vault contract supports the primary contract `amm-pool-v2-01.clar` in position and swap operations by keeping records of the reserves accumulated from fees and securing pool assets. This contract also offers a flash-loan feature for registered tokens, available to approved users.
|
||||
|
||||
[Complete technical documentation](./amm-vault-v2-01.clar.md)
|
||||
|
||||
## Common features
|
||||
|
||||
### Governance
|
||||
|
||||
The smart contracts discussed in this section include features to control administrative privileges, access, and operational status. It is needed to duplicate some functions for them to be available on each contract.
|
||||
|
||||
#### Admin access control
|
||||
|
||||
Each of the three contracts includes a feature that checks administrative access through the function `is-dao-or-extension`. This function ensures that the caller (`tx-sender`) is either the DAO executor or an authorized extension.
|
||||
|
||||
#### Operational status
|
||||
|
||||
The `amm-pool-v2-01` and `amm-vault-v2-01` contracts have functionalities to set and query the operational status of the contract. Specifically, these contracts include a `paused` flag. When this flag is set to true, all operations within the contract are halted.
|
||||
|
||||
#### Blocklisted operators
|
||||
|
||||
The `amm-registry-v2-01` contract features the ability to update (on admin operator request) and query a list of blacklisted addresses that are prohibited from operating within the trading pool. The `amm-pool-v2-01` contract delegates the task of this verification to the registry, which performs a check against the `tx-sender`.
|
||||
|
||||
### Imported Traits
|
||||
|
||||
In Clarity language, a trait defines a public interface to which smart contracts can conform. All Trading Pool contracts in this documentation import traits to ensure interface conformity for various types (such as tokens and flash-loan users) and to conduct their transactions safely. These traits are customized versions of standard traits which are provided by the ALEX platform to serve specific purposes. Below is a list of all the traits utilized by the Trading Pool contracts.
|
||||
|
||||
#### sip-010-trait
|
||||
|
||||
This is a customized version of the Stacks' Standard Trait Definition for Fungible Tokens and is used by all three Trading Pool contracts. The changes in this version include support for 8-digit fixed notation and additional helper functions for `transfer`, `get-balance`, and `get-total-supply`. Mint and burn functions are also included along with their respective helpers.
|
||||
|
||||
[ALEX sip-010 customized implementation](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/traits/trait-sip-010.clar) |
|
||||
[Full sip-010 standard](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md)
|
||||
|
||||
#### semi-fungible-trait
|
||||
|
||||
This is a customized version of the Stacks' Standard Trait Definition for Semi-Fungible Tokens and is used only by the Vault contract.
|
||||
The customizations are similar to those in the customized `sip-010-trait`, with additional fixed notation helpers for the `transfer-memo`, `get-overall-balance`, and `get-overall-supply` functions. Additionally, the `get-token-uri` function is customized to redefine the `response` parameter type to the tuple: `(optional (string-utf8 256)) uint` instead of sip-013's `string-ascii`.
|
||||
|
||||
[ALEX sip-013 customized implementation](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/traits/trait-semi-fungible.clar) |
|
||||
[Full sip-013 standard](https://github.com/stacksgov/sips/blob/main/sips/sip-013/sip-013-semi-fungible-token-standard.md)
|
||||
|
||||
#### flash-loan-user-trait
|
||||
|
||||
This is a custom trait from ALEX designed to support flash-loan operations and is used only by the Vault contract. The trait defines an `execute` function, which is asserted in the Vault's `flash-loan` function signature, allowing the flash-loan user to execute their logic with the loaned amount.
|
||||
|
||||
[ALEX flash-loan customized implementation](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/traits/trait-flash-loan-user.clar)
|
||||
|
||||
### Mathematics helpers
|
||||
|
||||
The Pool and Vault contracts are equipped with helper functions that facilitate various mathematical operations (e.g., amounts, percentages) with the necessary precision. These helpers improve the expressiveness of the contracts' logic. Some of these helper functions utilize mathematical constants defined within each contract. All helper functions are declared as private and, like the governance functions, may be replicated across both contracts using the same equations.
|
||||
|
||||
|Topic|Functions|
|
||||
|--|--|
|
||||
|Precision multipliers and divisors|`mul-down`, `mul-up`, `div-down`, `div-up`|
|
||||
|Rolling summation|`rolling_sum_div`, `rolling_div_sum`|
|
||||
|Accumulate|`accumulate_division`, `accumulate_product`|
|
||||
|Power and exponential|`pow-fixed`, `pow-priv`, `pow-down`, `pow-up`, `exp-fixed`, `exp-pos`|
|
||||
|Logarithmic|`log-fixed`, `ln-fixed`, `ln-priv`|
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
#### Location: [_`./alex-dao-2/contracts/extensions/amm-pool-v2-01.clar`_](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/extensions/amm-pool-v2-01.clar)
|
||||
|
||||
This document provides comprehensive technical documentation for the primary contract in ALEX's AMM Trading Pool system. The contract encompasses several core operations, including pool creation, liquidity operations (adding or removing assets), LP token management (minting and burning tokens that represent a user's share of the pool and potential earnings), and token swapping (facilitating the exchange of tokens within an existing and funded pool while charging a corresponding fee). This contract is complemented by two auxiliary contracts: a REGISTRY contract that handles the persistence of pool information, and a VAULT contract that secures the assets and manages the reserves accumulated from the fees. For detailed information about these auxiliary contracts, please refer to their respective technical documentation: [amm-registry-v2-01.clar](./amm-registry-v2-01.clar.md) and [amm-vault-v2-01.clar](./amm-vault-v2-01.clar.md).
|
||||
This document provides comprehensive technical documentation for the primary contract in ALEX's AMM Trading Pool system. The contract encompasses several core operations, including pool creation, liquidity operations (adding or removing assets), LP token management (minting and burning tokens that represent a user's share of the pool and potential earnings), and token swapping (facilitating the exchange of tokens within an existing and funded pool while charging a corresponding fee). This contract is complemented by two auxiliary contracts: a REGISTRY contract that handles the persistence of pool information, and a VAULT contract that secures the assets and manages the reserves accumulated from the fees. For detailed information about these auxiliary contracts, please refer to their respective technical documentation: [amm-registry-v2-01.clar](amm-registry-v2-01.clar.md) and [amm-vault-v2-01.clar](amm-vault-v2-01.clar.md).
|
||||
|
||||
## Storage
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
#### Location: [_`./alex-dao-2/contracts/aux/amm-registry-v2-01.clar`_](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/aux/amm-registry-v2-01.clar)
|
||||
|
||||
This document provides comprehensive technical details for the registry contract within ALEX's Automated Market Maker (AMM) Trading Pool system. The contract primarily functions as a persistence module for all pool-related information needed by the main contract [amm-pool-v2-01.clar](./amm-pool-v2-01.clar.md).
|
||||
This document provides comprehensive technical details for the registry contract within ALEX's Automated Market Maker (AMM) Trading Pool system. The contract primarily functions as a persistence module for all pool-related information needed by the main contract [amm-pool-v2-01.clar](amm-pool-v2-01.clar.md).
|
||||
|
||||
To achieve this, the contract allows for the creation and updating of pools. Pool creation involves persisting an entry in a datamap, using `token-x`, `token-y`, and `factor` as the key and containing all relevant pool information.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
#### Location: [_`./alex-dao-2/contracts/aux/amm-vault-v2-01.clar`_](https://github.com/alexgo-io/alex-dao-2/blob/main/contracts/aux/amm-vault-v2-01.clar)
|
||||
|
||||
This document provides comprehensive technical details for the vault contract within ALEX's Automated Market Maker (AMM) Trading Pool system. The vault contract supports the primary contract [amm-pool-v2-01.clar](./amm-pool-v2-01.clar.md) in position and swap operations by keeping record of the reserves accumulated from fees and securing pool assets. It ensures asset security through transfer transactions where the vault contract is the recipient of token transfers, thereby holding and safeguarding the assets within the pool.
|
||||
This document provides comprehensive technical details for the vault contract within ALEX's Automated Market Maker (AMM) Trading Pool system. The vault contract supports the primary contract [amm-pool-v2-01.clar](amm-pool-v2-01.clar.md) in position and swap operations by keeping record of the reserves accumulated from fees and securing pool assets. It ensures asset security through transfer transactions where the vault contract is the recipient of token transfers, thereby holding and safeguarding the assets within the pool.
|
||||
In addition to supporting Trading Pool operations, the vault contract also offers a flash-loan feature for registered tokens, available to approved users.
|
||||
|
||||
## Storage
|
||||
@@ -1,3 +1,5 @@
|
||||
<mark style="color:green;">Demo note: this document will be adjusted with some updated operations context and an enriched glossary. A link to developers contract section will be included.</mark>
|
||||
|
||||
# Trading Pool
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
<mark style="color:green;">Demo note: A link to developers contract section will be included.</mark>
|
||||
|
||||
# Vault
|
||||
|
||||
Vault holds and manages the assets of all ALEX pools. The separation of pool and vault has many benefits including, among others, cheaper transaction costs for users and quicker learning curve for developers when building custom pools on ALEX.
|
||||
|
||||
Reference in New Issue
Block a user