https://github.com/tangle-network/subsquid-portal-blueprint

A Tangle Blueprint for running a Subsquid Portal
https://github.com/tangle-network/subsquid-portal-blueprint

Last synced: 3 months ago
JSON representation

A Tangle Blueprint for running a Subsquid Portal

• Host: GitHub
• URL: https://github.com/tangle-network/subsquid-portal-blueprint
• Owner: tangle-network
• License: apache-2.0
• Created: 2025-04-08T22:05:26.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2025-10-09T14:26:32.000Z (8 months ago)
• Last Synced: 2026-04-04T07:44:30.361Z (3 months ago)
• Language: Rust
• Size: 257 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHE

Awesome Lists containing this project

README

          
# Subsquid Portal Tangle Blueprint

This blueprint enables Tangle Network operators to provide managed Subsquid Portal instances with an optional authenticated and rate-limited gateway service.

## Overview

Subsquid Portals provide efficient access to blockchain data via the Subsquid Network. This blueprint allows operators to run these portals as a service for customers who need reliable data access without managing the infrastructure themselves.

Key features:

- **Portal Provisioning:** Operators can easily deploy new `sqd-portal` instances configured for specific networks (e.g., `mainnet`).

- **Authenticated Gateway:** An optional gateway can be configured to sit in front of a portal instance, requiring API keys for access.

- **Rate Limiting:** The gateway enforces configurable rate limits per API key.

- **API Key Management:** Customers (or operators on their behalf) can generate new API keys associated with a specific gateway, with the key securely delivered via RSA encryption.

## Users & Interactions

1.  **Operator:**

    - Deploys this blueprint service on the Tangle Network.

    - Registers their service instance.

    - Manages the underlying infrastructure (Docker, host machine).

    - Can call any job on behalf of customers if needed.

2.  **Customer (Requester):**

    - Requests a portal instance from an operator (off-chain agreement).

    - Provides necessary configuration (network, RPC URLs, etc.) to the operator.

    - Requests gateway configuration (desired port) from the operator.

    - Requests API key generation, providing their RSA public key for secure delivery.

    - Uses the provided API key (after decrypting it) to access data through the operator's gateway endpoint.

    - Likely pays the operator off-chain or via a separate smart contract mechanism for the service.

3.  **Tangle Network:**

    - Facilitates job submission and result delivery.

    - Provides the secure execution environment for the blueprint.

## Jobs

This blueprint exposes the following jobs callable via the Tangle Network:

1.  **`provision_portal` (ID: 1)**

    - **Action:** Deploys a new `sqd-portal` Docker container based on the standard `subsquid/sqd-portal` image and the provided `subsquid-docker-compose.yml`.

    - **Arguments:**

      - `network`: (String) e.g., "tethys" or "mainnet".

      - `key_path_on_host`: (String) Absolute path _on the operator's machine_ to the portal's network key file.

      - `rpc_url`: (String) Primary blockchain RPC endpoint URL.

      - `l1_rpc_url`: (Optional) L1 RPC endpoint URL (if applicable).

      - `boot_nodes`: (Optional>) List of boot nodes in " 
" format.

    - **Returns:** (String) Success message with the new Docker container ID.

    - **Called by:** Operator (usually based on a customer request).


2.  **`configure_gateway` (ID: 2)**

    - **Action:** Configures and starts (or restarts) the authenticated gateway proxy for a specific portal instance. Aborts any existing gateway task for that instance.

    - **Arguments:**

      - `portal_container_id`: (String) The container ID returned by `provision_portal`.

      - `listen_port`: (u16) The TCP port the gateway should listen on (e.g., 8090).

    - **Returns:** (String) Success message confirming configuration.

    - **Called by:** Operator (based on customer request to enable gateway).

3.  **`generate_api_key` (ID: 3)**

    - **Action:** Generates a new, secure API key for an existing, configured gateway, associates an optional rate limit, and adds it to the gateway's configuration.

    - **Arguments:**

      - `portal_container_id`: (String) The container ID of the portal whose gateway needs the key.

      - `limit_per_sec`: (Optional) Requests per second limit for this key (0 or None for unlimited).

      - `public_key`: (Vec) The requester's RSA public key (PKCS#1 DER format) used to encrypt the new API key.

    - **Returns:** (String) The new API key, RSA encrypted and base64 encoded.

    - **Called by:** Customer (or Operator). _Note: Payment verification might be added via a smart contract proxy._

## Setup & Running

1.  **Prerequisites:**

    - Rust toolchain

    - Docker

    - Access to a Tangle RPC endpoint

    - A funded Tangle account with keys

2.  **Build:**

    ```bash

    cargo build --release

    ```

3.  **Configure Environment:**

    - Set up environment variables for the Tangle connection, keystore, service ID, etc., typically via a `.env` file loaded by the `BlueprintEnvironment`.

4.  **Run:**

    ```bash

    ./target/release/subsquid-portal-blueprint-bin

    ```

## Development

- **Library Crate:** `subsquid-portal-blueprint-lib` contains the core logic, context, jobs, and gateway implementation.

- **Binary Crate:** `subsquid-portal-blueprint-bin` sets up the `BlueprintRunner`, router, producer, consumer, and context, then starts the blueprint service.

- **Tests:** E2E tests are located in `subsquid-portal-blueprint-lib/tests/e2e.rs` (requires Docker).