Setup

Local development setup guide for the Pactum platform.

Prerequisites

1. Clone and Install

git clone https://github.com/rizkygm23/pactum.git
cd pactum
npm install

2. Configure Environment

Create a .env.local file in the project root:

cp .env.example .env.local

Fill in the following variables:

[!NOTE] For full production deployment, the backend requires additional operator credentials. Refer to internal engineering guidelines for production deployment secrets.

[!CAUTION] Never commit .env.local to version control. The .gitignore already excludes it.

3. Set Up the Database

Run the SQL migration files in order in the Database SQL Editor (Dashboard → SQL Editor):

1. database/migrations/001_initial_schema.sql — Core tables and initial RLS
2. database/migrations/002_custom_auth.sql — Custom auth migration (decouples from Database Auth)
3. database/migrations/003_state_channel.sql — Adds status and address columns for state channel billing
4. database/migrations/004_enable_rls.sql — Re-enables RLS on all tables

[!IMPORTANT] Migrations must be executed in numerical order. Each migration depends on the previous one.

4. Deploy the Smart Contract (Optional)

If you need to deploy a fresh instance of the PactumBilling contract:

1. Configure hardhat.config.cjs with your Arc Testnet RPC and deployer private key.
2. Compile the contract:

   node compile.js
   

3. Deploy using Hardhat or your preferred deployment tool.
4. Update PACTUM_CONTRACT_ADDRESS and NEXT_PUBLIC_PACTUM_CONTRACT_ADDRESS in .env.local with the deployed address.

If a contract is already deployed on Arc Testnet, use the existing address.

5. Run the Development Server

npm run dev

The application starts at http://localhost:3000.

6. Verify the Setup

1. Signup: Navigate to /signup and create an account.
2. Dashboard: After login, you should see the dashboard at /dashboard.
3. API Key: Go to Settings and generate an API key.
4. Test Usage Tracking: Send a test request:

   curl -X POST http://localhost:3000/api/v1/usage/track \
     -H "Content-Type: application/json" \
     -H "X-API-Key: YOUR_API_KEY" \
     -d '{
       "model": "test-model",
       "prompt_tokens": 100,
       "completion_tokens": 50,
       "prompt_price_per_token": 0.000005,
       "completion_price_per_token": 0.000015,
       "user_address": "0xYOUR_TEST_ADDRESS",
       "idempotency_key": "test-001"
     }'
   

5. Dashboard Update: The usage event should appear in the dashboard immediately.

Common Issues