Project Liberty Logo

Frequency Developer Gateway

Last updated: March 28, 2025

Version: 1.0.0

Table of Contents

1. Project Overview

The Frequency Developer Gateway is a suite of microservices designed to simplify interactions with the Frequency blockchain, bridging the gap between Web2 and Web3 development. It provides a familiar REST API interface that abstracts away complex blockchain operations, making it more accessible for traditional web developers. As a decentralized SSO solution, it offers OAuth2-style endpoints and standard flows that mirror traditional providers while leveraging blockchain technology for enhanced security, transparency, and user data sovereignty.

Core Purpose

mindmap root((Frequency Developer Gateway)) Purpose Bridge Web2 and Web3 Simplify blockchain interactions Enable social applications Abstract complex operations Provide familiar REST APIs Value Proposition Lower adoption barriers Accelerate development Promote decentralization Maintain flexibility Enable diverse implementations

SSO Capabilities

mindmap root((Decentralized SSO)) Traditional Integration OAuth2-Style Endpoints /authorize endpoint /token endpoint Standard SSO Flows Compatible API Interfaces Drop-in Replacement Blockchain Features Decentralized Authentication User-Owned Identity Granular Permissions Itemized Control User Data Sovereignty Audit Trail Transparent Immutable Open Integration Model

High-Level Architecture

flowchart LR C[Client Applications] --> Gateway subgraph Gateway["Gateway Microservices"] A[Account Service] --- G[Graph Service] G --- CP[Content Publishing Service] CP --- CW[Content Watcher Service] end Gateway --> F[Frequency Blockchain] CP --> IPFS[IPFS Storage]

2. Scope of Work

1. Maintenance

  • Monitor and resolve issues reported on the GitHub repository
  • Update dependencies and libraries to ensure security and compatibility
  • Optimize existing code for performance and scalability

2. Feature Enhancements

  • Collaborate with Project Liberty to identify and prioritize new features
  • Implement new features as specified in the project roadmap
  • Ensure compatibility with the latest developments in the Frequency blockchain ecosystem

Upcoming Features Include:

3. Code Quality and Documentation

  • Adhere to best practices in software development, including code reviews and testing
  • Maintain and enhance project documentation to assist contributors and end-users
  • Write unit, integration, and end-to-end tests to ensure system reliability

4. Community Engagement

  • Assist contributors with pull requests and code reviews
  • Respond to developer inquiries and provide technical guidance to companies integrating with the Frequency Developer Gateway

5. Reporting

  • Provide bi-weekly progress updates to the designated person at Project Liberty
  • Maintain a clear log of tasks completed and issues resolved

3. Microservices Breakdown

3.1 Account Service

mindmap root((Account Service)) Core Functions Account Creation User Registration Provider Setup Handle Management Username Claims Handle Updates Key Management Add Keys Retrieve Keys Key Rotation SIWF Integration Web3 Authentication Wallet Integration API Auth Token Management Permission Control
Key Features
  • Create and manage DSNP accounts (MSA Ids)
  • Claim and manage unique handles (usernames)
  • Add and retrieve keys for account authentication
  • Retrieve delegation information for MSA Ids
  • Seamless integration with Web3 wallets

3.2 Graph Service

mindmap root((Graph Service)) Core Functionality Fetch social graphs Update social connections Watch graph changes Manage follows/unfollows Architecture API Component Worker Component Redis job queue Graph monitoring Use Cases Social network connections Content discovery User recommendations Private vs public graphs
Key Features
  • Retrieve public and private social connection data
  • Follow/unfollow users on the network
  • Monitor changes in social graphs
  • Support for reconnection services for migrating users

3.3 Content Publishing Service

mindmap root((Content Publishing Service)) Core Functionality Asset file uploads Create broadcasts/posts Create replies Create reactions Update/delete content Update profiles Architecture API Controller Worker Process BullMQ Queue IPFS Integration Use Cases Social media posts Content management User interactions Media sharing
Key Features
  • Upload asset files to off-chain storage (IPFS)
  • Create new broadcasts (posts) on the network
  • Reply to existing content
  • Add reactions to content
  • Update or remove existing content
  • Manage user profile information
  • Monitor and manage publishing jobs

3.4 Content Watcher Service

mindmap root((Content Watcher Service)) Core Functionality Parse DSNP messages Webhook integration Flexible content filtering Scanner operations Architecture Blockchain scanner Message parser Webhook dispatcher Block range monitoring Use Cases Content discovery Notifications Feed generation Custom integrations
Key Features
  • Monitor and parse messages on Frequency blockchain
  • Send content updates to registered webhooks
  • Filter content by schema and MSA Id
  • Control scanning operations (start/stop/restart)
  • Specify custom block ranges for content retrieval

4. Technical Architecture

4.1 Component Interaction

sequenceDiagram participant Client as Client Application participant AS as Account Service participant GS as Graph Service participant CPS as Content Publishing Service participant CWS as Content Watcher Service participant Freq as Frequency Blockchain Client->>AS: Create/Authenticate User AS->>Freq: Submit Account Extrinsic Freq-->>AS: Confirm Account Creation AS-->>Client: Return Account Details Client->>GS: Establish Social Connections GS->>Freq: Update Social Graph Freq-->>GS: Confirm Graph Update GS-->>Client: Return Updated Graph Client->>CPS: Publish New Content CPS->>IPFS: Store Content Data IPFS-->>CPS: Return Content URI CPS->>Freq: Announce Content Publication Freq-->>CPS: Confirm Publication CPS-->>Client: Return Content Publication Status CWS->>Freq: Monitor for New Content Freq-->>CWS: Send New Content Announcements CWS->>Client: Deliver Content Updates via Webhook

4.2 Technology Stack

mindmap root((Technology Stack)) Backend Framework NestJS TypeScript Node.js Data Management Redis BullMQ Job queues Blockchain Integration Polkadot API DSNP Protocol Frequency Chain Storage IPFS Testing Jest Supertest E2E Tests Containerization Docker Docker Compose Documentation Swagger OpenAPI mdBook

5. Setup & Installation

5.1 Prerequisites

5.2 Quick Start Guide

git clone git@github.com:ProjectLibertyLabs/gateway.git
cd gateway
./start.sh

5.3 Service-Specific Setup

Account Service Setup
# Copy environment template
cp env-files/account.template.env .env.account

# Start supporting services
./scripts/account/restart-chain-docker.sh

# Start account service
docker compose -f docker-compose.yaml -f docker-compose-e2e.account.yaml --profile account up -d

# Verification
# Access Swagger UI: http://localhost:3000/api/docs/swagger
# View queues: http://localhost:3000/queues
Graph Service Setup
# Copy environment template
cp env-files/graph.template.env .env

# Start services
docker compose up -d redis frequency graph-service-api graph-service-worker

# Setup with account data
make setup-account

# Verification
# Access Swagger UI: http://localhost:3012/docs/swagger
Content Publishing Service Setup
# Copy environment template
cp env-files/content-publishing.template.env .env.content-publishing

# Start supporting services
docker compose up -d frequency redis ipfs

# Start application services
npm run start:content-publishing-api:dev
npm run start:content-publishing-worker:dev

# Setup with account data
make setup-account

# Verification
# Access Swagger UI: http://localhost:3000/docs/swagger
Content Watcher Service Setup
# Copy environment template
cp env-files/content-watcher.template.env .env.content-watcher

# Start required services
docker compose up -d frequency redis ipfs

# Start Content Watcher
npm run start:content-watcher:dev

# Verification
# Access Swagger UI: http://localhost:3000/api/docs/swagger

6. Usage Examples

6.1 Building a Social Application

flowchart TD subgraph "User Authentication Flow" A1[Client App] --> A2[Account Service: Create User] A2 --> A3[Sign In With Frequency] A3 --> A4[Return Account & Token] end subgraph "Social Connection Flow" B1[Client App] --> B2[Graph Service: Fetch User's Graph] B2 --> B3[Follow/Unfollow Users] B3 --> B4[Return Updated Connections] end subgraph "Content Creation Flow" C1[Client App] --> C2[Content Publishing: Upload Media] C2 --> C3[Create Post with Media] C3 --> C4[Return Post Status] end subgraph "Content Discovery Flow" D1[Client Server] --> D2[Content Watcher: Register Webhook] D2 --> D3[Receive Content Updates] D3 --> D4[Process & Display to User] end

6.2 API Usage Examples

Account Service

// Create a user account
POST /api/v1/accounts
{
  "handle": "username",
  "owner": "0x..."
}

// Retrieve account information
GET /api/v1/accounts/{msaId}

// Add a key to an account
POST /api/v1/accounts/{msaId}/keys
{
  "keyType": "...",
  "publicKey": "0x..."
}

Graph Service

// Fetch a user's graph
GET /api/v1/graph/{msaId}

// Follow another user
POST /api/v1/graph/{fromMsaId}/connections
{
  "toMsaId": 123
}

// Unfollow a user
DELETE /api/v1/graph/{fromMsaId}/connections/{toMsaId}

Content Publishing Service

// Upload an asset
POST /api/v1/assets
[multipart/form-data]

// Create a post
POST /api/v1/broadcasts
{
  "fromId": 123,
  "content": "Hello world!",
  "assets": ["assetId1", "assetId2"]
}

// Create a reply
POST /api/v1/replies
{
  "fromId": 123,
  "inReplyTo": "urlOfOriginalPost",
  "content": "This is a reply"
}

Content Watcher Service

// Register a webhook
POST /api/v1/webhooks
{
  "url": "https://example.com/webhook",
  "filters": {
    "msaIds": [123, 456],
    "schemas": ["broadcast", "reply"]
  }
}

// Start scanning
POST /api/v1/scanner/start

// Get scanner status
GET /api/v1/scanner/status

7. Development & Testing

7.1 Development Environment

Local Development
  • Each service can be run locally for development
  • Supporting services (Redis, Frequency, IPFS) can be run in Docker
  • Hot-reloading enabled in development mode
  • Debug configurations available for VSCode

7.2 Testing

Unit Tests
# Run account service tests
npm run test:account

# Run graph service tests
npm run test:graph

# Run content publishing tests
npm run test:content-publishing

# Run content watcher tests
npm run test:content-watcher
E2E Tests
# Run account service E2E tests
make test-e2e-account

# Run graph service E2E tests
npm run test:e2e:graph

# Run content publishing E2E tests
npm run test:e2e:content-publishing

# Run content watcher E2E tests
npm run test:e2e:content-watcher

7.3 Code Quality

# Run linter
npm run lint

# Format code
npm run format

Connect With Us