Skip to content

Latest commit

 

History

History
243 lines (201 loc) · 5.53 KB

README.md

File metadata and controls

243 lines (201 loc) · 5.53 KB

VOI Name Service API

A caching resolver service for VOI (.voi) names and addresses.

API Endpoints

Single Name/Address Resolution

Get Name from Address

GET /api/name/[address]?ignoreCache=false

Resolves an Algorand address to its corresponding VOI name. For multiple addresses, use comma-separated values.

Parameters:

  • address (string): The Algorand address to resolve, or multiple comma-separated addresses (max 50)
  • ignoreCache (boolean, optional): Skip cache lookup (default: false)

Examples:

GET /api/name/ADDRESS1
GET /api/name/ADDRESS1,ADDRESS2,ADDRESS3

Response:

{
  "results": [
    {
      "address": "ADDRESS1",
      "name": "example.voi",
      "cached": true
    }
  ]
}

Get Address from Name

GET /api/address/[name]?ignoreCache=false

Resolves a VOI name to its corresponding Algorand address. For multiple names, use comma-separated values.

Parameters:

  • name (string): The VOI name to resolve (must end in .voi), or multiple comma-separated names (max 50)
  • ignoreCache (boolean, optional): Skip cache lookup (default: false)

Examples:

GET /api/address/name1.voi
GET /api/address/name1.voi,name2.voi,name3.voi

Response:

{
  "results": [
    {
      "name": "name1.voi",
      "address": "R7TBR3Y5QCM6Y2OPQP3BPNUQG7TLN75IOC2WTNRUKO4VPNSDQF52MZB4ZE",
      "cached": true
    }
  ]
}

Batch Resolution

Resolve Multiple Addresses to Names

POST /api/name

Request Body:

{
  "addresses": ["ADDRESS1", "ADDRESS2", ...],
  "ignoreCache": false
}

Parameters:

  • addresses (string[]): Array of Algorand addresses (max 50)
  • ignoreCache (boolean, optional): Skip cache lookup (default: false)

Resolve Multiple Names to Addresses

POST /api/address

Request Body:

{
  "names": ["name1.voi", "name2.voi", ...],
  "ignoreCache": false
}

Parameters:

  • names (string[]): Array of VOI names (max 50)
  • ignoreCache (boolean, optional): Skip cache lookup (default: false)

Batch Response Format:

{
  "results": [
    {
      "address": "...",  // or "name" for name lookups
      "name": "example.voi",  // or "address" for address lookups
      "cached": true
    }
    // ... more results
  ]
}

Error Responses

400 Bad Request

{
  "error": "Name/Address parameter is required"
}

404 Not Found

{
  "error": "Name/Address not found"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Caching

The API implements a dual-cache system with the following features:

  • Separate caches for name-to-address and address-to-name lookups
  • Results are cached for 1 hour by default, including not-found responses
  • Cache can be bypassed using ignoreCache=true
  • When bypassing cache, the service will still update both caches with fresh values
  • Bidirectional caching: when a name or address is resolved, both caches are updated
  • Null values are cached to prevent repeated lookups of non-existent names/addresses
  • Cache status is indicated in the X-Cache header:
    • HIT: Served from cache
    • MISS: Freshly resolved
    • BYPASS: Cache was ignored
    • MIXED: For batch requests with mixed cache results

Cache Tables

name_cache

  • Primary key: name (lowercase)
  • Stores name-to-address mappings
  • Handles multiple names pointing to the same address
  • Null addresses indicate non-existent names
  • Schema: 
    CREATE TABLE name_cache (
    name TEXT PRIMARY KEY,
    address TEXT NULL,  -- NULL indicates name not found
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
  • Constraints:
    • Name format: Must match ^[a-z0-9-]+\.voi$
    • Address format: Must match ^[A-Z2-7]{58}$ when not null
  • Indexes:
    • Primary key on name
    • Secondary index on address

address_cache

  • Primary key: address
  • Stores address-to-name mappings
  • Maintains the canonical name for each address
  • Null names indicate non-existent addresses
  • Schema: 
    CREATE TABLE address_cache (
    address TEXT PRIMARY KEY,
    name TEXT NULL,  -- NULL indicates address not found
    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);
  • Constraints:
    • Address format: Must match ^[A-Z2-7]{58}$
    • Name format: Must match ^[a-z0-9-]+\.voi$ when not null
  • Indexes:
    • Primary key on address
    • Secondary index on name

Security

The API implements the following security measures:

CORS Policy

The API has a permissive CORS policy that allows:

  • Origins: * (all origins)
  • Methods: GET, POST, OPTIONS
  • Headers: Content-Type

Row Level Security

The cache tables implement Row Level Security (RLS) with the following policies:

  • Public read access is allowed for all records
  • Write access (insert/update) is restricted to the service role
  • No delete access is provided

Rate Limiting

  • Batch requests are limited to 50 items per request
  • Individual requests are processed sequentially

Environment Variables

Required environment variables:

PUBLIC_SUPABASE_URL=your_supabase_url
PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Development

  1. Clone the repository
  2. Install dependencies: 
    npm install
  3. Create a .env file with the required environment variables
  4. Run the development server: 
    npm run dev

Deployment

The API is designed to be deployed on Vercel using the SvelteKit adapter. Simply push to your repository and Vercel will handle the deployment automatically.