docs

.env.sample

@@ -1,4 +1,5 @@
 NC_REGISTRY_ENDPOINT=
+NC_HEADLESS_JWT_TOKEN=
 NC_UPSTREAM_PLANET=
 NC_DOWNSTREAM_PLANET=
 NC_VAULT_ADDRESS=
@@ -20,5 +21,6 @@ SLACK__BOT_USERNAME=
 SLACK__CHANNEL=
 
 USE_RDB=
+DATABASE_URL=
 NC_UPSTREAM__RDB__START_BLOCK_INDEX=
 NC_DOWNSTREAM__RDB__START_BLOCK_INDEX=

.vscode/launch.json

@@ -0,0 +1,32 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "type": "node",
+        "request": "launch",
+        "name": "Debug Yarn Start",
+        "runtimeExecutable": "yarn",
+        "runtimeArgs": ["start"],
+        "skipFiles": ["<node_internals>/**"],
+        "cwd": "${workspaceFolder}",
+        "envFile": "${workspaceFolder}/.env",
+        "sourceMaps": true,
+        "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+        "console": "integratedTerminal"
+      },
+      {
+        "type": "node",
+        "request": "launch",
+        "name": "Debug Jest Tests",
+        "program": "${workspaceFolder}/node_modules/.bin/jest",
+        "args": [
+          "--runInBand"
+        ],
+        "runtimeExecutable": "node",
+        "skipFiles": ["<node_internals>/**"],
+        "cwd": "${workspaceFolder}",
+        "console": "integratedTerminal",
+        "internalConsoleOptions": "openOnSessionStart"
+      }
+    ]
+  }

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Development Environment Setup and Contribution Guide
+
+This document explains how to contribute to the NineChronicles Bridge project or set up a local development environment.
+
+## Requirements
+
+- Node.js (>=16)
+- Yarn
+- Docker and Docker Compose
+- PostgreSQL
+
+## Local Development Environment Setup
+
+### 1. Install Dependencies
+
+```bash
+yarn install
+```
+
+### 2. Environment Variable Setup
+
+Create a `.env` file in the project root and set it up as follows:
+
+```
+# Database settings
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/local_db
+
+# Planet settings
+PLANETS_JSON_PATH=./local-test/local-planet-sample.json
+
+# Account settings
+NC_UPSTREAM__PRIVATE_KEY=YOUR_UPSTREAM_PRIVATE_KEY
+NC_DOWNSTREAM__PRIVATE_KEY=YOUR_DOWNSTREAM_PRIVATE_KEY
+
+# Vault settings
+NC_VAULT_ADDRESS=YOUR_VAULT_ADDRESS_HEX
+NC_VAULT_AVATAR_ADDRESS=YOUR_VAULT_AVATAR_ADDRESS_HEX
+
+# Initial block index settings (tracking start point)
+NC_UPSTREAM__RDB__START_BLOCK_INDEX=YOUR_UPSTREAM_START_BLOCK_INDEX
+NC_DOWNSTREAM__RDB__START_BLOCK_INDEX=YOUR_DOWNSTREAM_START_BLOCK_INDEX
+
+# PostgreSQL usage setting
+USE_RDB=true
+
+# Optional settings
+NC_UPSTREAM_NCG_MINTER=YOUR_UPSTREAM_NCG_MINTER_ADDRESS
+```
+
+> Note: In production environments, make sure to securely set `NC_UPSTREAM__PRIVATE_KEY` and `NC_DOWNSTREAM__PRIVATE_KEY`.
+
+### 3. PostgreSQL Setup
+
+Run PostgreSQL using Docker Compose:
+
+```bash
+docker-compose up -d
+```
+
+### 4. Planet Setup
+
+Planet information is managed in JSON files. A sample file is located at `local-test/local-planet-sample.json`.
+You can modify this file or create a new one as needed.
+
+For local testing, you can run a simple HTTP server to serve the Planet information:
+
+```bash
+cd local-test
+npx http-server -p 8080
+```
+
+Then, you can set PLANETS_JSON_PATH to `http://localhost:8080/local-planet-sample.json`.
+
+### 5. Project Build and Run
+
+```bash
+# Generate GraphQL code and Prisma client
+yarn codegen
+
+# Run the project
+yarn start
+```
+
+## Code Style
+
+This project uses Biome as a code formatter:
+
+```bash
+npx @biomejs/biome check --apply .
+``` 

README.ko.md

@@ -0,0 +1,35 @@
+# NineChronicles Bridge
+
+나인크로니클의 서로 다른, 즉 Planet A와 Planet B 간 NCG 송금을 위한 브릿지입니다.
+
+## 개요
+
+이 프로젝트는 서로 다른 Planet 간 NCG 토큰을 전송하기 위한 브릿지 역할을 합니다. 기본적인 구조는 다음과 같습니다.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UpstreamAddress as Planet A 주소 (Upstream)
+    participant Bridge as 브릿지
+    participant Vault as Planet B의 Vault 주소
+    participant DownstreamAddress as Planet B 주소 (Downstream)
+
+    User->>UpstreamAddress: NCG 송금 (+ 목적지 주소 정보)
+    UpstreamAddress-->>Bridge: 트랜잭션 확인
+    Bridge->>Bridge: 트랜잭션 검증
+    Bridge->>Vault: 송금 지시
+    Vault->>DownstreamAddress: NCG 송금
+    DownstreamAddress-->>User: 최종 수령 확인
+
+    Note over User,DownstreamAddress: 반대 방향(Planet B → Planet A)도 동일한 방식으로 작동
+```
+
+## 구현
+
+- **트랜잭션 모니터링**: Headless GraphQL 클라이언트를 통해 각 Planet의 트랜잭션을 실시간으로 모니터링합니다.
+- **상태 저장**: PostgreSQL 데이터베이스를 사용하여 각 트랜잭션의 처리 상태와 진행 상황을 추적합니다.
+- **토큰 송금**: 브릿지는 사용자가 지정한 목적지 주소로 직접 서명하여 NCG를 송금합니다.
+
+## 시작하기
+
+프로젝트 설정 및 실행 방법에 대한 자세한 내용은 [CONTRIBUTING.md](CONTRIBUTING.md) 파일을 참조하세요.

README.md

@@ -1,16 +1,35 @@
-# NineChronicles Asset Bridges
-As name suggests, this app bridges assets between Nine Chronicles networks.
+# NineChronicles Bridge
 
-## Prerequisites
+A bridge for transferring NCG between different planets (Planet A and Planet B) in Nine Chronicles.
 
-- Node.js v22.10.0+
-- yarn 4.5.1+
+## Overview
 
-## Build and Run
-```bash
-$ cp .env.sample .env
-# Then, edit `.env` file well
+This project acts as a bridge for transferring NCG tokens between different planets. The basic structure is as follows:
 
-$ yarn
-$ yarn run start
+```mermaid
+sequenceDiagram
+    participant User
+    participant UpstreamAddress as Planet A Address (Upstream)
+    participant Bridge as Bridge
+    participant Vault as Planet B Vault Address
+    participant DownstreamAddress as Planet B Address (Downstream)
+
+    User->>UpstreamAddress: NCG Transfer (+ Destination Address Info)
+    UpstreamAddress-->>Bridge: Transaction Verification
+    Bridge->>Bridge: Transaction Validation
+    Bridge->>Vault: Transfer Instruction
+    Vault->>DownstreamAddress: NCG Transfer
+    DownstreamAddress-->>User: Final Receipt Confirmation
+
+    Note over User,DownstreamAddress: The reverse direction (Planet B → Planet A) works the same way
 ```
+
+## Implementation
+
+- **Transaction Monitoring**: Real-time monitoring of transactions on each planet through Headless GraphQL client.
+- **State Storage**: Using PostgreSQL database to track the processing status and progress of each transaction.
+- **Token Transfer**: The bridge directly signs and sends NCG to the destination address specified by the user.
+
+## Getting Started
+
+For detailed information on project setup and execution, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file.

docker-compose.yml

@@ -0,0 +1,17 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:15
+    container_name: local_postgres
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: local_db
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data: 

local-test/README.md

@@ -0,0 +1,3 @@
+```
+python3 -m http.server
+```

local-test/local-planet-sample.json

@@ -0,0 +1,22 @@
+[
+    {
+        "id": "0x000000000000",
+        "name": "odin",
+        "genesisHash": "4582250d0da33b06779a8475d283d5dd210c683b9b999d74d03fac4f58fa6bce",
+        "rpcEndpoints": {
+            "headless.gql": [
+                "https://9c-main-jwt.nine-chronicles.com/graphql"
+            ]
+        }
+    },
+    {
+        "id": "0x000000000001",
+        "name": "local",
+        "genesisHash": "85ae57a288aeb4ca15623b3f1d48529b50942507e146c6eea7ef986cc51267da",
+        "rpcEndpoints": {
+            "headless.gql": [
+                "http://localhost:31280/graphql"
+            ]
+        }
+    }
+]