@usdu-core/usdu-core 0.0.1

package/README.md

@@ -0,0 +1,244 @@
+# Core
+
+### Yarn Package Scripts
+
+```json
+// yarn run <command> args...
+
+"wallet": "npx ts-node helper/wallet.info.ts",
+"wallet:info": "npx ts-node helper/wallet.info.ts",
+
+"compile": "npx hardhat compile",
+"test": "npx hardhat test",
+"coverage": "npx hardhat coverage",
+
+"deploy": "npx hardhat ignition deploy",
+"verify": "npx hardhat verify",
+
+"npm:build": "tsup",
+"npm:publish": "npm publish --access public"
+```
+
+### 1. Install dependencies
+
+`yarn install`
+
+### 2. Set Environment
+
+> See .env.example
+
+```JSON
+file: .env
+
+DEPLOYER_SEED="test test test test test test test test test test test junk"
+DEPLOYER_SEED_INDEX=1
+ALCHEMY_RPC_KEY=...
+ETHERSCAN_API=...
+```
+
+> Create new session or re-navigate to the current directory, to make sure environment is loaded from `.env`
+
+### 3. Develop Smart Contracts
+
+> Develop your contracts in the `/contracts` directory and compile with:
+
+```Bash
+yarn run compile					# Compiles all contracts
+```
+
+### 4. Testing
+
+> All test files are located in /test directory. Run tests using:
+
+```Bash
+yarn run test                    	# Run all tests
+yarn run test test/Membership.ts 	# Run specific test file
+yarn run coverage               	# Generate test coverage report
+```
+
+### 5. Write Deployment Scripts (via ignition deploy and verify)
+
+-   Create new `/ignition/params/[file].ts` for type conform deployment params
+-   Create new `/ignition/module/[file].ts` for workflow of deployment
+
+> Deployment modules are located in `/ignition/modules`. Deploy your contracts:
+
+```Bash
+yarn run deploy ignition/modules/MembershipFactory.ts --network polygon --verify --deployment-id Membership01
+
+--> increase: deployment-id
+```
+
+This will:
+
+-   Compile and deploy contracts
+-   Verify on Etherscan and Sourcify
+-   Generate deployment artifacts in `/ignition/deployments`
+
+Verify:
+
+-   verifies contract on etherscan
+-   verifies contract on sourcify
+
+Key deployment files:
+
+-   deployed_addresses.json: Contains contract addresses
+-   journal.json: Detailed deployment logs
+
+-   creates deployment artifacts in /ignition`/deployments` directory
+-   creates ./ignition/deployments/[deployment]/`deployed_addresses.json`
+-   creates ./ignition/deployments/[deployment]/`journal.jsonl`
+-   creates constructor-args in /ignition`/constructor-args` directory, as JS module export
+
+### 5.1 Example
+
+```Bash
+✔ Confirm deploy to network polygon (137)? … yes
+{
+  message: 'Config Info: Deploying Module with accounts',
+  admin: '0xb687FE7E47774B22F10Ca5E747496d81827167E3',
+  executor: '0xBdae8D35EDe5bc5174E805DcBe3F7714d142DAAb',
+  member: '0x2ACf17C04F1d8BE7E9D5529894DCee86bf2fcdC3'
+}
+Constructor Args
+[
+  '0xb687FE7E47774B22F10Ca5E747496d81827167E3',
+  '0xBdae8D35EDe5bc5174E805DcBe3F7714d142DAAb',
+  '0x2ACf17C04F1d8BE7E9D5529894DCee86bf2fcdC3'
+]
+Hardhat Ignition 🚀
+
+Deploying [ MembershipModule ]
+
+Batch #1
+  Executed MembershipModule#Membership
+
+Batch #2
+  Executed MembershipModule#Storage
+
+[ MembershipModule ] successfully deployed 🚀
+
+Deployed Addresses
+
+MembershipModule#Membership - 0x72950A0A9689fCA941Ddc9E1a58dcD3fb792E3D2
+MembershipModule#Storage - 0x8A7e8091e71cCB7D1EbDd773C26AD82AAd323328
+
+Verifying deployed contracts
+
+Verifying contract "contracts/Membership.sol:Membership" for network polygon...
+Contract contracts/Membership.sol:Membership already verified on network polygon:
+  - https://polygonscan.com/address/0x72950A0A9689fCA941Ddc9E1a58dcD3fb792E3D2#code
+
+Verifying contract "contracts/Storage.sol:Storage" for network polygon...
+Contract contracts/Storage.sol:Storage already verified on network polygon:
+  - https://polygonscan.com/address/0x8A7e8091e71cCB7D1EbDd773C26AD82AAd323328#code
+
+✨  Done in 69.96s.
+```
+
+### 5.2 Manual Verify
+
+`npx hardhat verify --network polygon --constructor-args ./ignition/constructor-args/$FILE.js $ADDRESS`
+
+or manually include unrelated contracts by creating or using `/ignition/constructor-args/[file].js`
+
+`npx hardhat ignition verify $DEPLOYMENT --include-unrelated-contracts`
+
+### 6 Prepare NPM Package Support
+
+-   [x] Export ready to use TypeScript ABIs
+-   [x] Export ready to use TypeScript deployed address config
+-   [ ] ...
+
+### 6.1 TypeScript ABIs
+
+Export contract ABIs for npm package usage by copying the JSON into dedicated TypeScript files:
+
+```TS
+file: exports/abis/...
+
+export const StorageABI = [
+...
+JSON
+...
+] as const;
+```
+
+### 6.2 TypeScript Address Config
+
+Provides a mapping of contract addresses for the Membership and Storage contracts deployed on different blockchain networks.
+
+The `ADDRESS` object contains the contract addresses for the `mainnet` and `polygon` networks, with the network ID as the key.
+The `zeroAddress` is used as a placeholder for the `mainnet` network, as the contracts have not been deployed there yet.
+
+```TS
+file: exports/address.config.ts
+
+import { mainnet, polygon } from 'viem/chains';
+import { Address, zeroAddress } from 'viem';
+
+export interface ChainAddress {
+	membership: Address;
+	storage: Address;
+}
+
+export const ADDRESS: Record<number, ChainAddress> = {
+	[mainnet.id]: {
+		membership: zeroAddress,
+		storage: zeroAddress,
+	},
+	[polygon.id]: {
+		membership: '0x72950A0A9689fCA941Ddc9E1a58dcD3fb792E3D2',
+		storage: '0x8A7e8091e71cCB7D1EbDd773C26AD82AAd323328',
+	},
+};
+```
+
+# 7. TSUP and npm package
+
+### 7.1 TSUP
+
+> Config: /tsup.config.ts
+
+TSUP bundles TypeScript code into optimized JavaScript packages. This package uses TSUP to create production-ready builds.
+
+`yarn run build`
+
+### 7.2 NPM Package
+
+> **Increase Version:** Update version number in package.json using semantic versioning (e.g. 0.0.1 -> 0.0.2) before publishing new changes.
+
+```
+file: /package.json
+
+"name": "@wrytlabs/core-template",
+"version": "0.0.1", <-- HERE
+```
+
+Login to your NPM account
+
+`npm login`
+
+This will publish your package to NPM with public access, making it **available for anyone to install and use**.
+
+`yarn run publish`
+
+To publish new version. `publish: "npm publish --access public"`
+
+> **Note**: During npm package publishing, the command may execute twice. The second execution will fail with a version conflict since the package is already published. This is expected behavior and the first publish will have succeeded.
+
+### 7.3 How to transpile package into bundled apps
+
+(not needed, since its already a true JS bundled module)
+
+E.g. for `NextJs` using the `next.config.js` in root of project.
+
+```js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+	reactStrictMode: true,
+	transpilePackages: ['@wrtylabs/core', '@wrytelabs/api'],
+};
+
+module.exports = nextConfig;
+```

package/contracts/curve/CurveAdapterV1.sol

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+pragma solidity ^0.8.20;
+
+import {Math} from '@openzeppelin/contracts/utils/math/Math.sol';
+
+import {Context} from '@openzeppelin/contracts/utils/Context.sol';
+import {IERC20Metadata} from '@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol';
+import {SafeERC20} from '@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol';
+
+import {Stablecoin} from '../stablecoin/Stablecoin.sol';
+import {ErrorsLib} from '../stablecoin/libraries/ErrorsLib.sol';
+import {ICurveStableSwapNG} from './helpers/ICurveStableSwapNG.sol';
+
+/**
+ * @title CurveAdapterV1
+ * @author @samclassix <samclassix@proton.me>, @wrytlabs <wrytlabs@proton.me>
+ * @notice This is an adapter for interacting with ICurveStableSwapNG to mint liquidity straight into the pool under certain conditions.
+ */
+contract CurveAdapterV1 is Context {
+	using Math for uint256;
+	using SafeERC20 for IERC20Metadata;
+	using SafeERC20 for Stablecoin;
+
+	ICurveStableSwapNG public immutable pool;
+	Stablecoin public immutable stable;
+	IERC20Metadata public immutable coin;
+
+	uint256 public immutable idxS;
+	uint256 public immutable idxC;
+
+	uint256 public totalMinted;
+	uint256 public totalRevenue;
+
+	address[5] public receivers;
+	uint32[5] public weights;
+	uint256 public totalWeights;
+
+	address[5] public pendingReceivers;
+	uint32[5] public pendingWeights;
+	uint256 public pendingValidAt;
+
+	// ---------------------------------------------------------------------------------------
+
+	event SubmitDistribution(address indexed caller, address[5] receivers, uint32[5] weights, uint256 timelock);
+	event RevokeDistribution(address indexed caller);
+	event SetDistribution(address indexed caller);
+
+	event AddLiquidity(address indexed sender, uint256 minted, uint256 totalMinted, uint256 sharesMinted, uint256 totalShares);
+	event RemoveLiquidity(address indexed sender, uint256 burned, uint256 totalMinted, uint256 sharesBurned, uint256 totalShares);
+	event Revenue(uint256 amount, uint256 totalRevenue, uint256 totalMinted);
+	event Distribution(address indexed receiver, uint256 amount, uint256 ratio);
+
+	// ---------------------------------------------------------------------------------------
+
+	error ImbalancedVariant(uint256[] balances);
+	error NotProfitable();
+
+	// ---------------------------------------------------------------------------------------
+
+	modifier onlyCurator() {
+		stable.verifyCurator(_msgSender());
+		_;
+	}
+
+	modifier onlyCuratorOrGuardian() {
+		stable.verifyCuratorOrGuardian(_msgSender());
+		_;
+	}
+
+	modifier afterTimelock(uint256 validAt) {
+		if (validAt == 0) revert ErrorsLib.NoPendingValue();
+		if (block.timestamp < validAt) revert ErrorsLib.TimelockNotElapsed();
+		_;
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	constructor(
+		ICurveStableSwapNG _pool,
+		uint256 _idxS, // IStablecoin
+		uint256 _idxC // IERC20 coin
+	) {
+		pool = _pool;
+
+		require(_idxS < 8, 'idxS out of bounds for max 8 tokens');
+		require(_idxC < 8, 'idxC out of bounds for max 8 tokens');
+
+		idxS = _idxS;
+		idxC = _idxC;
+
+		stable = Stablecoin(_pool.coins(_idxS));
+		coin = IERC20Metadata(_pool.coins(_idxC));
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function setDistribution(address[5] calldata _receivers, uint32[5] calldata _weights) external onlyCurator {
+		if (pendingValidAt != 0) revert ErrorsLib.AlreadyPending();
+
+		if (receivers[0] == address(0)) {
+			_setDistribution(_receivers, _weights);
+		} else {
+			pendingReceivers = _receivers;
+			pendingWeights = _weights;
+			pendingValidAt = block.timestamp + stable.timelock();
+			emit SubmitDistribution(_msgSender(), _receivers, _weights, pendingValidAt);
+		}
+	}
+
+	function revokePendingDistribution() external onlyCuratorOrGuardian {
+		if (pendingValidAt == 0) revert ErrorsLib.NoPendingValue();
+		emit RevokeDistribution(_msgSender());
+		_cleanUpPending();
+	}
+
+	function applyDistribution() external afterTimelock(pendingValidAt) {
+		_setDistribution(pendingReceivers, pendingWeights);
+	}
+
+	function _setDistribution(address[5] memory _receivers, uint32[5] memory _weights) internal {
+		// reset totalWeights
+		totalWeights = 0;
+
+		// update total weight
+		for (uint32 i = 0; i < _receivers.length; i++) {
+			totalWeights += _weights[i];
+		}
+
+		// update distribution
+		receivers = _receivers;
+		weights = _weights;
+
+		// emit event
+		emit SetDistribution(_msgSender());
+
+		_cleanUpPending();
+	}
+
+	function _cleanUpPending() internal {
+		delete pendingReceivers;
+		delete pendingWeights;
+		delete pendingValidAt;
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function checkImbalance() public view returns (bool) {
+		uint256 correctedAmount = (pool.balances(idxC) * 1 ether) / 10 ** coin.decimals();
+		if (pool.balances(idxS) <= correctedAmount) {
+			return true;
+		} else {
+			return false;
+		}
+	}
+
+	function verifyImbalance(bool state) public view {
+		if (checkImbalance() != state) revert ImbalancedVariant(pool.get_balances());
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function addLiquidity(uint256 amount, uint256 minShares) external returns (uint256) {
+		uint256 amountStable = (amount * 1 ether) / 10 ** coin.decimals();
+
+		// transfer coin token, needs approval
+		coin.safeTransferFrom(_msgSender(), address(this), amount);
+
+		// mint the same amountStable in stables
+		stable.mintModule(address(this), amountStable);
+		totalMinted += amountStable;
+
+		// approve tokens
+		stable.forceApprove(address(pool), amountStable);
+		coin.forceApprove(address(pool), amount);
+
+		// prepare amounts
+		uint256[] memory amounts = new uint256[](2);
+		amounts[idxS] = amountStable;
+		amounts[idxC] = amount;
+
+		// provide liquidity
+		uint256 shares = pool.add_liquidity(amounts, minShares * 2);
+
+		// verify imbalance for stable
+		verifyImbalance(true);
+
+		// return sender's split of shares
+		uint256 split = shares / 2;
+		pool.transfer(_msgSender(), split);
+
+		// emit event and return share split
+		emit AddLiquidity(_msgSender(), amountStable, totalMinted, split, pool.balanceOf(address(this)));
+		return split;
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function calcProfitability(uint256 beforeLP, uint256 afterLP, uint256 split) public view returns (uint256) {
+		// @dev: if all debt is already paid, `calcBeforeSplit` will be 0 and therefore profit is the whole `split`
+		uint256 calcBeforeSplit = ((1 ether - ((afterLP * 1 ether) / beforeLP)) * totalMinted) / 1 ether;
+		if (split > calcBeforeSplit) {
+			return split - calcBeforeSplit;
+		} else {
+			return 0;
+		}
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function removeLiquidity(uint256 shares, uint256 minAmount) external returns (uint256) {
+		// store LP balance
+		uint256 beforeLP = pool.balanceOf(address(this));
+
+		// transfer LP shares from sender, needs approval
+		pool.transferFrom(_msgSender(), address(this), shares);
+
+		// remove both shares and get split
+		uint256 split = pool.remove_liquidity_one_coin(shares * 2, int128(int256(idxS)), minAmount * 2) / 2;
+
+		// verify imbalance for coin
+		verifyImbalance(false);
+
+		// verify if in profit
+		uint256 afterLP = pool.balanceOf(address(this));
+		uint256 profit = calcProfitability(beforeLP, afterLP, split);
+		if (profit == 0) revert NotProfitable();
+		totalRevenue += profit;
+
+		// transfer split to sender
+		stable.transfer(_msgSender(), split);
+
+		// reconcile
+		uint256 burned = _reconcile();
+
+		// emit revenue with reduced totalMinted
+		emit Revenue(profit, totalRevenue, totalMinted);
+
+		// emit event and return share portion
+		emit RemoveLiquidity(_msgSender(), burned, totalMinted, shares, afterLP);
+		return split;
+	}
+
+	// ---------------------------------------------------------------------------------------
+	// redeem, onlyCurator
+
+	function redeem(uint256 shares, uint256 minAmount) external onlyCurator {
+		pool.remove_liquidity_one_coin(shares, int128(int256(idxS)), minAmount);
+		_reconcile();
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function payOffDebt() external onlyCuratorOrGuardian {
+		_reconcile();
+	}
+
+	// ---------------------------------------------------------------------------------------
+
+	function _reconcile() internal returns (uint256) {
+		uint256 amount = stable.balanceOf(address(this));
+		if (totalMinted <= amount) {
+			// in profit or neutral
+			uint256 dist = amount - totalMinted;
+
+			if (totalMinted != 0) {
+				stable.burn(totalMinted);
+				totalMinted = 0;
+			}
+
+			// distribute
+			if (dist != 0) {
+				_distribute(dist);
+			}
+
+			return totalMinted;
+		} else {
+			// fallback, burn existing totalMinted if available,
+			// will leave with dust debt
+			stable.burn(amount);
+			totalMinted -= amount;
+			return amount;
+		}
+	}
+
+	function _distribute(uint256 amount) internal {
+		for (uint256 i = 0; i < 5; i++) {
+			address receiver = receivers[i];
+			uint256 weight = weights[i];
+			uint256 split;
+
+			// end distribution
+			if (receiver == address(0)) return;
+
+			// last item reached (index: 5 - 1 = 4) OR next receiver is zeroAddress
+			if (i == 4 || (i < 4 && receivers[i + 1] == address(0))) {
+				// distribute remainings, eliminating rounding or deposit issues
+				split = stable.balanceOf(address(this));
+			} else {
+				// distribute weighted split
+				split = (weight * amount) / totalWeights;
+			}
+
+			// distribute revenue split
+			stable.transfer(receiver, split);
+
+			// last weighted ratio might be inconsistant, due to remaining assets distribution
+			emit Distribution(receiver, split, (weight * 1 ether) / totalWeights);
+		}
+	}
+}