dexignation-api

Core backend services powering DEXignation.

DEXignation의 핵심 백엔드 서비스.

---

What is this? / 이 저장소는?

dexignation-api is the HTTP + indexer service that sits between the on-chain DEXignation contracts and consumer clients (the website, wallets, MetaMask Snap, third-party dApps).

dexignation-api는 온체인 DEXignation 컨트랙트와 소비자 클라이언트(웹사이트, 지갑, MetaMask Snap, 외부 dApp) 사이를 잇는 HTTP + 인덱서 서비스입니다.

It does not hold private keys. It does not sign transactions on behalf of users. It is a read-side service that:

• Resolves name.dex → on-chain addresses (forward resolution).
• Resolves an EVM address → its registered .dex name (reverse resolution).
• Indexes registry events into a local database for fast lookups, statistics, and search.

사용자 키를 보관하지 않고, 사용자를 대신해 트랜잭션에 서명하지도 않습니다. 읽기 측 서비스로서:

• name.dex → 온체인 주소 해결 (정방향).
• EVM 주소 → 등록된 .dex 이름 해결 (역방향).
• 빠른 조회·통계·검색을 위해 레지스트리 이벤트를 로컬 DB에 인덱싱.

---

Stack / 스택

• Runtime: Node.js 22+, TypeScript 5.7, ES modules
• HTTP: Express 4, Helmet, CORS, rate limiting, structured pino logging
• Chain: viem public client
• DB: Prisma 6 (SQLite default; PostgreSQL recommended for prod)
• Validation: Zod schemas at the environment and request boundary
• Tests: Vitest

---

Endpoints / 엔드포인트

GET /health

Health probe. Returns 200 with the latest block number if the configured RPC is reachable; 503 otherwise.

설정된 RPC가 도달 가능하면 최신 블록 번호와 함께 200을 반환, 그렇지 않으면 503.

curl http://localhost:3000/health
# {"ok":true,"service":"dexignation-api","chainId":137,"block":"58712390",...}

GET /resolve/:name

Forward-resolve a .dex name to chain-specific addresses.

.dex 이름을 체인별 주소로 정방향 해결.

curl http://localhost:3000/resolve/alice.dex
# {
#   "name": "alice.dex",
#   "node": "0x...",
#   "owner": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
#   "expired": false,
#   "addresses": {
#     "polygon": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
#     "ethereum": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9A0B1C2D3E"
#   }
# }

GET /reverse/:address

Reverse-resolve an EVM address to its registered .dex name.

주소를 등록된 .dex 이름으로 역방향 해결.

curl http://localhost:3000/reverse/0x71C7656EC7ab88b098defB751B7401B5f6d8976F
# {"address":"0x71C7...","name":"alice.dex"}

---

Development / 개발

Prerequisites / 사전 요구사항

• Node.js v22 or later
• An RPC URL for the chain where DEXignation is deployed
• Contract addresses for the deployed registry and resolver

Quick start / 빠른 시작

git clone https://github.com/DEXignation/dexignation-api
cd dexignation-api
npm install
cp .env.example .env
# Edit .env: set RPC_URL, REGISTRY_ADDRESS, RESOLVER_ADDRESS

npm run prisma:generate
npm run prisma:migrate
npm run dev

The server starts on http://localhost:3000 and watches for changes.

http://localhost:3000에서 시작하며 변경을 감시합니다.

Tests / 테스트

npm test           # one-shot
npm run test:watch # watch mode

Indexer / 인덱서

The indexer is a separate process that consumes on-chain events and writes them to the database. Run it alongside the HTTP server:

인덱서는 온체인 이벤트를 소비하여 DB에 기록하는 별도 프로세스입니다.

npm run indexer

In production, run both processes under a supervisor (PM2, systemd, Kubernetes Deployments, etc.).

운영 환경에서는 두 프로세스를 supervisor(PM2, systemd, K8s Deployment 등) 아래에서 실행하세요.

---

Production deployment / 운영 배포

Database

The Prisma schema defaults to SQLite for friction-free local development. For production, switch to PostgreSQL:

Prisma 스키마는 마찰 없는 로컬 개발을 위해 SQLite를 기본값으로 합니다. 운영에서는 PostgreSQL로 전환하세요:

1. Edit prisma/schema.prisma: change provider = "sqlite" to provider = "postgresql".
2. Set DATABASE_URL=postgresql://user:pass@host:5432/dexignation.
3. npm run prisma:deploy.

Docker

A Dockerfile is included. Build and run:

Dockerfile이 포함되어 있습니다.

docker build -t dexignation-api:latest .
docker run --env-file .env -p 3000:3000 dexignation-api:latest

Process model / 프로세스 모델

The HTTP server and the indexer are separate processes so the indexer can crash or restart without affecting the read API. Run them as sibling deployments and share a database.

HTTP 서버와 인덱서는 별도 프로세스라 인덱서가 크래시·재시작되어도 읽기 API에 영향이 없습니다. 형제 Deployment로 두고 DB만 공유하세요.

---

Security / 보안

• This service holds no private keys and signs no transactions.
• All write paths to the chain go through the user's own wallet.
• Read-only RPC calls are rate-limited per IP (RATE_LIMIT_PER_MINUTE).
• See SECURITY.md for vulnerability disclosure.

키 보관 없음, 트랜잭션 서명 없음. 모든 쓰기는 사용자 본인 지갑을 통해 이루어집니다. IP당 rate-limit 적용. 취약점 제보는 SECURITY.md 참고.

---

Related repositories / 관련 저장소

Repo	Purpose	역할
dexignation-contracts	Smart contracts	스마트 컨트랙트
dexignation-api	This repo	본 저장소
dexignation-snap	MetaMask Snap	MetaMask Snap
dexignation-docs	Official docs	공식 문서

---

License / 라이선스

MIT. See LICENSE.

MIT. LICENSE 참고.