# 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/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pontis.gitbook.io/about/how-it-works/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.