Address Lookup Table API

A Node.js/Express API for fetching and storing Solana Address Lookup Table (ALT) information with PostgreSQL integration.

Features

• Fetch address lookup table information from Solana blockchain
• Store lookup table results in PostgreSQL database
• Query stored lookup tables
• Search for addresses across all lookup tables
• RESTful API endpoints

Prerequisites

• Node.js (v14 or higher)
• PostgreSQL (v12 or higher)
• npm or yarn

Installation

1. Clone the repository:

git clone <repository-url>
cd address-lookup-table

2. Install dependencies:

npm install

3. Set up PostgreSQL database:

# Create database
createdb address_lookup_table

# Or using psql
psql -U postgres
CREATE DATABASE address_lookup_table;

4. Configure environment variables:

cp .env.example .env
# Edit .env with your database credentials and configuration

5. The database tables will be created automatically when the server starts.

Configuration

Edit the .env file with your configuration:

# Server Configuration
PORT=3001

# Solana RPC Endpoint
RPC_ENDPOINT=https://api.mainnet-beta.solana.com

# PostgreSQL Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=address_lookup_table
DB_USER=postgres
DB_PASSWORD=your_password_here

Running the Server

Development mode:

npm run dev

The server will start on http://localhost:3001 (or the port specified in your .env file).

API Endpoints

1. Health Check

GET /api/health

Returns server status and database connection status.

Response:

{
  "status": "ok",
  "message": "Server is running",
  "database": "connected"
}

2. Add Lookup Tables

POST /api/add

Fetches lookup table information from Solana and stores it in the database.

Request Body:

{
  "lookuptables": [
    "ALT_PUBLIC_KEY_1",
    "ALT_PUBLIC_KEY_2"
  ]
}

Response:

{
  "data": [
    {
      "key": "ALT_PUBLIC_KEY_1",
      "publicKeys": ["ADDRESS_1", "ADDRESS_2", ...]
    }
  ],
  "invalidAddresses": [],
  "invalidAlt": []
}

3. Get All Lookup Tables

GET /api/lookuptables

Retrieves all stored lookup tables from the database.

Response:

{
  "data": [
    {
      "id": 1,
      "lookup_table_key": "ALT_PUBLIC_KEY",
      "addresses": ["ADDRESS_1", "ADDRESS_2", ...],
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "count": 1
}

4. Get Specific Lookup Table

GET /api/lookuptables/:key

Retrieves a specific lookup table by its public key.

Response:

{
  "data": {
    "id": 1,
    "lookup_table_key": "ALT_PUBLIC_KEY",
    "addresses": ["ADDRESS_1", "ADDRESS_2", ...],
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}

5. Search Address

GET /api/search/:address

Searches for all lookup tables containing a specific address.

Response:

{
  "data": [
    {
      "id": 1,
      "lookup_table_key": "ALT_PUBLIC_KEY",
      "addresses": ["ADDRESS_1", "ADDRESS_2", ...],
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "count": 1
}

6. Delete Lookup Table

DELETE /api/lookuptables/:key

Deletes a lookup table and its associated addresses from the database.

Response:

{
  "status": "success",
  "message": "Lookup table deleted"
}

Database Schema

lookup_tables

• id (SERIAL PRIMARY KEY)
• lookup_table_key (VARCHAR(44) UNIQUE) - Solana public key
• created_at (TIMESTAMP)
• updated_at (TIMESTAMP)

addresses

• id (SERIAL PRIMARY KEY)
• lookup_table_id (INTEGER, FOREIGN KEY)
• address (VARCHAR(44)) - Solana public key
• position (INTEGER) - Position in the lookup table array
• created_at (TIMESTAMP)

Development

Project Structure

.
├── src/
│   ├── index.ts          # Main application entry point
│   ├── db/
│   │   ├── database.ts   # Database connection and queries
│   │   └── schema.sql    # SQL schema definition
│   ├── solana/
│   │   └── solana.ts     # Solana blockchain interaction
│   └── type.ts           # TypeScript type definitions
├── .env.example          # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

Error Handling

The API includes comprehensive error handling:

• Invalid Solana public keys are returned in the invalidAddresses array
• Invalid lookup tables are returned in the invalidAlt array
• Database errors are logged and appropriate HTTP status codes are returned
• The server can run without database connection (with limited functionality)

License

ISC