Prepare to open repo to public (#88)

Co-authored-by: Udit Vira <[email protected]>

README.md

@@ -1,29 +1,38 @@
-# Neutron MAINNET Contracts
+# Valence Services
+![Rebalancer](https://www.valence.zone/img/rebalancer.svg)
 
-[![Check Set-Up & Build](https://github.com/timewave-computer/valence-services/actions/workflows/check.yml/badge.svg)](https://github.com/timewave-computer/valence-services/actions/workflows/check.yml)
+Valence Services houses the code for the [Valence Rebalancer](https://www.valence.zone/rebalancer). The Rebalancer enables automated balance sheet and treasury management. Use the Rebalancer to efficiently convert tokens for scheduled payments or manage your digital organization’s asset portfolio. The Rebalancer is custom-built to address the needs of blockchains, protocols, and decentralized autonomous organizations. 
+
+Learn more about the Rebalancer [here](https://www.valence.zone/blog/Rebalancer-Protocol-Asset-Management).
+
+This repository contains the smart contracts for the Valence Services. It includes the following contracts:
+- Auctions Manager
+- Auction
+- Oracle
+- Services Manager
+- Rebalancer
+- Account
 
-## Code ids
+Here is a high level of the system for more details please refer to the [Valence Services Architecture](./architecture.md)
 
-- auctions manager = `1502`
-- auction = `1504`
-- oracle = `1505`
-- rebalancer = `1501`
-- services manager = `1503`
-- account = `1506`
+![Top Level](./images/high-level.png)
 
-## Owner / Admin
+For a specific contract documentation, please refer to the README.md file of each contract.
 
-`neutron1phx0sz708k3t6xdnyc98hgkyhra4tp44et5s68`
+Parties (e.g. market makers) interested to participate in the Rebalancer Auctions should read the [Auctions contract documentation](./contracts//auction/auction/README.md).
 
-## Addresses
+## Neutron Mainnet Contracts
+
+[![Check Set-Up & Build](https://github.com/timewave-computer/valence-services/actions/workflows/check.yml/badge.svg)](https://github.com/timewave-computer/valence-services/actions/workflows/check.yml)
+
+### Addresses
 
 - Services manager - `neutron1gantvpnat0la8kkkzrnj48d5d8wxdjllh5r2w4r2hcrpwy00s69quypupa`
 - Auctions manager - `neutron13exc5wdc7y5qpqazc34djnu934lqvfw2dru30j52ahhjep6jzx8ssjxcyz`
 - Rebalancer - `neutron1qs6mzpmcw3dvg5l8nyywetcj326scszdj7v4pfk55xwshd4prqnqfwc0z2`
-- Account - `neutron1pkk88zqjd478x3maws3mv7qugylhsu0sjkejj3k2w02wwhp6fqgsl7m0js`
 - Oracle - `neutron1s8uqyh0mmh8g66s2dectf56c08y6fvusp39undp8kf4v678ededsy6tstf`
 
-### Auctions
+### Auctions addresses
 
 - [uatom, untrn] - `neutron1l9zmckc8j7zhutx088g6ppd9dfs45jet6dyq3pypc0gt5h9ncsvs5m4tsz`
 - [untrn, uatom] - `neutron13jppm4n77u8ud5wma9xe0dqnaz85ne9jem3r0scc009uemvh49qqxuuggf`
@@ -40,49 +49,10 @@
 - [untrn, newt] - `neutron1zvw9l8c82hnvwsntpuy89p86ztfmmudd9usfmnpa2tnqws74zsxq56sczm`
 - [uusdc, newt] - `neutron1vu04szc78ae0nplwpuxjr6j592hn2d60zqtuts7w3ah6kajtxd2q2vfv59`
 
-# Juno Contracts
-
-## Code ids
-
-- auctions manager = `3812`
-- auction = `3810`
-- price oracle = `3813`
-- rebalancer = `3814`
-- services manager = `3815`
-- account = `3811`
-
-## Token factory
-
-Token that is created by the token factory is the one that is used in our tests on juno
-
-vuusdcx - `factory/juno17s47ltx2hth9w5hntncv70kvyygvg0qr83zghn/vuusdcx`
-
-## Owner
-
-The Owner address is the admin of the contracts as well as the account owner.
-
-To add the owner to the keys (in order to use scripts on testnet):
-
-```
-junod keys add valence-owner --recover
-// Enter mnemonic from below
-```
-
-- Owner Juno - `juno17s47ltx2hth9w5hntncv70kvyygvg0qr83zghn`
-- Owner Neutron - `neutron17s47ltx2hth9w5hntncv70kvyygvg0qr4ug32g`
-- Owner mnemonic - `comfort decrease casual olive mountain joke timber concert leg salt stereo ticket trim plunge matter steak glory above neither hospital agent spoil kick split`
-
-## Addresses
-
-### Juno Contracts
+## Security
 
-- Services manager - `juno1h2md5367062ypuv93kpwyu84eaq04xx4lfmqwqp5fkqrwa66pynsk6qmk5`
-- Auctions manager - `juno1tp2n8fa9848355hfd98lufhm84sudlvnzwvsdsqtlahtsrdtl6astvrz9j`
-- Rebalancer - `juno18rpfddza4g3h5a05fzwq6xwepzh2t0twhetly4y5aqjyeh8cjflspa8fqr`
-- Account - `juno1rs76w568qe8z4vn9sxch7da84uauul5aek05n29tldmdra3dfk9qrar5ze`
-- Oracle - `juno14vgs85az6xlfzkczzq06agk2tv8zkdxqdue4gs08h0f60smu3jjqfryaj2`
+If you believe you've found a security-related issue with the contracts associated with this repository, please disclose responsibly by contacting the Timewave team at [[email protected]](mailto:[email protected]).
 
-#### Auctions
+## License
 
-- (ujunox, vuusdcx) - ``
-- (vuusdcx, ujunox) - ``
+All materials in this repository are licensed under [BSL](./LICENSE).

architecture.md

@@ -0,0 +1,21 @@
+# System Architecture
+
+The full figma diagram can be found [here](https://www.figma.com/board/o5hUA2cS7dV82gJYb3nLhN/Valence-Services?node-id=0-1&t=IfEzfIERC7KCJbKz-1)
+
+## System Instantiation
+![System Instantiation](./images/init.png)
+
+## Account interaction
+![Account interaction](./images/account.png)
+
+## Rebalancer
+![Rebalancer](./images/rebalancer.png)
+
+## Auctions
+![Auctions](./images/auction.png)
+
+## Oracle
+![Oracle](./images/oracle.png)
+
+## System flow
+![System flow](./images/flow.png)

contracts/auction/auction/README.md

@@ -41,11 +41,20 @@ The starting price will be `2 + (2 * 20%) = 2.4` and the end price will be `2 -
 
 ## Executables
 
-`AuctionFunds` - Send funds to be auctioned during the next auction.
+`AuctionFunds {}` - Send funds to be auctioned during the next auction.
 
-`WithdrawFunds` - Withdraw funds sent to the auction. Only funds from pending auctions can be withdrawn.
+`WithdrawFunds {}` - Withdraw funds sent to the auction. Only funds from pending auctions can be withdrawn.
 
-`Bid` - Bid in the active auction. The bid is resolved immediately.
+`Bid {}` - Bid in the active auction. The bid is resolved immediately.
+
+### Doing a bid
+
+First we need to know what the price of the auction before bidding, 2 queries are available:
+
+1. `GetPrice` - This gives us the current price of the auction.
+2. `GetAuction` - This gives us the auction `start_price`, `end_price`, `start_block`, `end_block`, which allows us to calculate the price decrease per block, and get the price in any future block. 
+
+Once we know the price and want to bid on that price, we execute `bid {}` message on the auction contract, and provide the amount of `TOKEN_2` we want to buy with, any leftovers will be returned to the bidder.
 
 ### Auction management
 
@@ -55,15 +64,15 @@ Based on the weight each seller had in the auction, we send the amount of `TOKEN
 There will be cases where we have leftover results from rounding, the leftover tokens will be added to the next auction, to mitigate the leftovers of the next auction.
 The impact of the leftover tokens is minimal per seller, the loss is less than 1 udenom (1 millionth of 1 token) per auction.
 
-`CleanAfterAuction` - Clean up storage from the closed auction that is not needed anymore.
+`CleanAfterAuction {}` - Clean up storage from the closed auction that is not needed anymore.
 
 ### Admin
 
 The admin of each auction is the Auctions Manager contract, which makes it easier for us to manage multiple auctions.
 
-`PauseAuction` - Allows us to pause the auction in case of an emergency.
+`PauseAuction {}` - Allows us to pause the auction in case of an emergency.
 
-`ResumeAuction` - Resume the auction after it was paused.
+`ResumeAuction {}` - Resume the auction after it was paused.
 
 `UpdateStrategy { strategy: AuctionStrategy }` - update the strategy of the auction, see more in the [Auction strategy](#auction-strategy) section.
 

contracts/services_manager/README.md

@@ -9,6 +9,21 @@ The services manager maintains a registry of services. It allows services users
 2. You instantiate a service
 3. You add the service to the services manager.
 
+## Service fee
+
+Currently the rebalancer charges service fees when either of two actions are performed:
+1. Register: A fee is taken when an account registers to a service for the first time.
+2. Resume: A fee is taken when an account resumes the rebalancer service after it has been automatically paused by the system due to low balance. Note that accounts do not have to pay fees to resume the service if the account itself has paused the service.
+
+The rebalancer service fee can be queried the rebalancer service with the following message:
+```json
+ {
+  "get_service_fee": {
+    "account": "<account address>",
+    "action": "<register | resume>"
+ }
+  ```
+
 ## Talk to a service
 
 You can now talk to any service that exists on the services manager, using its name instead of its address.