docs: improve documentation, fix broken links, and add parameter desc…

README.md

@@ -2,16 +2,159 @@
 
 This repository is the codebase for the Magic Protocol contracts and web application.
 
+Magic Protocol is a trustless Bitcoin-to-Stacks bridge that enables users to swap BTC for xBTC (wrapped Bitcoin on Stacks) and vice versa without requiring trust in a centralized party.
+
 Check out the [Magic docs](https://docs.magic.fun) for more information about how Magic works.
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Project Structure](#project-structure)
+- [Contracts](#contracts)
+- [Development Setup](#development-setup)
+- [Testing](#testing)
+- [Environment Variables](#environment-variables)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+
+Magic Protocol enables trustless atomic swaps between Bitcoin (BTC) and wrapped Bitcoin on Stacks (xBTC). The protocol uses Hash Time-Locked Contracts (HTLCs) to ensure that swaps are either completed fully or refunded, eliminating counterparty risk.
+
+### Key Features
+
+- **Trustless Swaps**: No centralized party holds your funds
+- **Atomic Transactions**: Swaps complete fully or are automatically refunded
+- **Supplier System**: Liquidity providers can earn fees by facilitating swaps
+- **Inbound & Outbound**: Support for both BTC→xBTC and xBTC→BTC swaps
+
+## Architecture
+
+The protocol consists of three main components:
+
+1. **Bridge Contract** (`bridge.clar`): Core protocol logic handling supplier registration, escrow management, and swap finalization
+2. **Supplier Wrapper** (`supplier-wrapper.clar`): Helper contract for suppliers to manage their liquidity
+3. **Clarity Bitcoin Library** (`clarity-bitcoin.clar`): Bitcoin transaction parsing and validation
+
+### Swap Flow
+
+**Inbound Swap (BTC → xBTC):**
+1. User creates an HTLC on Bitcoin with the supplier's public key
+2. User calls `escrow-swap` with the BTC transaction proof
+3. Supplier reveals the preimage to claim BTC and releases xBTC to the user
+
+**Outbound Swap (xBTC → BTC):**
+1. User initiates outbound swap by locking xBTC in the contract
+2. Supplier sends BTC to the user's Bitcoin address
+3. Supplier finalizes the swap with the BTC transaction proof
+
+## Project Structure
+
+```
+magic-protocol/
+├── contracts/           # Clarity smart contracts
+│   ├── bridge.clar      # Main protocol contract
+│   ├── supplier-wrapper.clar
+│   ├── clarity-bitcoin.clar
+│   └── test/            # Test contracts
+├── common/              # Shared TypeScript utilities and Clarigen bindings
+├── components/          # React UI components
+├── docs/                # Contract documentation
+├── pages/               # Next.js pages
+├── public/              # Static assets
+├── scripts/             # Utility scripts
+├── settings/            # Configuration files
+└── test/                # Test files
+```
+
 ## Contracts
 
-The main contract for Magic is [./contracts/bridge.clar](`bridge.clar`), where all protocol-specific logic is handled. You can find tests for this contract under the `test` directory.
+The main contract for Magic is [`./contracts/bridge.clar`](./contracts/bridge.clar), where all protocol-specific logic is handled. You can find tests for this contract under the `test` directory.
+
+### Contract Documentation
+
+- [`bridge`](./docs/bridge.md) - Core protocol contract
+- [`supplier-wrapper`](./docs/supplier-wrapper.md) - Supplier helper contract
+- [`clarity-bitcoin`](./docs/clarity-bitcoin.md) - Bitcoin transaction utilities
+
+## Development Setup
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (v16 or higher)
+- [Yarn](https://yarnpkg.com/) package manager
+- [Clarinet](https://github.com/hirosystems/clarinet) (for Clarity development)
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/magicstx/magic-protocol.git
+   cd magic-protocol
+   ```
+
+2. Install dependencies:
+   ```bash
+   yarn
+   ```
+
+3. Copy the environment configuration:
+   ```bash
+   cp .env.example .env.local
+   ```
+
+4. Start the development server:
+   ```bash
+   yarn dev
+   ```
+
+The app will be available at [localhost:4444](http://localhost:4444).
+
+## Testing
+
+Run the test suite with:
+
+```bash
+yarn test
+```
+
+For Clarity contract tests using Clarinet:
+
+```bash
+clarinet test
+```
+
+## Environment Variables
+
+Create a `.env.local` file based on `.env.example`:
+
+| Variable | Description |
+| --- | --- |
+| `NEXT_PUBLIC_NETWORK` | Network to use (`testnet` or `mainnet`) |
+| `NEXT_PUBLIC_ELECTRUM_HOST` | Electrum server host |
+| `NEXT_PUBLIC_ELECTRUM_PORT` | Electrum server port |
+
+The example configuration works for public testnet configurations.
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests to ensure everything works
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to your branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
 
-## Development setup
+### Code Style
 
-First, install dependencies by running `yarn`.
+- Follow existing code conventions
+- Add tests for new functionality
+- Update documentation as needed
 
-Copy the `.env.example` file to `.env.local`. The example configuration will work for public testnet configurations.
+## License
 
-Finally, run the app with `yarn dev`. The app will be available at [localhost:4444](http://localhost:4444).
+This project is licensed under the GPL-2.0 License - see the [LICENSE](LICENSE) file for details.

docs/README.md

@@ -1,9 +1,38 @@
-# Contracts
-
-- [`ft-trait`](.mdinet/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.ft-trait.clar)
-- [`restricted-token-trait`](.mdinet/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.restricted-token-trait.clar)
-- [`Wrapped-Bitcoin`](.mdinet/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin.clar)
-- [`test-utils`](contracts/test/test-utils.md)
-- [`clarity-bitcoin`](contracts/test/clarity-bitcoin.md)
-- [`bridge`](contracts/bridge.md)
-- [`supplier-wrapper`](contracts/supplier-wrapper.md)
+# Contract Documentation
+
+This directory contains auto-generated documentation for Magic Protocol smart contracts.
+
+## Core Contracts
+
+- [`bridge`](./bridge.md) - Main protocol contract handling supplier registration, escrow management, and swap finalization
+- [`supplier-wrapper`](./supplier-wrapper.md) - Helper contract for suppliers to manage their liquidity
+
+## Supporting Contracts
+
+- [`clarity-bitcoin`](./clarity-bitcoin.md) - Bitcoin transaction parsing and validation utilities
+- [`test-utils`](./test-utils.md) - Testing utilities
+
+## External Dependencies
+
+These contracts are external dependencies used by the protocol:
+
+- [`ft-trait`](./../.clarinet/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.ft-trait.clar) - SIP-010 fungible token trait
+- [`restricted-token-trait`](./../.clarinet/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.restricted-token-trait.clar) - Restricted token trait
+- [`Wrapped-Bitcoin`](./Wrapped-Bitcoin.md) - xBTC token contract (wrapped Bitcoin on Stacks)
+
+## Contract Architecture
+
+```
+                    ┌─────────────────────┐
+                    │   bridge.clar       │
+                    │   (Core Protocol)   │
+                    └──────────┬──────────┘
+                               │
+           ┌───────────────────┼───────────────────┐
+           │                   │                   │
+           ▼                   ▼                   ▼
+┌──────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ supplier-wrapper │ │ clarity-bitcoin │ │  Wrapped-Bitcoin│
+│  (Supplier Mgmt) │ │  (BTC Parsing)  │ │    (xBTC)       │
+└──────────────────┘ └─────────────────┘ └─────────────────┘
+```