From d7bbcf29cf67b737fc30a546b8f942f68c707caf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=87a=C4=9Fla=20=C3=87elik?= Date: Wed, 4 Dec 2024 11:18:39 +0300 Subject: [PATCH] update docs --- Makefile | 8 +- docs/src/README.md | 90 ++-- docs/src/SUMMARY.md | 36 +- docs/src/contracts/README.md | 8 - docs/src/contracts/libraries/README.md | 4 - .../Statistics.sol/library.Statistics.md | 71 --- .../contract.LLMOracleCoordinator.md | 442 ------------------ .../contract.LLMOracleManager.md | 200 -------- .../contract.LLMOracleRegistry.md | 194 -------- .../enum.LLMOracleKind.md | 13 - .../interface.LLMOracleTask.md | 80 ---- .../struct.LLMOracleTaskParameters.md | 17 - docs/src/contracts/llm/README.md | 9 - .../contract.LLMOracleCoordinatorV2.md | 15 - .../contract.LLMOracleRegistryV2.md | 15 - docs/src/contracts/mock/README.md | 6 - docs/src/contracts/token/README.md | 4 - .../token/WETH9.sol/contract.WETH9.md | 115 ----- .../BuyerAgent.sol/contract.BuyerAgent.md | 62 ++- .../contract.BuyerAgentFactory.md | 4 +- docs/src/{contracts/swan => src}/README.md | 1 + .../swan => src}/Swan.sol/constants.Swan.md | 10 +- .../swan => src}/Swan.sol/contract.Swan.md | 116 +++-- .../SwanAsset.sol/contract.SwanAsset.md | 2 +- .../contract.SwanAssetFactory.md | 2 +- .../SwanManager.sol/abstract.SwanManager.md | 45 +- .../struct.SwanMarketParameters.md | 3 +- docs/src/src/mock/README.md | 4 + .../mock/SvanV2.sol}/contract.SwanV2.md | 4 +- foundry.toml | 2 +- 30 files changed, 216 insertions(+), 1366 deletions(-) delete mode 100644 docs/src/contracts/README.md delete mode 100644 docs/src/contracts/libraries/README.md delete mode 100644 docs/src/contracts/libraries/Statistics.sol/library.Statistics.md delete mode 100644 docs/src/contracts/llm/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md delete mode 100644 docs/src/contracts/llm/LLMOracleManager.sol/contract.LLMOracleManager.md delete mode 100644 docs/src/contracts/llm/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md delete mode 100644 docs/src/contracts/llm/LLMOracleRegistry.sol/enum.LLMOracleKind.md delete mode 100644 docs/src/contracts/llm/LLMOracleTask.sol/interface.LLMOracleTask.md delete mode 100644 docs/src/contracts/llm/LLMOracleTask.sol/struct.LLMOracleTaskParameters.md delete mode 100644 docs/src/contracts/llm/README.md delete mode 100644 docs/src/contracts/mock/LLMOracleCoordinatorV2.sol/contract.LLMOracleCoordinatorV2.md delete mode 100644 docs/src/contracts/mock/LLMOracleRegistryV2.sol/contract.LLMOracleRegistryV2.md delete mode 100644 docs/src/contracts/mock/README.md delete mode 100644 docs/src/contracts/token/README.md delete mode 100644 docs/src/contracts/token/WETH9.sol/contract.WETH9.md rename docs/src/{contracts/swan => src}/BuyerAgent.sol/contract.BuyerAgent.md (90%) rename docs/src/{contracts/swan => src}/BuyerAgent.sol/contract.BuyerAgentFactory.md (79%) rename docs/src/{contracts/swan => src}/README.md (95%) rename docs/src/{contracts/swan => src}/Swan.sol/constants.Swan.md (60%) rename docs/src/{contracts/swan => src}/Swan.sol/contract.Swan.md (82%) rename docs/src/{contracts/swan => src}/SwanAsset.sol/contract.SwanAsset.md (89%) rename docs/src/{contracts/swan => src}/SwanAsset.sol/contract.SwanAssetFactory.md (84%) rename docs/src/{contracts/swan => src}/SwanManager.sol/abstract.SwanManager.md (79%) rename docs/src/{contracts/swan => src}/SwanManager.sol/struct.SwanMarketParameters.md (82%) create mode 100644 docs/src/src/mock/README.md rename docs/src/{contracts/mock/SwanV2.sol => src/mock/SvanV2.sol}/contract.SwanV2.md (61%) diff --git a/Makefile b/Makefile index 08e1d92..5811ff8 100644 --- a/Makefile +++ b/Makefile @@ -26,7 +26,7 @@ update: # Build the contracts build: - forge clean && forge build + forge build # Generate gas snapshot snapshot: @@ -34,11 +34,11 @@ snapshot: # Test the contracts forked base-sepolia network with 4 parallel jobs test: - forge clean && forge test --fork-url $(BASE_TEST_RPC_URL) --no-match-contract "InvariantTest" --jobs 4 + forge test --fork-url $(BASE_TEST_RPC_URL) --no-match-contract "InvariantTest" --jobs 4 # Run invariant tests on local network with 4 parallel jobs test-inv: - forge clean && forge test --match-contract "InvariantTest" --jobs 4 + forge test --match-contract "InvariantTest" --jobs 4 anvil: anvil --fork-url $(BASE_TEST_RPC_URL) @@ -61,7 +61,7 @@ fmt: # Coverage cov: - forge clean && forge coverage --no-match-coverage "(test|mock|script)" --jobs 4 + forge coverage --no-match-coverage "(test|mock|script)" --jobs 4 # Verify contract on blockscout verify: diff --git a/docs/src/README.md b/docs/src/README.md index 872fc33..10ed460 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -1,10 +1,8 @@ # Swan Protocol +Swan is a **Decentralized Protocol** where AI agents (buyers) dynamically interact with asset creators. Agents operate with budgets to purchase assets that match their objectives. Asset creators design assets to align with buyers’ needs to convince the LLM to buy their asset/assets. -This document provides instructions for swan contracts using Foundry. - -## Test - -Compile the contracts: +## Compile +Compile the contracts with: ```sh make build @@ -14,32 +12,19 @@ make build > > Please prepare a valid `.env` according to `.env.example` before running tests. -Run tests on forked base-sepolia: - -```sh -make test -``` - -## Coverage +## Test -Check coverages with: +Run tests on forked base-sepolia with: ```sh -bash coverage.sh +make test ``` -You can see coverages under the coverage directory. - -## Storage Layout - -Get storage layout with: - +Run invariant tests on local with: ```sh -bash storage.sh +make test-inv ``` -You can see storage layouts under the storage directory. - ## Deployment **Step 1.** @@ -97,6 +82,54 @@ make deploy base-sepolia You can see deployed contract addresses under the `deployment/.json` +## Verify Contract + +Verify contract manually with: + +```sh +make verify base-sepolia +``` +## Coverage + +Check coverages with: + +```sh +bash coverage.sh +``` +or to see summarized coverages on terminal: + +```sh +make cov +``` + +You can see coverages under the coverage directory. + +## Storage Layout + +Get storage layout with: + +```sh +bash storage.sh +``` + +You can see storage layouts under the storage directory. + +## Format + +Format code with: + +```sh +make fmt +``` + +## Update + +Update modules with: + +```sh +make update +``` + ## Gas Snapshot Take the gas snapshot with: @@ -105,17 +138,14 @@ Take the gas snapshot with: make snapshot ``` -You can see the snapshot `.gas-snapshot` in the current directory. +You can see the snapshot `.gas-snapshot` file in the current directory. ## Generate documentation +Generate documentation with: + ```sh make doc ``` -You can also use the command below if you want to see docs locally with the given port number. - -```sh -make doc --serve --port - -``` +You can see the documentation under the `docs/` directory. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index f230466..fd7d0e5 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,27 +1,13 @@ # Summary - [Home](README.md) -# contracts - - [❱ libraries](contracts/libraries/README.md) - - [Statistics](contracts/libraries/Statistics.sol/library.Statistics.md) - - [❱ llm](contracts/llm/README.md) - - [LLMOracleCoordinator](contracts/llm/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md) - - [LLMOracleManager](contracts/llm/LLMOracleManager.sol/contract.LLMOracleManager.md) - - [LLMOracleKind](contracts/llm/LLMOracleRegistry.sol/enum.LLMOracleKind.md) - - [LLMOracleRegistry](contracts/llm/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md) - - [LLMOracleTaskParameters](contracts/llm/LLMOracleTask.sol/struct.LLMOracleTaskParameters.md) - - [LLMOracleTask](contracts/llm/LLMOracleTask.sol/interface.LLMOracleTask.md) - - [❱ mock](contracts/mock/README.md) - - [LLMOracleCoordinatorV2](contracts/mock/LLMOracleCoordinatorV2.sol/contract.LLMOracleCoordinatorV2.md) - - [LLMOracleRegistryV2](contracts/mock/LLMOracleRegistryV2.sol/contract.LLMOracleRegistryV2.md) - - [SwanV2](contracts/mock/SwanV2.sol/contract.SwanV2.md) - - [❱ swan](contracts/swan/README.md) - - [BuyerAgentFactory](contracts/swan/BuyerAgent.sol/contract.BuyerAgentFactory.md) - - [BuyerAgent](contracts/swan/BuyerAgent.sol/contract.BuyerAgent.md) - - [Swan](contracts/swan/Swan.sol/contract.Swan.md) - - [Swan constants](contracts/swan/Swan.sol/constants.Swan.md) - - [SwanAssetFactory](contracts/swan/SwanAsset.sol/contract.SwanAssetFactory.md) - - [SwanAsset](contracts/swan/SwanAsset.sol/contract.SwanAsset.md) - - [SwanMarketParameters](contracts/swan/SwanManager.sol/struct.SwanMarketParameters.md) - - [SwanManager](contracts/swan/SwanManager.sol/abstract.SwanManager.md) - - [❱ token](contracts/token/README.md) - - [WETH9](contracts/token/WETH9.sol/contract.WETH9.md) +# src + - [❱ mock](src/mock/README.md) + - [SwanV2](src/mock/SvanV2.sol/contract.SwanV2.md) + - [BuyerAgentFactory](src/BuyerAgent.sol/contract.BuyerAgentFactory.md) + - [BuyerAgent](src/BuyerAgent.sol/contract.BuyerAgent.md) + - [Swan](src/Swan.sol/contract.Swan.md) + - [Swan constants](src/Swan.sol/constants.Swan.md) + - [SwanAssetFactory](src/SwanAsset.sol/contract.SwanAssetFactory.md) + - [SwanAsset](src/SwanAsset.sol/contract.SwanAsset.md) + - [SwanMarketParameters](src/SwanManager.sol/struct.SwanMarketParameters.md) + - [SwanManager](src/SwanManager.sol/abstract.SwanManager.md) diff --git a/docs/src/contracts/README.md b/docs/src/contracts/README.md deleted file mode 100644 index 05ba2f8..0000000 --- a/docs/src/contracts/README.md +++ /dev/null @@ -1,8 +0,0 @@ - - -# Contents -- [libraries](/contracts/libraries) -- [llm](/contracts/llm) -- [mock](/contracts/mock) -- [swan](/contracts/swan) -- [token](/contracts/token) diff --git a/docs/src/contracts/libraries/README.md b/docs/src/contracts/libraries/README.md deleted file mode 100644 index d82c024..0000000 --- a/docs/src/contracts/libraries/README.md +++ /dev/null @@ -1,4 +0,0 @@ - - -# Contents -- [Statistics](Statistics.sol/library.Statistics.md) diff --git a/docs/src/contracts/libraries/Statistics.sol/library.Statistics.md b/docs/src/contracts/libraries/Statistics.sol/library.Statistics.md deleted file mode 100644 index 3362ee7..0000000 --- a/docs/src/contracts/libraries/Statistics.sol/library.Statistics.md +++ /dev/null @@ -1,71 +0,0 @@ -# Statistics -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/libraries/Statistics.sol) - -Simple statistic library for uint256 arrays, numbers are treat as fixed-precision floats. - - -## Functions -### avg - -Compute the mean of the data. - - -```solidity -function avg(uint256[] memory data) internal pure returns (uint256 ans); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`data`|`uint256[]`|The data to compute the mean for.| - - -### variance - -Compute the variance of the data. - - -```solidity -function variance(uint256[] memory data) internal pure returns (uint256 ans, uint256 mean); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`data`|`uint256[]`|The data to compute the variance for.| - - -### stddev - -Compute the standard deviation of the data. - -*Computes variance, and takes the square root.* - - -```solidity -function stddev(uint256[] memory data) internal pure returns (uint256 ans, uint256 mean); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`data`|`uint256[]`|The data to compute the standard deviation for.| - - -### sqrt - -Compute the square root of a number. - -*Uses Babylonian method.* - - -```solidity -function sqrt(uint256 x) internal pure returns (uint256 y); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`x`|`uint256`|The number to compute the square root for.| - - diff --git a/docs/src/contracts/llm/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md b/docs/src/contracts/llm/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md deleted file mode 100644 index 0b79004..0000000 --- a/docs/src/contracts/llm/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md +++ /dev/null @@ -1,442 +0,0 @@ -# LLMOracleCoordinator -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/llm/LLMOracleCoordinator.sol) - -**Inherits:** -[LLMOracleTask](/contracts/llm/LLMOracleTask.sol/interface.LLMOracleTask.md), [LLMOracleManager](/contracts/llm/LLMOracleManager.sol/contract.LLMOracleManager.md), UUPSUpgradeable - -Responsible for coordinating the Oracle responses to LLM generation requests. - - -## State Variables -### registry -The Oracle Registry. - - -```solidity -LLMOracleRegistry public registry; -``` - - -### feeToken -The token to be used for fee payments. - - -```solidity -ERC20 public feeToken; -``` - - -### nextTaskId -The task ID counter. - -*TaskId starts from 1, as 0 is reserved.* - -*0 can be used in to check that a request/response/validation has not been made.* - - -```solidity -uint256 public nextTaskId; -``` - - -### requests -LLM generation requests. - - -```solidity -mapping(uint256 taskId => TaskRequest) public requests; -``` - - -### responses -LLM generation responses. - - -```solidity -mapping(uint256 taskId => TaskResponse[]) public responses; -``` - - -### validations -LLM generation response validations. - - -```solidity -mapping(uint256 taskId => TaskValidation[]) public validations; -``` - - -## Functions -### onlyRegistered - -Reverts if `msg.sender` is not a registered oracle. - - -```solidity -modifier onlyRegistered(LLMOracleKind kind); -``` - -### onlyAtStatus - -Reverts if the task status is not `status`. - - -```solidity -modifier onlyAtStatus(uint256 taskId, TaskStatus status); -``` - -### constructor - -Locks the contract, preventing any future re-initialization. - -*[See more](https://docs.openzeppelin.com/contracts/5.x/api/proxy#Initializable-_disableInitializers--).* - -**Note:** -oz-upgrades-unsafe-allow: constructor - - -```solidity -constructor(); -``` - -### _authorizeUpgrade - -Function that should revert when `msg.sender` is not authorized to upgrade the contract. - -*Called by and upgradeToAndCall.* - - -```solidity -function _authorizeUpgrade(address newImplementation) internal override onlyOwner; -``` - -### initialize - -Initialize the contract. - -Sets the Oracle Registry & Oracle Fee Manager. - - -```solidity -function initialize( - address _oracleRegistry, - address _feeToken, - uint256 _platformFee, - uint256 _generationFee, - uint256 _validationFee -) public initializer; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`_oracleRegistry`|`address`|The Oracle Registry contract address.| -|`_feeToken`|`address`|The token (ERC20) to be used for fee payments (usually $BATCH).| -|`_platformFee`|`uint256`|The initial platform fee for each LLM generation.| -|`_generationFee`|`uint256`|The initial base fee for LLM generation.| -|`_validationFee`|`uint256`|The initial base fee for response validation.| - - -### request - -Request LLM generation. - -*Input must be non-empty.* - -*Reverts if contract has not enough allowance for the fee.* - -*Reverts if difficulty is out of range.* - - -```solidity -function request(bytes32 protocol, bytes memory input, bytes memory models, LLMOracleTaskParameters calldata parameters) - public - onlyValidParameters(parameters) - returns (uint256); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`protocol`|`bytes32`|The protocol string, should be a short 32-byte string (e.g., "dria/1.0.0").| -|`input`|`bytes`|The input data for the LLM generation.| -|`models`|`bytes`|| -|`parameters`|`LLMOracleTaskParameters`|The task parameters| - -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|``|`uint256`|task id| - - -### respond - -Respond to an LLM generation. - -*Output must be non-empty.* - -*Reverts if the task is not pending generation.* - -*Reverts if the responder is not registered.* - -*Reverts if the responder has already responded to this task.* - -*Reverts if the nonce is not a valid proof-of-work.* - - -```solidity -function respond(uint256 taskId, uint256 nonce, bytes calldata output, bytes calldata metadata) - public - onlyRegistered(LLMOracleKind.Generator) - onlyAtStatus(taskId, TaskStatus.PendingGeneration); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The task ID to respond to.| -|`nonce`|`uint256`|The proof-of-work nonce.| -|`output`|`bytes`|The output data for the LLM generation.| -|`metadata`|`bytes`|Optional metadata for this output.| - - -### validate - -Validate requests for a given taskId. - -*Reverts if the task is not pending validation.* - -*Reverts if the number of scores is not equal to the number of generations.* - -*Reverts if any score is greater than the maximum score.* - - -```solidity -function validate(uint256 taskId, uint256 nonce, uint256[] calldata scores, bytes calldata metadata) - public - onlyRegistered(LLMOracleKind.Validator) - onlyAtStatus(taskId, TaskStatus.PendingValidation); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The ID of the task to validate.| -|`nonce`|`uint256`|The proof-of-work nonce.| -|`scores`|`uint256[]`|The validation scores for each generation.| -|`metadata`|`bytes`|Optional metadata for this validation.| - - -### assertValidNonce - -Checks that proof-of-work is valid for a given task with taskId and nonce. - -*Reverts if the nonce is not a valid proof-of-work.* - - -```solidity -function assertValidNonce(uint256 taskId, TaskRequest storage task, uint256 nonce) internal view; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The ID of the task to check proof-of-work.| -|`task`|`TaskRequest`|The task (in storage) to validate.| -|`nonce`|`uint256`|The candidate proof-of-work nonce.| - - -### finalizeValidation - -Compute the validation scores for a given task. - -*Reverts if the task has no validations.* - - -```solidity -function finalizeValidation(uint256 taskId) private; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The ID of the task to compute scores for.| - - -### withdrawPlatformFees - -Withdraw the platform fees & along with remaining fees within the contract. - - -```solidity -function withdrawPlatformFees() public onlyOwner; -``` - -### getResponses - -Returns the responses to a given taskId. - - -```solidity -function getResponses(uint256 taskId) public view returns (TaskResponse[] memory); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The ID of the task to get responses for.| - -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|``|`TaskResponse[]`|The responses for the given taskId.| - - -### getValidations - -Returns the validations to a given taskId. - - -```solidity -function getValidations(uint256 taskId) public view returns (TaskValidation[] memory); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The ID of the task to get validations for.| - -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|``|`TaskValidation[]`|The validations for the given taskId.| - - -### _increaseAllowance - -Increases the allowance by setting the approval to the sum of the current allowance and the additional amount. - - -```solidity -function _increaseAllowance(address spender, uint256 amount) internal; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`spender`|`address`|spender address| -|`amount`|`uint256`|additional amount of allowance| - - -### getBestResponse - -Returns the best performing result of the given task. - -*For invalid task IDs, the status check will fail.* - - -```solidity -function getBestResponse(uint256 taskId) external view returns (TaskResponse memory); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`taskId`|`uint256`|The ID of the task to get the result for.| - -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|``|`TaskResponse`|The best performing response w.r.t validation scores.| - - -## Events -### Request -Indicates a generation request for LLM. - -*`protocol` is a short 32-byte string (e.g., "dria/1.0.0").* - -*Using the protocol topic, listeners can filter by protocol.* - - -```solidity -event Request(uint256 indexed taskId, address indexed requester, bytes32 indexed protocol); -``` - -### Response -Indicates a single Oracle response for a request. - - -```solidity -event Response(uint256 indexed taskId, address indexed responder); -``` - -### Validation -Indicates a single Oracle response for a request. - - -```solidity -event Validation(uint256 indexed taskId, address indexed validator); -``` - -### StatusUpdate -Indicates the status change of an LLM generation request. - - -```solidity -event StatusUpdate(uint256 indexed taskId, bytes32 indexed protocol, TaskStatus statusBefore, TaskStatus statusAfter); -``` - -## Errors -### InsufficientFees -Not enough funds were provided for the task. - - -```solidity -error InsufficientFees(uint256 have, uint256 want); -``` - -### InvalidTaskStatus -Unexpected status for this task. - - -```solidity -error InvalidTaskStatus(uint256 taskId, TaskStatus have, TaskStatus want); -``` - -### InvalidNonce -The given nonce is not a valid proof-of-work. - - -```solidity -error InvalidNonce(uint256 taskId, uint256 nonce); -``` - -### InvalidValidation -The provided validation does not have a score for all responses. - - -```solidity -error InvalidValidation(uint256 taskId, address validator); -``` - -### NotRegistered -The oracle is not registered. - - -```solidity -error NotRegistered(address oracle); -``` - -### AlreadyResponded -The oracle has already responded to this task. - - -```solidity -error AlreadyResponded(uint256 taskId, address oracle); -``` - diff --git a/docs/src/contracts/llm/LLMOracleManager.sol/contract.LLMOracleManager.md b/docs/src/contracts/llm/LLMOracleManager.sol/contract.LLMOracleManager.md deleted file mode 100644 index 468b523..0000000 --- a/docs/src/contracts/llm/LLMOracleManager.sol/contract.LLMOracleManager.md +++ /dev/null @@ -1,200 +0,0 @@ -# LLMOracleManager -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/llm/LLMOracleManager.sol) - -**Inherits:** -OwnableUpgradeable - -Holds the configuration for the LLM Oracle, such as allowed bounds on difficulty, -number of generations & validations, and fee settings. - - -## State Variables -### platformFee -A fixed fee paid for the platform. - - -```solidity -uint256 public platformFee; -``` - - -### generationFee -The base fee factor for a generation of LLM generation. - -*When scaled with difficulty & number of generations, we denote it as `generatorFee`.* - - -```solidity -uint256 public generationFee; -``` - - -### validationFee -The base fee factor for a generation of LLM validation. - -*When scaled with difficulty & number of validations, we denote it as `validatorFee`.* - - -```solidity -uint256 public validationFee; -``` - - -### validationDeviationFactor -The deviation factor for the validation scores. - - -```solidity -uint64 public validationDeviationFactor; -``` - - -### generationDeviationFactor -The deviation factor for the generation scores. - - -```solidity -uint64 public generationDeviationFactor; -``` - - -### minimumParameters -Minimums for oracle parameters. - - -```solidity -LLMOracleTaskParameters minimumParameters; -``` - - -### maximumParameters -Maximums for oracle parameters. - - -```solidity -LLMOracleTaskParameters maximumParameters; -``` - - -## Functions -### __LLMOracleManager_init - -Initialize the contract. - - -```solidity -function __LLMOracleManager_init(uint256 _platformFee, uint256 _generationFee, uint256 _validationFee) - internal - onlyInitializing; -``` - -### __LLMOracleManager_init_unchained - - -```solidity -function __LLMOracleManager_init_unchained(uint256 _platformFee, uint256 _generationFee, uint256 _validationFee) - internal - onlyInitializing; -``` - -### onlyValidParameters - -Modifier to check if the given parameters are within the allowed range. - - -```solidity -modifier onlyValidParameters(LLMOracleTaskParameters calldata parameters); -``` - -### setFees - -Update Oracle fees. - -*To keep a fee unchanged, provide the same value.* - - -```solidity -function setFees(uint256 _platformFee, uint256 _generationFee, uint256 _validationFee) public onlyOwner; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`_platformFee`|`uint256`|The new platform fee| -|`_generationFee`|`uint256`|The new generation fee| -|`_validationFee`|`uint256`|The new validation fee| - - -### getFee - -Get the total fee for a given task setting. - - -```solidity -function getFee(LLMOracleTaskParameters calldata parameters) - public - view - returns (uint256 totalFee, uint256 generatorFee, uint256 validatorFee); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`parameters`|`LLMOracleTaskParameters`|The task parameters.| - -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|`totalFee`|`uint256`|The total fee for the task.| -|`generatorFee`|`uint256`|The fee paid to each generator per generation.| -|`validatorFee`|`uint256`|The fee paid to each validator per validated generation.| - - -### setParameters - -Update Oracle parameters bounds. - -*Provide the same value to keep it unchanged.* - - -```solidity -function setParameters(LLMOracleTaskParameters calldata minimums, LLMOracleTaskParameters calldata maximums) - public - onlyOwner; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`minimums`|`LLMOracleTaskParameters`|The new minimum parameters.| -|`maximums`|`LLMOracleTaskParameters`|The new maximum parameters.| - - -### setDeviationFactors - -Update deviation factors. - -*Provide the same value to keep it unchanged.* - - -```solidity -function setDeviationFactors(uint64 _generationDeviationFactor, uint64 _validationDeviationFactor) public onlyOwner; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`_generationDeviationFactor`|`uint64`|The new generation deviation factor.| -|`_validationDeviationFactor`|`uint64`|The new validation deviation factor.| - - -## Errors -### InvalidParameterRange -Given parameter is out of range. - - -```solidity -error InvalidParameterRange(uint256 have, uint256 min, uint256 max); -``` - diff --git a/docs/src/contracts/llm/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md b/docs/src/contracts/llm/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md deleted file mode 100644 index 9ef6a33..0000000 --- a/docs/src/contracts/llm/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md +++ /dev/null @@ -1,194 +0,0 @@ -# LLMOracleRegistry -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/llm/LLMOracleRegistry.sol) - -**Inherits:** -OwnableUpgradeable, UUPSUpgradeable - -Holds the addresses that are eligible to respond to LLM requests. - -*There may be several types of oracle kinds, and each require their own stake.* - - -## State Variables -### generatorStakeAmount -Stake amount to be registered as an Oracle that can serve generation requests. - - -```solidity -uint256 public generatorStakeAmount; -``` - - -### validatorStakeAmount -Stake amount to be registered as an Oracle that can serve validation requests. - - -```solidity -uint256 public validatorStakeAmount; -``` - - -### registrations -Registrations per address & kind. If amount is 0, it is not registered. - - -```solidity -mapping(address oracle => mapping(LLMOracleKind => uint256 amount)) public registrations; -``` - - -### token -Token used for staking. - - -```solidity -ERC20 public token; -``` - - -## Functions -### constructor - -Locks the contract, preventing any future re-initialization. - -*[See more](https://docs.openzeppelin.com/contracts/5.x/api/proxy#Initializable-_disableInitializers--).* - -**Note:** -oz-upgrades-unsafe-allow: constructor - - -```solidity -constructor(); -``` - -### _authorizeUpgrade - -Function that should revert when `msg.sender` is not authorized to upgrade the contract. - -*Called by and upgradeToAndCall.* - - -```solidity -function _authorizeUpgrade(address newImplementation) internal override onlyOwner; -``` - -### initialize - -*Sets the owner to be the deployer, sets initial stake amount.* - - -```solidity -function initialize(uint256 _generatorStakeAmount, uint256 _validatorStakeAmount, address _token) public initializer; -``` - -### register - -Register an Oracle. - -*Reverts if the user is already registered or has insufficient funds.* - - -```solidity -function register(LLMOracleKind kind) public; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`kind`|`LLMOracleKind`|The kind of Oracle to unregister.| - - -### unregister - -Remove registration of an Oracle. - -*Reverts if the user is not registered.* - - -```solidity -function unregister(LLMOracleKind kind) public returns (uint256 amount); -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`kind`|`LLMOracleKind`|The kind of Oracle to unregister.| - -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|`amount`|`uint256`|Amount of stake approved back.| - - -### setStakeAmounts - -Set the stake amount required to register as an Oracle. - -*Only allowed by the owner.* - - -```solidity -function setStakeAmounts(uint256 _generatorStakeAmount, uint256 _validatorStakeAmount) public onlyOwner; -``` - -### getStakeAmount - -Returns the stake amount required to register as an Oracle w.r.t given kind. - - -```solidity -function getStakeAmount(LLMOracleKind kind) public view returns (uint256); -``` - -### isRegistered - -Check if an Oracle is registered. - - -```solidity -function isRegistered(address user, LLMOracleKind kind) public view returns (bool); -``` - -## Events -### Registered -The Oracle response to an LLM generation request. - - -```solidity -event Registered(address indexed, LLMOracleKind kind); -``` - -### Unregistered -The Oracle response to an LLM generation request. - - -```solidity -event Unregistered(address indexed, LLMOracleKind kind); -``` - -## Errors -### NotRegistered -The user is not registered. - - -```solidity -error NotRegistered(address); -``` - -### AlreadyRegistered -The user is already registered. - - -```solidity -error AlreadyRegistered(address); -``` - -### InsufficientFunds -Insufficient stake amount during registration. - - -```solidity -error InsufficientFunds(); -``` - diff --git a/docs/src/contracts/llm/LLMOracleRegistry.sol/enum.LLMOracleKind.md b/docs/src/contracts/llm/LLMOracleRegistry.sol/enum.LLMOracleKind.md deleted file mode 100644 index 70df3c6..0000000 --- a/docs/src/contracts/llm/LLMOracleRegistry.sol/enum.LLMOracleKind.md +++ /dev/null @@ -1,13 +0,0 @@ -# LLMOracleKind -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/llm/LLMOracleRegistry.sol) - -The type of Oracle. - - -```solidity -enum LLMOracleKind { - Generator, - Validator -} -``` - diff --git a/docs/src/contracts/llm/LLMOracleTask.sol/interface.LLMOracleTask.md b/docs/src/contracts/llm/LLMOracleTask.sol/interface.LLMOracleTask.md deleted file mode 100644 index d833379..0000000 --- a/docs/src/contracts/llm/LLMOracleTask.sol/interface.LLMOracleTask.md +++ /dev/null @@ -1,80 +0,0 @@ -# LLMOracleTask -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/llm/LLMOracleTask.sol) - -An umbrella interface that captures task-related structs and enums. - - -## Structs -### TaskRequest -A task request for LLM generation. - -*Fees are stored here as well in case fee changes occur within the duration of a task.* - - -```solidity -struct TaskRequest { - address requester; - bytes32 protocol; - LLMOracleTaskParameters parameters; - TaskStatus status; - uint256 generatorFee; - uint256 validatorFee; - uint256 platformFee; - bytes input; - bytes models; -} -``` - -### TaskResponse -A task response to an LLM generation request. - - -```solidity -struct TaskResponse { - address responder; - uint256 nonce; - uint256 score; - bytes output; - bytes metadata; -} -``` - -### TaskValidation -A task validation for a response. - - -```solidity -struct TaskValidation { - address validator; - uint256 nonce; - uint256[] scores; - bytes metadata; -} -``` - -## Enums -### TaskStatus -Task status. - -*`None`: Task has not been created yet. (default)* - -*`PendingGeneration`: Task is waiting for Oracle generation responses.* - -*`PendingValidation`: Task is waiting for validation by validator Oracles.* - -*`Completed`: The task has been completed.* - -*With validation, the flow is `None -> PendingGeneration -> PendingValidation -> Completed`.* - -*Without validation, the flow is `None -> PendingGeneration -> Completed`.* - - -```solidity -enum TaskStatus { - None, - PendingGeneration, - PendingValidation, - Completed -} -``` - diff --git a/docs/src/contracts/llm/LLMOracleTask.sol/struct.LLMOracleTaskParameters.md b/docs/src/contracts/llm/LLMOracleTask.sol/struct.LLMOracleTaskParameters.md deleted file mode 100644 index efa9807..0000000 --- a/docs/src/contracts/llm/LLMOracleTask.sol/struct.LLMOracleTaskParameters.md +++ /dev/null @@ -1,17 +0,0 @@ -# LLMOracleTaskParameters -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/llm/LLMOracleTask.sol) - -Collection of oracle task-related parameters. - -*Prevents stack-too-deep with tight-packing. -TODO: use 256-bit tight-packing here* - - -```solidity -struct LLMOracleTaskParameters { - uint8 difficulty; - uint40 numGenerations; - uint40 numValidations; -} -``` - diff --git a/docs/src/contracts/llm/README.md b/docs/src/contracts/llm/README.md deleted file mode 100644 index db5cccc..0000000 --- a/docs/src/contracts/llm/README.md +++ /dev/null @@ -1,9 +0,0 @@ - - -# Contents -- [LLMOracleCoordinator](LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md) -- [LLMOracleManager](LLMOracleManager.sol/contract.LLMOracleManager.md) -- [LLMOracleKind](LLMOracleRegistry.sol/enum.LLMOracleKind.md) -- [LLMOracleRegistry](LLMOracleRegistry.sol/contract.LLMOracleRegistry.md) -- [LLMOracleTaskParameters](LLMOracleTask.sol/struct.LLMOracleTaskParameters.md) -- [LLMOracleTask](LLMOracleTask.sol/interface.LLMOracleTask.md) diff --git a/docs/src/contracts/mock/LLMOracleCoordinatorV2.sol/contract.LLMOracleCoordinatorV2.md b/docs/src/contracts/mock/LLMOracleCoordinatorV2.sol/contract.LLMOracleCoordinatorV2.md deleted file mode 100644 index 68652e9..0000000 --- a/docs/src/contracts/mock/LLMOracleCoordinatorV2.sol/contract.LLMOracleCoordinatorV2.md +++ /dev/null @@ -1,15 +0,0 @@ -# LLMOracleCoordinatorV2 -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/mock/LLMOracleCoordinatorV2.sol) - -**Inherits:** -[LLMOracleCoordinator](/contracts/llm/LLMOracleCoordinator.sol/contract.LLMOracleCoordinator.md) - - -## Functions -### upgraded - - -```solidity -function upgraded() public view virtual returns (bool); -``` - diff --git a/docs/src/contracts/mock/LLMOracleRegistryV2.sol/contract.LLMOracleRegistryV2.md b/docs/src/contracts/mock/LLMOracleRegistryV2.sol/contract.LLMOracleRegistryV2.md deleted file mode 100644 index bbcf792..0000000 --- a/docs/src/contracts/mock/LLMOracleRegistryV2.sol/contract.LLMOracleRegistryV2.md +++ /dev/null @@ -1,15 +0,0 @@ -# LLMOracleRegistryV2 -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/mock/LLMOracleRegistryV2.sol) - -**Inherits:** -[LLMOracleRegistry](/contracts/llm/LLMOracleRegistry.sol/contract.LLMOracleRegistry.md) - - -## Functions -### upgraded - - -```solidity -function upgraded() public view virtual returns (bool); -``` - diff --git a/docs/src/contracts/mock/README.md b/docs/src/contracts/mock/README.md deleted file mode 100644 index 839d223..0000000 --- a/docs/src/contracts/mock/README.md +++ /dev/null @@ -1,6 +0,0 @@ - - -# Contents -- [LLMOracleCoordinatorV2](LLMOracleCoordinatorV2.sol/contract.LLMOracleCoordinatorV2.md) -- [LLMOracleRegistryV2](LLMOracleRegistryV2.sol/contract.LLMOracleRegistryV2.md) -- [SwanV2](SwanV2.sol/contract.SwanV2.md) diff --git a/docs/src/contracts/token/README.md b/docs/src/contracts/token/README.md deleted file mode 100644 index 85822f0..0000000 --- a/docs/src/contracts/token/README.md +++ /dev/null @@ -1,4 +0,0 @@ - - -# Contents -- [WETH9](WETH9.sol/contract.WETH9.md) diff --git a/docs/src/contracts/token/WETH9.sol/contract.WETH9.md b/docs/src/contracts/token/WETH9.sol/contract.WETH9.md deleted file mode 100644 index 9579178..0000000 --- a/docs/src/contracts/token/WETH9.sol/contract.WETH9.md +++ /dev/null @@ -1,115 +0,0 @@ -# WETH9 -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/token/WETH9.sol) - - -## State Variables -### name - -```solidity -string public name = "Wrapped Ether"; -``` - - -### symbol - -```solidity -string public symbol = "WETH"; -``` - - -### decimals - -```solidity -uint8 public decimals = 18; -``` - - -### balanceOf - -```solidity -mapping(address => uint256) public balanceOf; -``` - - -### allowance - -```solidity -mapping(address => mapping(address => uint256)) public allowance; -``` - - -## Functions -### receive - - -```solidity -receive() external payable; -``` - -### deposit - - -```solidity -function deposit() public payable; -``` - -### withdraw - - -```solidity -function withdraw(uint256 wad) public; -``` - -### totalSupply - - -```solidity -function totalSupply() public view returns (uint256); -``` - -### approve - - -```solidity -function approve(address guy, uint256 wad) public returns (bool); -``` - -### transfer - - -```solidity -function transfer(address dst, uint256 wad) public returns (bool); -``` - -### transferFrom - - -```solidity -function transferFrom(address src, address dst, uint256 wad) public returns (bool); -``` - -## Events -### Approval - -```solidity -event Approval(address indexed src, address indexed guy, uint256 wad); -``` - -### Transfer - -```solidity -event Transfer(address indexed src, address indexed dst, uint256 wad); -``` - -### Deposit - -```solidity -event Deposit(address indexed dst, uint256 wad); -``` - -### Withdrawal - -```solidity -event Withdrawal(address indexed src, uint256 wad); -``` - diff --git a/docs/src/contracts/swan/BuyerAgent.sol/contract.BuyerAgent.md b/docs/src/src/BuyerAgent.sol/contract.BuyerAgent.md similarity index 90% rename from docs/src/contracts/swan/BuyerAgent.sol/contract.BuyerAgent.md rename to docs/src/src/BuyerAgent.sol/contract.BuyerAgent.md index 67d3aef..1f81dce 100644 --- a/docs/src/contracts/swan/BuyerAgent.sol/contract.BuyerAgent.md +++ b/docs/src/src/BuyerAgent.sol/contract.BuyerAgent.md @@ -1,8 +1,8 @@ # BuyerAgent -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/BuyerAgent.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/BuyerAgent.sol) **Inherits:** -Ownable, IERC721Receiver +Ownable BuyerAgent is responsible for buying the assets from Swan. @@ -66,12 +66,12 @@ bytes public state; ``` -### royaltyFee +### feeRoyalty Royalty fees for the buyer agent. ```solidity -uint96 public royaltyFee; +uint96 public feeRoyalty; ``` @@ -155,7 +155,7 @@ modifier onlyAuthorized(); Create the buyer agent. -*`_royaltyFee` should be between 1 and 100.* +*`_feeRoyalty` should be between 1 and maxBuyerAgentFee in the swan market parameters.* *All tokens are approved to the oracle coordinator of operator.* @@ -164,29 +164,18 @@ Create the buyer agent. constructor( string memory _name, string memory _description, - uint96 _royaltyFee, + uint96 _feeRoyalty, uint256 _amountPerRound, address _operator, address _owner ) Ownable(_owner); ``` -### onERC721Received - -Function to receive ERC721 tokens via safe transfer. - -*[See more](https://eips.ethereum.org/EIPS/eip-721).* - - -```solidity -function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4); -``` - ### minFundAmount The minimum amount of money that the buyer must leave within the contract. -*minFundAmount = amountPerRound + 2 * oracleTotalFee* +*minFundAmount should be `amountPerRound + oracleFee` to be able to make requests.* ```solidity @@ -412,13 +401,13 @@ Function to set feeRoyalty. ```solidity -function setFeeRoyalty(uint96 _fee) public onlyOwner; +function setFeeRoyalty(uint96 newFeeRoyalty) public onlyOwner; ``` **Parameters** |Name|Type|Description| |----|----|-----------| -|`_fee`|`uint96`|new feeRoyalty, must be between 1 and 100.| +|`newFeeRoyalty`|`uint96`|must be between 1 and 100.| ### setAmountPerRound @@ -440,6 +429,39 @@ function setAmountPerRound(uint256 _amountPerRound) external onlyOwner; |`_amountPerRound`|`uint256`|new amountPerRound.| +## Events +### StateRequest +Emitted when a state update request is made. + + +```solidity +event StateRequest(uint256 indexed taskId, uint256 indexed round); +``` + +### PurchaseRequest +Emitted when a purchase request is made. + + +```solidity +event PurchaseRequest(uint256 indexed taskId, uint256 indexed round); +``` + +### Purchase +Emitted when a purchase is made. + + +```solidity +event Purchase(uint256 indexed taskId, uint256 indexed round); +``` + +### StateUpdate +Emitted when the state is updated. + + +```solidity +event StateUpdate(uint256 indexed taskId, uint256 indexed round); +``` + ## Errors ### MinFundSubceeded The `value` is less than `minFundAmount` diff --git a/docs/src/contracts/swan/BuyerAgent.sol/contract.BuyerAgentFactory.md b/docs/src/src/BuyerAgent.sol/contract.BuyerAgentFactory.md similarity index 79% rename from docs/src/contracts/swan/BuyerAgent.sol/contract.BuyerAgentFactory.md rename to docs/src/src/BuyerAgent.sol/contract.BuyerAgentFactory.md index 290782d..d00c431 100644 --- a/docs/src/contracts/swan/BuyerAgent.sol/contract.BuyerAgentFactory.md +++ b/docs/src/src/BuyerAgent.sol/contract.BuyerAgentFactory.md @@ -1,5 +1,5 @@ # BuyerAgentFactory -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/BuyerAgent.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/BuyerAgent.sol) Factory contract to deploy BuyerAgent contracts. @@ -14,7 +14,7 @@ Factory contract to deploy BuyerAgent contracts. function deploy( string memory _name, string memory _description, - uint96 _royaltyFee, + uint96 _feeRoyalty, uint256 _amountPerRound, address _owner ) external returns (BuyerAgent); diff --git a/docs/src/contracts/swan/README.md b/docs/src/src/README.md similarity index 95% rename from docs/src/contracts/swan/README.md rename to docs/src/src/README.md index 04ba089..d461732 100644 --- a/docs/src/contracts/swan/README.md +++ b/docs/src/src/README.md @@ -1,6 +1,7 @@ # Contents +- [mock](/src/mock) - [BuyerAgentFactory](BuyerAgent.sol/contract.BuyerAgentFactory.md) - [BuyerAgent](BuyerAgent.sol/contract.BuyerAgent.md) - [Swan](Swan.sol/contract.Swan.md) diff --git a/docs/src/contracts/swan/Swan.sol/constants.Swan.md b/docs/src/src/Swan.sol/constants.Swan.md similarity index 60% rename from docs/src/contracts/swan/Swan.sol/constants.Swan.md rename to docs/src/src/Swan.sol/constants.Swan.md index 91a810e..84c2815 100644 --- a/docs/src/contracts/swan/Swan.sol/constants.Swan.md +++ b/docs/src/src/Swan.sol/constants.Swan.md @@ -1,5 +1,5 @@ # Constants -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/Swan.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/Swan.sol) ### SwanBuyerPurchaseOracleProtocol @@ -13,3 +13,11 @@ bytes32 constant SwanBuyerPurchaseOracleProtocol = "swan-buyer-purchase/0.1.0"; bytes32 constant SwanBuyerStateOracleProtocol = "swan-buyer-state/0.1.0"; ``` +### BASIS_POINTS +*Used to calculate the fee for the buyer agent to be able to compute correct amount.* + + +```solidity +uint256 constant BASIS_POINTS = 10_000; +``` + diff --git a/docs/src/contracts/swan/Swan.sol/contract.Swan.md b/docs/src/src/Swan.sol/contract.Swan.md similarity index 82% rename from docs/src/contracts/swan/Swan.sol/contract.Swan.md rename to docs/src/src/Swan.sol/contract.Swan.md index 2737c62..143a5b3 100644 --- a/docs/src/contracts/swan/Swan.sol/contract.Swan.md +++ b/docs/src/src/Swan.sol/contract.Swan.md @@ -1,11 +1,29 @@ # Swan -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/Swan.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/Swan.sol) **Inherits:** -[SwanManager](/contracts/swan/SwanManager.sol/abstract.SwanManager.md), UUPSUpgradeable, IERC721Receiver +[SwanManager](/src/SwanManager.sol/abstract.SwanManager.md), UUPSUpgradeable ## State Variables +### buyerAgentFactory +Factory contract to deploy Buyer Agents. + + +```solidity +BuyerAgentFactory public buyerAgentFactory; +``` + + +### swanAssetFactory +Factory contract to deploy SwanAsset tokens. + + +```solidity +SwanAssetFactory public swanAssetFactory; +``` + + ### listings To keep track of the assets for purchase. @@ -39,17 +57,6 @@ oz-upgrades-unsafe-allow: constructor constructor(); ``` -### onERC721Received - -Function to receive ERC721 tokens via safe transfer. - -*[See more](https://eips.ethereum.org/EIPS/eip-721).* - - -```solidity -function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4); -``` - ### _authorizeUpgrade Upgrades to contract with a new implementation. @@ -83,6 +90,42 @@ function initialize( ) public initializer; ``` +### transferOwnership + +Transfer ownership of the contract. + +*Overrides the default `transferOwnership` function to make the new owner an operator.* + + +```solidity +function transferOwnership(address newOwner) public override onlyOwner; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`newOwner`|`address`|address of the new owner.| + + +### createBuyer + +Creates a new buyer agent. + +*Emits a `BuyerCreated` event.* + + +```solidity +function createBuyer(string calldata _name, string calldata _description, uint96 _feeRoyalty, uint256 _amountPerRound) + external + returns (BuyerAgent); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`BuyerAgent`|address of the new buyer agent.| + + ### list Creates a new Asset. @@ -140,15 +183,27 @@ Executes the purchase of a listing for a buyer for the given asset. function purchase(address _asset) external; ``` -### getListingPrice +### setFactories -Returns the asset status with the given asset address. +Set the factories for Buyer Agents and Swan Assets. -*Active: If the asset has not been purchased or the next round has not started.* +*Only callable by owner.* -*Inactive: If the assets's purchaseRound has passed or delisted by the creator of the asset.* -*Sold: If the asset has already been purchased by the buyer.* +```solidity +function setFactories(address _buyerAgentFactory, address _swanAssetFactory) external onlyOwner; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`_buyerAgentFactory`|`address`|new BuyerAgentFactory address| +|`_swanAssetFactory`|`address`|new SwanAssetFactory address| + + +### getListingPrice + +Returns the asset price with the given asset address. ```solidity @@ -159,8 +214,6 @@ function getListingPrice(address _asset) external view returns (uint256); Returns the number of assets with the given buyer and round. -*Assets can be assumed to be* - ```solidity function getListedAssets(address _buyer, uint256 _round) external view returns (address[] memory); @@ -175,25 +228,6 @@ Returns the asset listing with the given asset address. function getListing(address _asset) external view returns (AssetListing memory); ``` -### createBuyer - -Creates a new buyer agent. - -*Emits a `BuyerCreated` event.* - - -```solidity -function createBuyer(string calldata _name, string calldata _description, uint96 _feeRoyalty, uint256 _amountPerRound) - external - returns (BuyerAgent); -``` -**Returns** - -|Name|Type|Description| -|----|----|-----------| -|``|`BuyerAgent`|address of the new buyer agent.| - - ## Events ### AssetListed `asset` is created & listed for sale. @@ -283,7 +317,7 @@ Holds the listing information. *`createdAt` is the timestamp of the Asset creation.* -*`royaltyFee` is the royaltyFee of the buyerAgent.* +*`feeRoyalty` is the royalty fee of the buyerAgent.* *`price` is the price of the Asset.* @@ -299,7 +333,7 @@ Holds the listing information. ```solidity struct AssetListing { uint256 createdAt; - uint96 royaltyFee; + uint96 feeRoyalty; uint256 price; address seller; address buyer; diff --git a/docs/src/contracts/swan/SwanAsset.sol/contract.SwanAsset.md b/docs/src/src/SwanAsset.sol/contract.SwanAsset.md similarity index 89% rename from docs/src/contracts/swan/SwanAsset.sol/contract.SwanAsset.md rename to docs/src/src/SwanAsset.sol/contract.SwanAsset.md index 48b2ffa..03a88b9 100644 --- a/docs/src/contracts/swan/SwanAsset.sol/contract.SwanAsset.md +++ b/docs/src/src/SwanAsset.sol/contract.SwanAsset.md @@ -1,5 +1,5 @@ # SwanAsset -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/SwanAsset.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/SwanAsset.sol) **Inherits:** ERC721, Ownable diff --git a/docs/src/contracts/swan/SwanAsset.sol/contract.SwanAssetFactory.md b/docs/src/src/SwanAsset.sol/contract.SwanAssetFactory.md similarity index 84% rename from docs/src/contracts/swan/SwanAsset.sol/contract.SwanAssetFactory.md rename to docs/src/src/SwanAsset.sol/contract.SwanAssetFactory.md index 5959955..d2b1f9a 100644 --- a/docs/src/contracts/swan/SwanAsset.sol/contract.SwanAssetFactory.md +++ b/docs/src/src/SwanAsset.sol/contract.SwanAssetFactory.md @@ -1,5 +1,5 @@ # SwanAssetFactory -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/SwanAsset.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/SwanAsset.sol) Factory contract to deploy SwanAsset tokens. diff --git a/docs/src/contracts/swan/SwanManager.sol/abstract.SwanManager.md b/docs/src/src/SwanManager.sol/abstract.SwanManager.md similarity index 79% rename from docs/src/contracts/swan/SwanManager.sol/abstract.SwanManager.md rename to docs/src/src/SwanManager.sol/abstract.SwanManager.md index 2cd228e..779f276 100644 --- a/docs/src/contracts/swan/SwanManager.sol/abstract.SwanManager.md +++ b/docs/src/src/SwanManager.sol/abstract.SwanManager.md @@ -1,5 +1,5 @@ # SwanManager -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/SwanManager.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/SwanManager.sol) **Inherits:** OwnableUpgradeable @@ -24,24 +24,6 @@ LLMOracleTaskParameters oracleParameters; ``` -### buyerAgentFactory -Factory contract to deploy Buyer Agents. - - -```solidity -BuyerAgentFactory public buyerAgentFactory; -``` - - -### swanAssetFactory -Factory contract to deploy SwanAsset tokens. - - -```solidity -SwanAssetFactory public swanAssetFactory; -``` - - ### coordinator LLM Oracle Coordinator. @@ -85,13 +67,6 @@ oz-upgrades-unsafe-allow: constructor constructor(); ``` -### __SwanManager_init - - -```solidity -function __SwanManager_init(address _owner) public onlyInitializing; -``` - ### getMarketParameters Returns the market parameters in memory. @@ -155,24 +130,6 @@ Returns the total fee required to make an oracle request. function getOracleFee() external view returns (uint256); ``` -### setFactories - -Set the factories for Buyer Agents and Swan Assets. - -*Only callable by owner.* - - -```solidity -function setFactories(address _buyerAgentFactory, address _swanAssetFactory) external onlyOwner; -``` -**Parameters** - -|Name|Type|Description| -|----|----|-----------| -|`_buyerAgentFactory`|`address`|new BuyerAgentFactory address| -|`_swanAssetFactory`|`address`|new SwanAssetFactory address| - - ### addOperator Adds an operator that can take actions on behalf of Buyer agents. diff --git a/docs/src/contracts/swan/SwanManager.sol/struct.SwanMarketParameters.md b/docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md similarity index 82% rename from docs/src/contracts/swan/SwanManager.sol/struct.SwanMarketParameters.md rename to docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md index f6c96b1..c861e63 100644 --- a/docs/src/contracts/swan/SwanManager.sol/struct.SwanMarketParameters.md +++ b/docs/src/src/SwanManager.sol/struct.SwanMarketParameters.md @@ -1,5 +1,5 @@ # SwanMarketParameters -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/swan/SwanManager.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/SwanManager.sol) Collection of market-related parameters. @@ -16,6 +16,7 @@ struct SwanMarketParameters { uint256 maxAssetCount; uint256 minAssetPrice; uint256 timestamp; + uint8 maxBuyerAgentFee; } ``` diff --git a/docs/src/src/mock/README.md b/docs/src/src/mock/README.md new file mode 100644 index 0000000..99b6b4b --- /dev/null +++ b/docs/src/src/mock/README.md @@ -0,0 +1,4 @@ + + +# Contents +- [SwanV2](SvanV2.sol/contract.SwanV2.md) diff --git a/docs/src/contracts/mock/SwanV2.sol/contract.SwanV2.md b/docs/src/src/mock/SvanV2.sol/contract.SwanV2.md similarity index 61% rename from docs/src/contracts/mock/SwanV2.sol/contract.SwanV2.md rename to docs/src/src/mock/SvanV2.sol/contract.SwanV2.md index e1fbf66..54d7227 100644 --- a/docs/src/contracts/mock/SwanV2.sol/contract.SwanV2.md +++ b/docs/src/src/mock/SvanV2.sol/contract.SwanV2.md @@ -1,8 +1,8 @@ # SwanV2 -[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/ceefa4b0353ce4c0f1536b7318fa82b208305342/contracts/mock/SwanV2.sol) +[Git Source](https://github.com/firstbatchxyz/swan-contracts/blob/b941dcd71134f5be2e73ec6ee0a8aa50cf333ffb/src/mock/SvanV2.sol) **Inherits:** -[Swan](/contracts/swan/Swan.sol/contract.Swan.md) +[Swan](/src/Swan.sol/contract.Swan.md) ## Functions diff --git a/foundry.toml b/foundry.toml index 02cbda5..0cb2f58 100644 --- a/foundry.toml +++ b/foundry.toml @@ -1,5 +1,5 @@ [profile.default] -src = 'contracts' +src = 'src' lib = 'lib' test = 'test' script = 'script'