feat: solving introduction

astro.config.mjs

@@ -50,7 +50,6 @@ export default defineConfig({
         },
         {
           label: "Solvers",
-          badge: "Outdated",
           autogenerate: {
             directory: "solver",
           },

src/content/docs/implementation/1-input-settlement.md → 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.

src/content/docs/implementation/999-calls.mdx → 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.

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';
 
-<Steps>
+<Card>
+  <Steps>
 
-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.
 
-</Steps>
+  </Steps>
+</Card>
 
 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.
 

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';
+
+<Steps>
+
+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.
+
+</Steps>
+
+
+### 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.
+

src/content/docs/solver/collecting-orders.mdx → 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";

src/content/docs/solver/evm-fulfilling.mdx → 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";

src/content/docs/solver/btc-fulfilling.mdx → 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";

src/content/docs/solver/init-orders.mdx → 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";