diff --git a/astro.config.mjs b/astro.config.mjs index eb44994..27d5c6a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -50,7 +50,6 @@ export default defineConfig({ }, { label: "Solvers", - badge: "Outdated", autogenerate: { directory: "solver", }, diff --git a/src/content/docs/implementation/1-input-settlement.md b/src/content/docs/implementation/01-input-settlement.md similarity index 88% rename from src/content/docs/implementation/1-input-settlement.md rename to src/content/docs/implementation/01-input-settlement.md index ea9f7a8..000e6f5 100644 --- a/src/content/docs/implementation/1-input-settlement.md +++ b/src/content/docs/implementation/01-input-settlement.md @@ -81,6 +81,21 @@ function finaliseFor( Notice that the fallback functions exist to fix orders that have been solved by multiple solvers. This is required because we need to hydrate the OutputDescription with the solver to check if the output has been filled on the Validation Layer. +There are 3 ways to finalise an intent: +1. Self-serve, called by the solver with the tokens paid to the solver. `finaliseSelf` +2. Self-serve, custom delivery. Called by the solver with the tokens paid to a specific address. `FinaliseTo` +3. External finalisation with signed message by the solver designating where assets are to be delivered. `finaliseFor` + +To use external finalisation, the struct, `AllowOpen` have to be EIP712 signed: +```solidity +struct AllowOpen { + bytes32 orderId; + address originSettler; + address destination; + bytes call; +} +``` + ### Registering Intents For how to register intents with Rhinestone, please refer to their docs. diff --git a/src/content/docs/implementation/2-output-settlement.mdx b/src/content/docs/implementation/02-output-settlement.mdx similarity index 100% rename from src/content/docs/implementation/2-output-settlement.mdx rename to src/content/docs/implementation/02-output-settlement.mdx diff --git a/src/content/docs/implementation/3-validation-layers.md b/src/content/docs/implementation/03-validation-layers.md similarity index 100% rename from src/content/docs/implementation/3-validation-layers.md rename to src/content/docs/implementation/03-validation-layers.md diff --git a/src/content/docs/implementation/999-calls.mdx b/src/content/docs/implementation/99-calls.mdx similarity index 99% rename from src/content/docs/implementation/999-calls.mdx rename to src/content/docs/implementation/99-calls.mdx index 5dd71fb..d817cdd 100644 --- a/src/content/docs/implementation/999-calls.mdx +++ b/src/content/docs/implementation/99-calls.mdx @@ -3,7 +3,7 @@ title: "Sub-Calls via Catalyst" slug: "implementation/calls" description: "By default, Catalyst supports calls on delivery. While the system does not define these, the default output types contain fields to facilitate secondary execution." sidebar: - order: 999 + order: 99 --- The default output type of Catalyst, called `OutputDescription` supports secondary calls. This allows you to schedule calldata to be executed after the delivery of the asset. diff --git a/src/content/docs/knowledge/2-resource-locks.mdx b/src/content/docs/knowledge/2-resource-locks.mdx index ab8206c..eb33734 100644 --- a/src/content/docs/knowledge/2-resource-locks.mdx +++ b/src/content/docs/knowledge/2-resource-locks.mdx @@ -23,23 +23,26 @@ Depending on the resource lock system, each user chooses an allocator and each l Think of a lock as a time-bound approval, co-signed by an allocator, to a specific protocol (arbiter). -While resource lock flows can look very different depending on the application, they generally following X steps: +While resource lock flows can look very different depending on the application, they generally follow 4 steps: +import { Card } from '@astrojs/starlight/components'; import { Steps } from '@astrojs/starlight/components'; - + + -0. The **sponsor** makes a deposit into a resource lock, if one does not already exist. + 0. The **sponsor** makes a deposit into a resource lock, if one does not already exist. -1. The **sponsor** signs a lock that describes a desired outcome. + 1. The **sponsor** signs a lock that describes a desired outcome. -2. The **allocator** ensures that the appropriate funds exists for the lock to be valid. In other words, if the sponsor has deposited 10 tokens, no set of approved locks shall exceed 10 tokens. The allocator then co-signs the lock. + 2. The **allocator** ensures that the appropriate funds exists for the lock to be valid. In other words, if the sponsor has deposited 10 tokens, no set of approved locks shall exceed 10 tokens. The allocator then co-signs the lock. -3. Desired event takes place. + 3. Desired event takes place. -4. The **arbiter** validates that the event has taken place and releases the token to the appropriate recipient. + 4. The **arbiter** validates that the event has taken place and releases the token to the appropriate recipient. - + + In this flow, 2 signatures and 1 transaction – ignoring the 0'th step – is required; The lock have to be signed by the sponsor, and co-signed by the allocator. Then the arbiter makes the final call whether the desired event took place. diff --git a/src/content/docs/solver/01-introduction.mdx b/src/content/docs/solver/01-introduction.mdx new file mode 100644 index 0000000..f9c25e6 --- /dev/null +++ b/src/content/docs/solver/01-introduction.mdx @@ -0,0 +1,90 @@ +--- +title: "Solving Catalyst" +slug: "solver/intro" +description: "All Catalyst orders are permissionlessly solvable. This page introduces you how to being solving for Catalyst." +sidebar: + order: 1 +--- + +Catalyst is an entirely permissionless system. Since the system is componentized and components have no inherient trust elements to other components, they can be mixed and matched as wanted by users. As a result, it is important that you validate orders in their entirety once received. + +The general Catalyst flow is as follows: + +import { Steps } from '@astrojs/starlight/components'; + + + +1. The sponsor signs a Catalyst compatible lock and sends it to the Catalyst order server. + +2. The Catalyst order server preliminarily validates the order and gets the allocator co-signature for the order. It is then broadcasted to solvers. + +3. A solver submits the order's output to the output settlement contract, starting the verification layer. + + :::note[[Output Settlement](/implementation/output)] + The output settlement is denoted as the `remoteFiller` in the order struct. + ::: + +4. The proof is delivered to the input chain through the validation layer. + + :::note[[Validation layer](/implementation/validation)] + The validation layer is denoted as the `localOracle` and `remoteOracle` in the order struct. + ::: + +5. The solver submits the order to the input settlement contract, verifying the delivery and unlocking the associated input tokens. + + + + +### Orders +The Catalyst system does not define a strict order type and as a result there will be differences between how orders are expressed in various systems. Currently only 1 order description is supported across all VMs: + +```solidity +struct CatalystCompactOrder { + address user; + uint256 nonce; + uint256 originChainId; + uint32 fillDeadline; + address localOracle; + uint256[2][] inputs; + OutputDescription[] outputs; +} +``` + +Where `uint256[2][] inputs === [uint256 tokenId, uint256 amount][]` and `OutputDescription`: + +```solidity +struct OutputDescription { + bytes32 remoteOracle; + bytes32 remoteFiller; + uint256 chainId; + bytes32 token; + uint256 amount; + bytes32 recipient; + bytes remoteCall; + bytes fulfillmentContext; +} +``` + +The `CatalystCompactOrder` will be used to interface all functions on the input chain. Additionally, once hydrated with a signature it allows one to verify the validity of an order. + +The `CatalystCompactOrder` struct will be signed and stored as a witness in the appropriate lock/claim structure. For TheCompact this is: + +```solidity +struct BatchCompact { + address arbiter; // Associated settlement contract + address sponsor; // CatalystCompactOrder.user + uint256 nonce; // CatalystCompactOrder.nonce + uint256 expires; // CatalystCompactOrder.fillDeadline + uint256[2][] idsAndAmounts; // CatalystCompactOrder.inputs + CatalystWitness witness; +} + +struct CatalystWitness { + uint32 fillDeadline; // CatalystCompactOrder.fillDeadline + address localOracle; // CatalystCompactOrder.localOracle + OutputDescription[] outputs; // CatalystCompactOrder.outputs +} +``` + +To validate an order, ensure that the sponsor and allocator signatures are valid for this EIP-712 signed structure. + diff --git a/src/content/docs/solver/collecting-orders.mdx b/src/content/docs/solver/02-collecting-orders.mdx similarity index 99% rename from src/content/docs/solver/collecting-orders.mdx rename to src/content/docs/solver/02-collecting-orders.mdx index 5076177..b844c85 100644 --- a/src/content/docs/solver/collecting-orders.mdx +++ b/src/content/docs/solver/02-collecting-orders.mdx @@ -1,8 +1,12 @@ --- title: "Collecting Orders" +slug: "solver/orderflow" description: "CrossCats allows solvers to collect order flow to and from various VM chains and to and from Bitcoin. Compared to competing solution, capital hungry solvers can improve their capital turnaround by using the underwriting network to their advantage." sidebar: - order: 4 + order: 2 + badge: + text: Outdated + variant: note --- import { Tabs, TabItem } from "@astrojs/starlight/components"; diff --git a/src/content/docs/solver/evm-fulfilling.mdx b/src/content/docs/solver/20-evm-fulfilling.mdx similarity index 98% rename from src/content/docs/solver/evm-fulfilling.mdx rename to src/content/docs/solver/20-evm-fulfilling.mdx index d666c17..ff3bb09 100644 --- a/src/content/docs/solver/evm-fulfilling.mdx +++ b/src/content/docs/solver/20-evm-fulfilling.mdx @@ -1,8 +1,12 @@ --- title: "Fulfilling EVM Orders" +slug: "solver/evm" description: "CrossCats allows solvers to collect order flow to and from various VM chains and to and from Bitcoin. Compared to competing solution, capital hungry solvers can improve their capital turnaround by using the underwriting network to their advantage." sidebar: - order: 6 + order: 20 + badge: + text: Outdated + variant: note --- import { Tabs, TabItem } from "@astrojs/starlight/components"; diff --git a/src/content/docs/solver/btc-fulfilling.mdx b/src/content/docs/solver/29-btc-fulfilling.mdx similarity index 98% rename from src/content/docs/solver/btc-fulfilling.mdx rename to src/content/docs/solver/29-btc-fulfilling.mdx index b5516a3..f8dd18a 100644 --- a/src/content/docs/solver/btc-fulfilling.mdx +++ b/src/content/docs/solver/29-btc-fulfilling.mdx @@ -1,8 +1,12 @@ --- title: "Fulfilling BTC Orders" +slug: "solver/btc" description: "CrossCats allows solvers to collect order flow to and from various VM chains and to and from Bitcoin. Compared to competing solution, capital hungry solvers can improve their capital turnaround by using the underwriting network to their advantage." sidebar: - order: 7 + order: 29 + badge: + text: Outdated + variant: note --- import { Tabs, TabItem } from "@astrojs/starlight/components"; diff --git a/src/content/docs/solver/init-orders.mdx b/src/content/docs/solver/90-settling-orders.mdx similarity index 99% rename from src/content/docs/solver/init-orders.mdx rename to src/content/docs/solver/90-settling-orders.mdx index 69f8080..2ee0132 100644 --- a/src/content/docs/solver/init-orders.mdx +++ b/src/content/docs/solver/90-settling-orders.mdx @@ -1,8 +1,12 @@ --- -title: "Initiating Orders" +title: "Settling Orders" +slug: "solver/settlement" description: "CrossCats allows solvers to collect order flow to and from various VM chains and to and from Bitcoin. Compared to competing solution, capital hungry solvers can improve their capital turnaround by using the underwriting network to their advantage." sidebar: - order: 5 + order: 90 + badge: + text: Outdated + variant: note --- import { Tabs, TabItem } from "@astrojs/starlight/components"; diff --git a/src/content/docs/solver/introduction.mdx b/src/content/docs/solver/introduction.mdx deleted file mode 100644 index 34c0cb9..0000000 --- a/src/content/docs/solver/introduction.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Solving for CrossCats" -description: "CrossCats allows solvers to collect order flow to and from various VM chains and to and from Bitcoin. Compared to competing solution, capital hungry solvers can improve their capital turnaround by using the underwriting network to their advantage." -sidebar: - order: 3 ---- - -import { Tabs, TabItem } from "@astrojs/starlight/components"; - - -CrossCats utilizes three main order structures: - -1. [**CrossChainOrder**](https://github.com/catalystdao/cross-cats/blob/7e07281eef10ffadc10f9f75eb42d1c2419224ca/src/interfaces/ISettlementContract.sol#L6-L27) is a generic input order with an ERC-7683 compatible structure. The key component here is orderData, which contains the core functionality and varies significantly across ERC-7683 supporting implementations. -2. [**ResolvedCrossChainOrder**](https://github.com/catalystdao/cross-cats/blob/7e07281eef10ffadc10f9f75eb42d1c2419224ca/src/interfaces/ISettlementContract.sol#L29-L52) provides a quote description, detailing the value of a cross-chain order at a specific point in time. It is also ERC-7683 compliant\*, allowing solvers to efficiently compare the resolution of orders across various protocols. -3. [**OrderKey**](https://github.com/catalystdao/cross-cats/blob/7e07281eef10ffadc10f9f75eb42d1c2419224ca/src/interfaces/Structs.sol#L41-L65) is used to monitor a Catalyst order throughout its lifecycle. It includes Catalyst-specific context and provides an in-depth description of an order. - -Below is the generic ERC-7683 CrossChainOrder structure. The `CrossChainOrder.orderData` field is an ABI-encoded order struct. - -```solidity -struct CrossChainOrder { - address settlementContract; - address swapper; - uint256 nonce; - uint32 originChainId; - uint32 initiateDeadline; - uint32 fillDeadline; - bytes orderData; -} -``` - -The `orderData` field is uniquely encoded by CrossCats. Currently, two orderdata structs are supported: - -```solidity -/// @notice Simpler and slightly cheaper for order types with fixed inputs and outputs. -struct CatalystLimitOrderData { - uint32 proofDeadline; - uint32 challengeDeadline; - address collateralToken; - uint256 fillerCollateralAmount; - uint256 challengerCollateralAmount; - address localOracle; - Input[] inputs; - OutputDescription[] outputs; -} -/// @notice Supports Dutch Auctions on both input and output and support for additional custom order verification. -struct CatalystDutchOrderData { - bytes32 verificationContext; - address verificationContract; - uint32 proofDeadline; - uint32 challengeDeadline; - address collateralToken; - uint256 fillerCollateralAmount; - uint256 challengerCollateralAmount; - address localOracle; - uint32 slopeStartingTime; - /** @dev Input rate of change. */ - int256[] inputSlopes; - /** @dev Output rate of change. */ - int256[] outputSlopes; - Input[] inputs; - OutputDescription[] outputs; -} - -// With the input and output structs defined as: -struct Input { - address token; - uint256 amount; -} - -struct OutputDescription { - /** @dev Contract on the destination that tells whether an order was filled. - * Format is bytes32() slice of the encoded bytearray from the messaging protocol. - * If local: bytes32(uint256(uint160(address(localOracle)))). */ - bytes32 remoteOracle; - /** @dev The address of the token on the destination chain. */ - bytes32 token; - /** @dev The amount of the token to be sent. */ - uint256 amount; - /** @dev The address to receive the output tokens. */ - bytes32 recipient; - /** @dev The destination chain for this output. */ - uint32 chainId; - /** @dev Additional data that is relevant for the caller. */ - bytes remoteCall; -} -``` - -Users generate a `CrossChainOrder` with the appropriate order data and sign it as a Permit2 witness, thereby approving both the order description and its associated inputs with a single signature. The signed struct will be a new structure where `orderData` is an ABI-encoded order type. - -CrossCats has directionality. That means the ways orders are initiated depends on the initiating chain (where the user is swapping out of). In the current iteration, there are 2 important origin types: EVM and Bitcoin. In the future, all virtual machine chains (including EVM) will generally be initiated similarly and all non-VM chains (including Bitcoin) will be initiated similarly but different from VM chains.