README.md

Faucet Backend API

This API provides endpoints for interacting with two main tables: faucet.solana_balances and faucet.rate_limits. Below are the available endpoints for each table.

---

Development

1. Clone the repository

   git clone <repository-url>

2. Install dependencies

   yarn install

3. Set up your .env file with the following

   POSTGRES_STRING=postgresql://<user>:<password>@<host>:<port>/<database>
   PROJECT_ID=<GCP Project ID>

   NOTE if you want to send request directly to Analytics DB, use Cloud SQL Auth Proxy to setup a connection

    ./cloud-sql-proxy --address 0.0.0.0 --port 5434 <SQL DB Connection String>
   

4. OPTIONAL In order to test the Github API locally, you need to provide a Github Personal Access Token in your .env file. The token only needs read:user and public_repo

   GH_TOKEN=<Github Token>
   

5. Start the server

   yarn start

6. Access the API at http://localhost:3000/api.

---

Solana Balances Endpoints

Create a New Solana Balance

POST /api/solana-balances

• Description: Adds a new Solana account balance.
• Request Body:

  {
    "account": "string",
    "balance": "number"
  }

• Curl Command:

  curl -v -X POST http://localhost:3000/api/solana-balances \
  -H "Content-Type: application/json" \
  -d '{"account": "test_account_1", "balance": 100.50}'

• Response:

  {
    "id": 1,
    "account": "string",
    "balance": "number",
    "date": "timestamp"
  }

Get All Balances for an Account

GET /api/solana-balances/account/:account

• Description: Retrieves all balances for a specific Solana account.
• Curl Command:

  curl -v http://localhost:3000/api/solana-balances/account/test_account_1

• Response:

  [
    {
      "id": 1,
      "account": "string",
      "balance": "number",
      "date": "timestamp"
    }
  ]

Get Recent Balances (Last Month)

GET /api/solana-balances/recent

• Description: Retrieves all Solana account balances from the past month, ordered by date.
• Curl Command:

  curl -v http://localhost:3000/api/solana-balances/recent

• Response:

  [
    {
      "account": "string",
      "balance": "number",
      "date": "timestamp"
    }
  ]

---

Rate Limits Endpoints

Create a New Rate Limit

POST /api/rate-limits

• Description: Adds a new rate limit entry.
• Request Body:

  {
    "key": "string",
    "timestamps": ["number"]
  }

• Curl Command:

  curl -v -X POST http://localhost:3000/api/rate-limits \
  -H "Content-Type: application/json" \
  -d '{"key": "test_key_1", "timestamps": [1635793421]}'

• Response:

  {
    "key": "string",
    "timestamps": ["number"]
  }

Get a Rate Limit by Key

GET /api/rate-limits/:key

• Description: Retrieves the rate limit entry for a specific key.
• Curl Command:

  curl -v http://localhost:3000/api/rate-limits/test_key_1

• Response:

  {
    "key": "string",
    "timestamps": ["number"]
  }

Update Timestamps for a Rate Limit

PUT /api/rate-limits/:key

• Description: Updates the timestamps for a specific rate limit key.
• Request Body:

  {
    "timestamps": ["number"]
  }

• Curl Command:

  curl -v -X PUT http://localhost:3000/api/rate-limits/test_key_1 \
  -H "Content-Type: application/json" \
  -d '{"timestamps": [1635793500]}'

• Response:

  {
    "key": "string",
    "timestamps": ["number"]
  }

Create a New Rate Limit Combination

POST /api/rate-limits-combo

• Description: Adds a new rate limit combination entry. Each combination of ip_address, wallet_address, and github_userid is checked for uniqueness before inserting to DB.
• Request Body:

  {
    "ip_address": "string",
    "wallet_address": "string",
    "github_userid": "string"
  }

• Curl Command:

  curl -v -X POST http://localhost:3000/api/rate-limits-combo \
    -H "Content-Type: application/json" \
    -d '{
      "ip_address": "19216801",
      "wallet_address": "wallet_123",
      "github_userid": "user123"
    }'

• Response:

 {
  "id": "3",
 "ip_address":"19216801",
 "wallet_address":"wallet_123",
 "github_userid":"user123"
 }

---

Github Validation Endpoints

Validate Github User ID

GET /api/github-validation/:userId

• Description: Validates a Github user by fetching their information from the Github API using their user ID.

• Request Params:

  • userId (string): The Github User ID to validate.

• Curl Command:

  curl -v http://localhost:3000/api/gh-validation/exampleUser 

-Response:

{
  "valid": "boolean"
} 

---

Error Handling

All endpoints return appropriate HTTP status codes:

• 201 Created for successful creations.
• 200 OK for successful data retrieval or updates.
• 404 Not Found if the requested resource does not exist.
• 500 Internal Server Error for unhandled exceptions.