feat(wrap): public release of Bitcoin Wrap (W) for Universal BRC-20

- Add Wrap Validator Service with audited Taproot validation path (multisig/csv)
- Introduce Wrap API endpoints and validation endpoints
- Consolidate wrap DB schema and tables: extended contracts, swap positions
- Add remaining_supply on deploys; initialize from max_supply for existing data
- Update services to use IntermediateState; align tests to new API
- Improve error handling and structured logging across indexer/processor

Migrations & Models
- Single consolidated Alembic migration: extended_contracts, swap_positions, remaining_supply
- Add enums, constraints, and indexes for new tables

API & Services
- New routers: wrap, validation
- Query services for extended contracts and TVL
- Processor integration for W mint/burn via wrap services

Tooling & CI
- Add system deps for secp256k1 build in CI (pkg-config, libsecp256k1-dev, build-essential, python3-dev)
- Add Python deps (bech32m, secp256k1, varint) and document dev setup

Quality
- Black/Flake8: clean
- Tests: 438 passed, 7 skipped locally
- README updated for Taproot crypto system dependencies

Authored-by: Universal BRC-20 Indexer Team

Author: GaloisField2718

.github/workflows/ci.yml

@@ -54,6 +54,11 @@ jobs:
         python -m pip install --upgrade pip
         pip install pipenv
     
+    - name: Install system dependencies (secp256k1 build)
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pkg-config libsecp256k1-dev build-essential python3-dev
+    
     - name: Cache pipenv dependencies
       uses: actions/cache@v4
       with:
@@ -208,11 +213,11 @@ jobs:
 
         echo "DATABASE_URL: $DATABASE_URL"
         echo "REDIS_URL: $REDIS_URL"
-        echo "Health check URL: http://localhost:8080/v1/indexer/brc20/health"
+        echo "Health check URL: http://localhost:8083/v1/indexer/brc20/health"
         sleep 6
         # Wait up to 6 seconds for the service to be up
         for i in {1..60}; do
-          if curl -f http://localhost:8080/v1/indexer/brc20/health; then
+          if curl -f http://localhost:8083/v1/indexer/brc20/health; then
             echo "Service is up!"
             docker stop test-indexer
             exit 0

Dockerfile

@@ -7,6 +7,8 @@ RUN apt-get update && apt-get install -y \
     build-essential \
     libpq-dev \
     gcc \
+    pkg-config \
+    libsecp256k1-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # Install pipenv
@@ -32,6 +34,7 @@ ENV HOME=/home/indexer
 RUN apt-get update && apt-get install -y \
     libpq5 \
     curl \
+    libsecp256k1-2 \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy Python packages from builder

Pipfile

@@ -28,6 +28,9 @@ sqlalchemy = "*"
 mypy = "*"
 bandit = "*"
 safety = "*"
+bech32m = "*"
+secp256k1 = "*"
+varint = "*"
 
 [dev-packages]
 pytest = "*"

Pipfile.lock

@@ -109,6 +109,23 @@ pipenv run alembic upgrade head
 pipenv run python run.py --continuous
 ```
 
+### System Dependencies for Taproot Crypto (Developers)
+
+Taproot helpers use `secp256k1` bindings and Bech32m:
+
+- Install OS libs (macOS):
+  ```bash
+  brew install pkg-config secp256k1
+  ```
+- Install OS libs (Debian/Ubuntu in CI/containers):
+  ```bash
+  sudo apt-get update && sudo apt-get install -y pkg-config libsecp256k1-dev
+  ```
+- Python deps are declared in `Pipfile` and `requirements.txt`:
+  ```bash
+  pipenv run pip install bech32m secp256k1
+  ```
+
 ### Available Commands
 
 The project includes a comprehensive Makefile for common operations:

README.md

@@ -0,0 +1,181 @@
+"""Consolidate wrap schema into simplicity (extended_contracts, vaults, swap_positions, remaining_supply)
+
+Revision ID: 20251030_01
+Revises: f0e124fbfbf0
+Create Date: 2025-10-30
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.sql import text
+
+
+# revision identifiers, used by Alembic.
+revision: str = "20251030_01"
+down_revision: Union[str, Sequence[str], None] = "f0e124fbfbf0"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1) deploys.remaining_supply (align with model)
+    conn = op.get_bind()
+
+    # Add column nullable first (if not exists)
+    op.add_column(
+        "deploys",
+        sa.Column("remaining_supply", sa.Numeric(precision=38, scale=8), nullable=True),
+    )
+
+    # Initialize values: set remaining_supply = max_supply
+    conn.execute(text("UPDATE deploys SET remaining_supply = max_supply"))
+    # Special case for W with max_supply = 0 → remaining_supply = 0
+    conn.execute(text("UPDATE deploys SET remaining_supply = 0 WHERE ticker = 'W' AND max_supply = 0"))
+    # Set NOT NULL
+    op.alter_column("deploys", "remaining_supply", nullable=False)
+
+    # 2) extended_contracts
+    op.create_table(
+        "extended_contracts",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("script_address", sa.String(), nullable=False),
+        sa.Column("initiator_address", sa.String(), nullable=False),
+        sa.Column("status", sa.String(), nullable=False, server_default="active"),
+        sa.Column("timelock_delay", sa.Integer(), nullable=False, comment="Timelock delay in blocks"),
+        sa.Column("initial_amount", sa.Numeric(precision=38, scale=8), nullable=True, comment="Amount of tokens initially wrapped"),
+        sa.Column("creation_txid", sa.String(), nullable=False),
+        sa.Column("creation_timestamp", sa.DateTime(), nullable=False),
+        sa.Column("creation_height", sa.Integer(), nullable=False),
+        sa.Column("internal_pubkey", sa.String(), nullable=True),
+        sa.Column("tapscript_hex", sa.Text(), nullable=True),
+        sa.Column("merkle_root", sa.String(), nullable=True),
+        sa.Column("closure_txid", sa.String(), nullable=True, comment="Transaction ID that closed the contract"),
+        sa.Column("closure_timestamp", sa.DateTime(), nullable=True, comment="Block timestamp when contract was closed"),
+        sa.Column("closure_height", sa.Integer(), nullable=True, comment="Block height when contract was closed"),
+        sa.Column("extension_data", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.PrimaryKeyConstraint("id", name=op.f("extended_contracts_pkey")),
+    )
+    op.create_index(op.f("ix_extended_contracts_script_address"), "extended_contracts", ["script_address"], unique=True)
+    op.create_index(op.f("ix_extended_contracts_initiator_address"), "extended_contracts", ["initiator_address"], unique=False)
+    op.create_index(op.f("ix_extended_contracts_creation_txid"), "extended_contracts", ["creation_txid"], unique=False)
+    op.create_index(op.f("ix_extended_contracts_creation_height"), "extended_contracts", ["creation_height"], unique=False)
+
+    # 3) vaults (Enum values in lowercase to align with models)
+    vaultstatus = sa.Enum("active", "abandoned", "recycled", "sovereign_recovery", "closed", name="vaultstatus")
+    vaultstatus.create(op.get_bind(), checkfirst=True)
+
+    op.create_table(
+        "vaults",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("vault_type", sa.String(), nullable=False, comment="Defines the type of contract, allowing for future protocol extensions."),
+        sa.Column("status", vaultstatus, nullable=False, comment="The current state of the game for this vault."),
+        sa.Column("p2tr_address", sa.String(), nullable=False, comment="The Taproot (P2TR) address encoding the contract's spend paths."),
+        sa.Column("owner_address", sa.String(), nullable=False, comment="The address of the vault's sovereign owner."),
+        sa.Column("collateral_amount_sats", sa.Numeric(precision=38, scale=0), nullable=False, comment="The amount of BTC collateral in satoshis."),
+        sa.Column("remaining_blocks", sa.Integer(), nullable=True, comment="Countdown for the liquidation timelock."),
+        sa.Column("w_proof_commitment", sa.String(), nullable=False, comment="Hash of the W_PROOF from the reveal transaction's witness."),
+        sa.Column("reveal_operation_id", sa.Integer(), nullable=False),
+        sa.Column("closing_operation_id", sa.Integer(), nullable=True),
+        sa.Column("reveal_txid", sa.String(), nullable=False, comment="TXID of the transaction that locked the collateral."),
+        sa.Column("reveal_block_height", sa.Integer(), nullable=False),
+        sa.Column("reveal_timestamp", sa.DateTime(), nullable=False),
+        sa.Column("closing_txid", sa.String(), nullable=True, comment="TXID of the transaction that unlocked the collateral."),
+        sa.Column("closing_block_height", sa.Integer(), nullable=True),
+        sa.Column("closing_timestamp", sa.DateTime(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.ForeignKeyConstraint(["reveal_operation_id"], ["brc20_operations.id"]),
+        sa.ForeignKeyConstraint(["closing_operation_id"], ["brc20_operations.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_vaults_vault_type"), "vaults", ["vault_type"], unique=False)
+    op.create_index(op.f("ix_vaults_status"), "vaults", ["status"], unique=False)
+    op.create_index(op.f("ix_vaults_p2tr_address"), "vaults", ["p2tr_address"], unique=True)
+    op.create_index(op.f("ix_vaults_owner_address"), "vaults", ["owner_address"], unique=False)
+    op.create_index(op.f("ix_vaults_remaining_blocks"), "vaults", ["remaining_blocks"], unique=False)
+    op.create_index(op.f("ix_vaults_reveal_block_height"), "vaults", ["reveal_block_height"], unique=False)
+    op.create_index(op.f("ix_vaults_reveal_operation_id"), "vaults", ["reveal_operation_id"], unique=True)
+    op.create_index(op.f("ix_vaults_reveal_txid"), "vaults", ["reveal_txid"], unique=True)
+    op.create_index(op.f("ix_vaults_closing_operation_id"), "vaults", ["closing_operation_id"], unique=True)
+    op.create_index(op.f("ix_vaults_closing_txid"), "vaults", ["closing_txid"], unique=True)
+    op.create_index(op.f("ix_vaults_closing_block_height"), "vaults", ["closing_block_height"], unique=False)
+
+    # 4) swap_positions (status as VARCHAR + CHECK to align with model native_enum=False)
+    active_values = ("active", "expired", "closed")
+    op.create_table(
+        "swap_positions",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True, nullable=False),
+        sa.Column("owner_address", sa.String(), nullable=False),
+        sa.Column("pool_id", sa.String(), nullable=False, comment="Canonical pair id (alphabetical)"),
+        sa.Column("src_ticker", sa.String(), nullable=False),
+        sa.Column("dst_ticker", sa.String(), nullable=False),
+        sa.Column("amount_locked", sa.Numeric(precision=38, scale=8), nullable=False),
+        sa.Column("lock_duration_blocks", sa.Integer(), nullable=False),
+        sa.Column("lock_start_height", sa.Integer(), nullable=False),
+        sa.Column("unlock_height", sa.Integer(), nullable=False),
+        sa.Column("status", sa.String(), nullable=False, server_default="active"),
+        sa.Column("init_operation_id", sa.Integer(), sa.ForeignKey("brc20_operations.id"), nullable=False, unique=True),
+        sa.Column("closing_operation_id", sa.Integer(), sa.ForeignKey("brc20_operations.id"), nullable=True, unique=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+        sa.CheckConstraint(f"status in {active_values}", name="ck_swap_positions_status_values"),
+    )
+    op.create_index("ix_swap_positions_owner_address", "swap_positions", ["owner_address"])
+    op.create_index("ix_swap_positions_pool_id", "swap_positions", ["pool_id"])
+    op.create_index("ix_swap_positions_src_ticker", "swap_positions", ["src_ticker"])
+    op.create_index("ix_swap_positions_dst_ticker", "swap_positions", ["dst_ticker"])
+    op.create_index("ix_swap_positions_lock_start_height", "swap_positions", ["lock_start_height"])
+    op.create_index("ix_swap_positions_unlock_height", "swap_positions", ["unlock_height"])
+    op.create_index("ix_swap_positions_status", "swap_positions", ["status"])
+
+    # Drop obsolete unique constraint if present (idempotent)
+    try:
+        op.drop_constraint("uq_swap_pos_owner_pool_unlock", "swap_positions", type_="unique")
+    except Exception:
+        pass
+
+
+def downgrade() -> None:
+    # swap_positions
+    op.drop_index("ix_swap_positions_status", table_name="swap_positions")
+    op.drop_index("ix_swap_positions_unlock_height", table_name="swap_positions")
+    op.drop_index("ix_swap_positions_lock_start_height", table_name="swap_positions")
+    op.drop_index("ix_swap_positions_dst_ticker", table_name="swap_positions")
+    op.drop_index("ix_swap_positions_src_ticker", table_name="swap_positions")
+    op.drop_index("ix_swap_positions_pool_id", table_name="swap_positions")
+    op.drop_index("ix_swap_positions_owner_address", table_name="swap_positions")
+    op.drop_table("swap_positions")
+
+    # vaults
+    op.drop_index(op.f("ix_vaults_closing_block_height"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_closing_txid"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_closing_operation_id"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_reveal_txid"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_reveal_operation_id"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_reveal_block_height"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_remaining_blocks"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_p2tr_address"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_owner_address"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_status"), table_name="vaults")
+    op.drop_index(op.f("ix_vaults_vault_type"), table_name="vaults")
+    op.drop_table("vaults")
+    try:
+        sa.Enum(name="vaultstatus").drop(op.get_bind(), checkfirst=True)
+    except Exception:
+        pass
+
+    # extended_contracts
+    op.drop_index(op.f("ix_extended_contracts_creation_height"), table_name="extended_contracts")
+    op.drop_index(op.f("ix_extended_contracts_creation_txid"), table_name="extended_contracts")
+    op.drop_index(op.f("ix_extended_contracts_initiator_address"), table_name="extended_contracts")
+    op.drop_index(op.f("ix_extended_contracts_script_address"), table_name="extended_contracts")
+    op.drop_table("extended_contracts")
+
+    # deploys.remaining_supply
+    op.drop_column("deploys", "remaining_supply")
+
+

alembic/versions/20251030_01_consolidate_wrap_schema.py

@@ -0,0 +1,52 @@
+"""Add trigger to update vault status when remaining_blocks reaches zero
+
+Revision ID: 20251030_02
+Revises: 20251030_01
+Create Date: 2025-10-30
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = "20251030_02"
+down_revision: Union[str, Sequence[str], None] = "20251030_01"
+branch_labels = None
+depends_on = None
+
+
+CREATE_TRIGGER_FUNCTION_SQL = """
+CREATE OR REPLACE FUNCTION update_vault_status_on_countdown()
+RETURNS TRIGGER AS $$
+BEGIN
+    IF NEW.status = 'active' AND NEW.remaining_blocks = 0 AND COALESCE(OLD.remaining_blocks, 0) > 0 THEN
+        NEW.status := 'abandoned';
+    END IF;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+"""
+
+
+CREATE_TRIGGER_SQL = """
+CREATE TRIGGER trigger_vault_abandonment
+BEFORE UPDATE ON vaults
+FOR EACH ROW
+EXECUTE FUNCTION update_vault_status_on_countdown();
+"""
+
+
+DROP_TRIGGER_SQL = "DROP TRIGGER IF EXISTS trigger_vault_abandonment ON vaults;"
+DROP_FUNCTION_SQL = "DROP FUNCTION IF EXISTS update_vault_status_on_countdown();"
+
+
+def upgrade() -> None:
+    op.execute(CREATE_TRIGGER_FUNCTION_SQL)
+    op.execute(CREATE_TRIGGER_SQL)
+
+
+def downgrade() -> None:
+    op.execute(DROP_TRIGGER_SQL)
+    op.execute(DROP_FUNCTION_SQL)
+
+

alembic/versions/20251030_02_vaults_status_trigger.py

@@ -6,9 +6,9 @@
 graph TD
     A[Block Ingestion] --> B[Transaction Parsing]
     B --> C{OPI Router}
-    C -->|op: "swap"| D[OPI-1 Processor]
-    C -->|op: "no_return"| E[OPI-0 Processor]
-    C -->|op: "deploy"| F[Legacy BRC20 Processor]
+    C -->|op: swap| D[OPI-1 Processor]
+    C -->|op: no_return| E[OPI-0 Processor]
+    C -->|op: deploy| F[Legacy BRC20 Processor]
     D --> G[State Validation]
     E --> G
     F --> G

docs/architecture/OPI_ARCHITECTURE_DIAGRAM.md

@@ -42,9 +42,9 @@ The OPI (Operation Proposal Improvement) framework is a modular architecture tha
 graph TD
     A[Block Ingestion] --> B[Transaction Parsing]
     B --> C{OPI Router}
-    C -->|op: "swap"| D[OPI-1 Processor]
-    C -->|op: "no_return"| E[OPI-0 Processor]
-    C -->|op: "deploy"| F[Legacy BRC20 Processor]
+    C -->|op: swap| D[OPI-1 Processor]
+    C -->|op: no_return| E[OPI-0 Processor]
+    C -->|op: deploy| F[Legacy BRC20 Processor]
     D --> G[State Validation]
     E --> G
     F --> G

docs/architecture/OPI_DEVELOPER_GUIDE.md

@@ -55,3 +55,6 @@ uvicorn[standard]==0.35.0; python_version >= '3.9'
 uvloop==0.21.0; python_full_version >= '3.8.0'
 watchfiles==1.1.0; python_version >= '3.9'
 websockets==15.0.1; python_version >= '3.9'
+bech32m==1.0.0
+secp256k1==0.14.0
+varint==1.0.2