API Overview

dataprism-api is a serverless REST API for managed-storage authorization and gasless request queueing. Signed-in users request short-lived storage URLs; users also submit EIP-712 requests that relayers claim, process on-chain, and complete. The API does not submit blockchain transactions directly.

Tech stack

• Language: TypeScript 5.8
• Runtime: Node.js 20.x on AWS Lambda
• Framework: Serverless Framework 3.40 (HTTP API Gateway)
• Build: esbuild (bundled, minified)
• Storage: Amazon DynamoDB + a private, encrypted Amazon S3 bucket
• Validation: Zod 3.25
• Crypto: viem 2.31 (signature verification)
• Session auth: Privy access-token verification

Project structure

dataprism-api/
├── src/
│   ├── auth/relayerAuth.ts          # Relayer signature authentication
│   ├── auth/storageAuth.ts          # Privy authentication for storage URLs
│   ├── db/
│   │   ├── dynamo.ts                # DynamoDB operations for requests
│   │   └── relayers.ts              # DynamoDB operations for the relayer whitelist
│   ├── handlers/
│   │   ├── admin/relayers.ts        # Admin endpoints (manage whitelist)
│   │   ├── signStorageOperation.ts   # POST /storage/sign
│   │   ├── getRequest.ts            # GET /requests/{id}
│   │   ├── listRequests.ts          # GET /requests
│   │   ├── submitRequest.ts         # POST /requests
│   │   └── updateRequestStatus.ts   # PATCH /requests/{id}
│   ├── storage/signing.ts           # Scoped object keys + signed operations
│   ├── types/request.ts             # Types and the RequestAction enum
│   ├── utils/http.ts                # HTTP response helpers + CORS
│   └── validation/schemas.ts        # Zod schemas per action
└── serverless.yml                   # Serverless Framework configuration

Request lifecycle

pending → processing → success
                    ↘ failed

• pending: created by the user via POST /requests.
• processing: claimed by a relayer (PATCH with status=processing). The pending → processing transition is atomic via a DynamoDB conditional expression, preventing two relayers from claiming the same request.
• success: completed; relayer supplied a txHash.
• failed: relayer supplied an errorMessage.

Request state (DynamoDB)

Three tables (suffixed by stage, e.g. -dev / -prod):

• dataprism-requests-{stage}: primary key requestId (UUID). Global secondary indexes: signer-createdAt-index, status-createdAt-index, and a chain index (queried by chainName).
• dataprism-relayers-{stage}: the relayer whitelist, primary key address.
• dataprism-ratelimit-{stage}: per-client API rate-limit counters.

Both use on-demand (PAY_PER_REQUEST) billing.

Configuration

Environment variables (set in serverless.yml):

Default region is eu-west-1; functions run with 256 MB memory and a 29 s timeout.

Install, run, deploy

npm install        # Install dependencies
npm run offline    # Run locally with serverless-offline (port 3000)
npm run build      # Compile TypeScript
npm run deploy      # Deploy to AWS (dev stage, eu-west-1)
npm run deploy:prod # Deploy to the prod stage

Deploying provisions the Lambda functions, HTTP API Gateway, DynamoDB tables, the private managed-storage bucket, and least-privilege IAM permissions for object operations.

CORS

All responses include:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization, X-Relayer-Address, X-Relayer-Signature, X-Relayer-Timestamp, X-Admin-Key
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS

The managed bucket has a separate CORS policy: production permits https://app.dataprism.co, while development permits the local frontend origins.

See Endpoints for the full route reference and Authentication for storage, relayer, and admin auth.