> For the complete documentation index, see [llms.txt](https://pontis.gitbook.io/about/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pontis.gitbook.io/about/how-it-works/architecture.md).

# Architecture

**Pontis Bridge** is designed to securely bridge assets across the **Bitcoin**, **Stacks**, and **EVM-based networks**. Built with **robust safety mechanisms**, it supports:

* Automatic and manual emergency procedures.
* Integration with key networks to handle **Runes**, **Ordinals**, and **BTC**.
* Consistent, reliable service for cross-chain transactions.

### Bridge Parameters

#### Signer Nodes

* **Role of Signer Nodes**:
  * Validate transactions independently to ensure integrity.
  * Prevent transaction approval if any validation check fails.
  * Switch listeners in case of malicious behavior from the primary listener.
* [**Asigna Multisig SDK**](https://www.asigna.io/):
  * Implements the logic for secure and decentralized transaction signing.
* **Listener Node Responsibilities**:
  * Monitor the source networks (**Bitcoin**, **Stacks**, **EVM**).
  * Determine the correct signer nodes (**BTC**, **STX**, **EVM**) for finalizing transactions on the target chain.

#### Fees

* **Fee Collection**:
  * Collected for each bridging transaction and transferred to the Pontis treasury.

#### Supported Networks

| **Network** | **Supported Assets**         |
| ----------- | ---------------------------- |
| Bitcoin     | BTC, Runes, BRC-20, Ordinals |
| Stacks      | BTC, Runes, BRC-20, Ordinals |
| EVM Chains  | BTC, Runes, BRC-20, TBA      |

#### Emergency Handling

In emergencies (e.g., unsupported assets, node migration):

1. **Manual Intervention Required**:
   * Listener nodes are halted to avoid conflicts.
   * Signer nodes manually verify and approve transactions via terminal.
2. **Process**:
   * Transactions are verified, signed, and confirmed manually.
   * The listener resumes operation once the process is complete.

***

#### Transaction Acceleration

* **When a transaction is stuck**:
  * Acceleration becomes available after a specified number of blocks (varies by chain).
  * Signer nodes validate the gas adjustment and ensure transaction details remain unchanged before approval.

#### User Flow

* Users initiate only **one transaction** to complete the bridging process.

#### Fee Configuration

* **Managed Separately**:
  * Fees are controlled independently of the main multisig.
  * Pontis enforces safeguards to prevent malicious fee configurations.

#### Multisig Control of Signer Nodes

* **Multisig Governance**:
  * The main multisig governs the **controller contract**, responsible for:
    * Setting the current bridge instance.
    * Managing **mint** and **burn** operations for **Fungible Tokens** and **Non-Fungible Token** contracts.

#### Transaction Uniqueness  Transaction uniqueness is ensured through the **tx-hash-and-vout** parameter:

| **Network**        | **Uniqueness Parameter**                      |
| ------------------ | --------------------------------------------- |
| **BTC**            | `tx hash + UTXO number`                       |
| **Runes (on BTC)** | `tx hash + UTXO number + rune number in UTXO` |
| **Other Networks** | `tx hash`                                     |

* **Key UTXO** is required for bridging assets from any network to Bitcoin, ensuring transaction uniqueness even if the main listener restarts.

#### Ordinals Bridge

* **Marketplace Integration**:
  * Separate contracts exist for each Ordinals collection.
  * These contracts will support future marketplace functionalities.

***

#### Confirmation Counting

| **Network**      | **Confirmation Requirement** |
| ---------------- | ---------------------------- |
| **Bitcoin**      | 1 Bitcoin block confirmation |
| **Stacks**       | 1 Bitcoin block confirmation |
| **EVM Networks** | Configurable per network     |

### Smart Contracts

| **Contract Name**                | **Functionality**                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------- |
| `pontis-bridge-controller.clar`  | Manages ownership migration and multisig updates.                                 |
| `pontis-bridge-fee-manager.clar` | Handles fee configuration for the bridge.                                         |
| `pontis-bridge-v1.clar`          | Primary bridging contract; only authorized multisig signers can finalize actions. |
| `pontis-ordinals-nft.clar`       | Sample contract for bridging Ordinals collections.                                |
| `pontis-bridge-ft.clar`          | Sample fungible token contract for **psBTC** and **Runes**.                       |

### External API Integrations

The Pontis Bridge leverages **industry-leading external APIs** to ensure consistent network communication and minimize downtime:

* [**Unisat API**](https://open-api.unisat.io/)
* [**Hiro API**](https://api.mainnet.hiro.so/extended)
* [**Blockstream API**](https://blockstream.info/)
* [**Quicknode**](https://www.quicknode.com/)