feat: resource lock description and fixes

astro.config.mjs

@@ -12,6 +12,8 @@ export default defineConfig({
   redirects: {
     "/cross-cats/": "/intent/intent/",
     "/cross-cats/solver/": "/intent/becoming-a-solver/introduction/",
+    "/validation": "/implementation/validation"
+
   },
   site: `${process.env["CF_PAGES_URL"] ?? "https://docs.catalyst.exchange"}`,
   markdown: {

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "catalyst-starlight",
+  "name": "catalyst-documentation",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "scripts": {
     "dev": "astro dev",
     "start": "astro dev",

src/content/docs/implementation/1-input-settlement.md

@@ -1,6 +1,6 @@
 ---
 title: "Input Settlement"
-slug: "input"
+slug: "implementation/input"
 description: "Built with resource locks in mind, Catalyst supports a variety of input settlement schemes; TheCompact and Rhinestone both allows for first fill flows and sponsored transactions assuming the user have existing deposits."
 sidebar:
   order: 1

src/content/docs/implementation/2-output-settlement.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Output Settlement"
-slug: "output"
+slug: "implementation/output"
 description: "Catalyst currently supports 2 order types: simple limit orders and dutch auctions. However, the Catalyst System was designed with flexbility in mind and more can easily be added."
 sidebar:
   order: 2

src/content/docs/implementation/3-validation-layers.md

@@ -1,6 +1,6 @@
 ---
 title: "Validation Layers"
-slug: "validation"
+slug: "implementation/validation"
 description: "Each Catalyst System order specifies which components are used for which aspects of the swap. Validation layers can be permissionlessly chosen by the issuer of an intent and anyone can write a validation layer."
 sidebar:
   order: 3

src/content/docs/implementation/999-calls.mdx

@@ -1,5 +1,6 @@
 ---
 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

src/content/docs/knowledge/bitcoin-primer.mdx → src/content/docs/knowledge/1-bitcoin-primer.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Bitcoin Primer"
-description: "What is Bitcoin? What is a Bitcoin Block? What is a Bitcoin transaction?  And how do CrossCats prove Bitcoin fulfillments? This page contains all information required to understand how CrossCats interact with BTC."
+slug: "knowledge/bitcoin"
+description: "What is Bitcoin? What is a Bitcoin Block? What is a Bitcoin transaction?  And how do Catalyst prove Bitcoin fulfillments? This page contains all information required to understand how Catalyst can interact with BTC."
 sidebar:
   order: 1
 ---

src/content/docs/knowledge/2-resource-locks.mdx

@@ -0,0 +1,76 @@
+---
+title: "Resource Locks"
+slug: "knowledge/resource-locks"
+description: "Resource locks allows users to pay after the settlement of their desired asset has taken place. This improve the user experience and makes cross-chain actions more seamless."
+sidebar:
+  order: 2
+---
+
+Resource locks allow users to commit tokens to something/someone without making an on-chain transaction to issue the lock or recover the lock after the lock's expiry. 
+In a resource-lock context, it is important that these tokens are at least inaccessible for a certain period of time, longer than the expected settlement time for a claim.
+
+In a sense, they are a form of credit account allowing users to provide guaranteed allowances to protocols.
+
+
+## Actors
+
+In a resource lock flow, you have 3 actors:
+1. Sponsor, user, owner; The actor that initially owns the funds in the resourec lock.
+2. Allocator, manager, credible commitment; The actor that validates that no conflicting locks are issued.
+3. Arbiter, validator, settlement; The actor that is capable of validating whether a lock has been resolved and can be paid.
+
+Depending on the resource lock system, each user chooses an allocator and each lock chooses the arbiter. When the wording *the arbiter*  is used, it refers specifically to the arbiter of a lock. Not to a general single arbiter that the user has chosen.
+
+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:
+
+import { Steps } from '@astrojs/starlight/components';
+
+<Steps>
+
+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.
+
+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.
+
+4. The **arbiter** validates that the event has taken place and releases the token to the appropriate recipient.
+
+</Steps>
+
+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.
+
+
+## Resource-Locked Intents.
+
+In an intent system, the 3'th step – the execution of the desired event – is usually performed by a 4'th actor usually referred to as either the **solver** or the **relayer**.
+
+Additionally, there are generally 2 ways to build intent systems around resource locks:
+
+##### Intent system as *executor* (Tribunual)
+
+In these flows, the intent system describes how the action takes place on the destination chain. However, the system does not directly validate the resource lock completion. 
+
+These systems instead rely on **allocators as arbiters** or resource lock support by **general message passing** (GMPs) protocols.
+
+The advantage of such a system is in its simplicity. The third party (whether allocator or GMP) generally handle the entire validation/settlement pipeline and thus solvers only have to concern themselves with filling orders.
+
+##### Intent system as *arbiter* (Catalyst)
+
+In these flows, the intent system is the arbiter and usually describes how the entire system is constructed: Output settlement, validation, and input settlement. This makes the system more flexible and customizable.
+
+While these systems may also rely on GMPs, they can also use other – potentially cheaper – validation layers like optimistic oracles, storage proofs, or secret reveals (like HTLCs).
+
+The advantage of such a system is indirectly its complexity. Since more logic is explicit defined by the system itself, the expresivity of intents can be greater and more specialised.
+
+For more on the resource locks Catalyst support, read the chapter on [Input Settlement Implementations](/implementation/input).
+
+
+## Trust Assumptions
+
+In a resource lock system, the actors needs to trust each other but generally no single actor can independently access any funds.
+- The sponsor needs to trust the arbiter such that **issued** locks are not fraudulently *finalised*. However, the arbiter can never access any of the sponsor's funds without a relevant signed lock. The trust assumptions between the sponsor and the arbiter is equivalent to permit/permit2 approvals.
+- The arbiter/solver needs to trust that the allocator does not co-sign overlapping locks that exceed the tokens the user have deposited. Otherwise, a filled intent may not have enough tokens available to resolve the payment to the solver for the fulfillment of the lock.

src/content/docs/solver/init-orders.mdx

@@ -172,9 +172,9 @@ If the same address is used every order, it becomes crucial to ensure that the *
 
 Bitcoin addresses are encoded in two fields: `token` and `address`.
 
-- **`token`**: This field serves to differentiate VM tokens from Bitcoin orders, encode relevant context like confirmations and address version. Refer to the [UTXO type table](/knowledge/bitcoin-primer/#utxo-type-table) for details on converting address types to versions. The field should consists of the bitcoin signifier (BC in the 12'th byte), number of confirmations in the 31st, UTXO type in the 32'th, and otherwise 0s.
+- **`token`**: This field serves to differentiate VM tokens from Bitcoin orders, encode relevant context like confirmations and address version. Refer to the [UTXO type table](/knowledge/bitcoin/#utxo-type-table) for details on converting address types to versions. The field should consists of the bitcoin signifier (BC in the 12'th byte), number of confirmations in the 31st, UTXO type in the 32'th, and otherwise 0s.
 
-- **`address`**: This field encodes the public key hash, script hash, or witness hash. Use the decoding schemes listed in the [UTXO type table](/knowledge/bitcoin-primer/#utxo-type-table) for various address versions. For addresses involving hashes of 20 bytes (P2PKH, P2SH, and P2WPKH), end pad the hashes with zeros (e.g., `0xabcdef...00000`).
+- **`address`**: This field encodes the public key hash, script hash, or witness hash. Use the decoding schemes listed in the [UTXO type table](/knowledge/bitcoin/#utxo-type-table) for various address versions. For addresses involving hashes of 20 bytes (P2PKH, P2SH, and P2WPKH), end pad the hashes with zeros (e.g., `0xabcdef...00000`).
 
 ### Quote Open Order (WIP)