@leofcoin/faucet 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Peach testnet faucet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The faucet transfers existing test LFC from a dedicated wallet. It cannot mint,
+does not run a validator, and refuses any network except `leofcoin:peach`.
+Default limits: 10 LFC per claim, one claim per address and IP per 24 hours,
+and 1000 LFC per rolling day. Multiple IPs cannot exceed the global budget.
+
+Claims and limits survive restart. Reservations are persisted before broadcast.
+Unknown outcomes remain reserved for operator reconciliation and are never
+automatically resent. Confirmation comes only from the canonical transaction
+completion handle. Do not delete `claims.json` to reset limits.
+After a restart, pending claims require operator reconciliation against canonical
+chain history; they are not automatically confirmed or rebroadcast.
+Only one process may use a faucet directory. An exclusive `faucet.lock` enforces
+this; after an unclean shutdown, remove that lock only after verifying the old
+process is no longer running. Never share the directory across machines.
+
+## Run locally
+
+After the package and its updated runtime dependencies are published to npm,
+no monorepo checkout is needed:
+
+```sh
+FAUCET_DATA_DIR=/absolute/private/faucet-directory npx --yes --package @leofcoin/faucet leofcoin-faucet
+```
+
+This starts a persistent signing service, not a validator. Its data directory
+must remain private and outside the package installation directory. For a
+production service, install and pin a reviewed package version rather than
+downloading a changing version at every boot. Deployment templates are included
+in the package's `deploy` directory.
+
+Requires Node >=24.15.0. From the monorepo root:
+
+```sh
+npm ci
+npm run build
+FAUCET_DATA_DIR=/absolute/private/faucet-directory npm start -w @leofcoin/faucet
+```
+
+The service generates a new password file (mode 600) only if none exists and
+keeps its identity/state in this separate directory. Back up the complete
+directory securely. Startup prints the public faucet address and password-file
+path, not its password or private key. Fund the public address from the existing
+Peach genesis owner. Never use the genesis owner's identity as the faucet.
+
+The genesis validator remains on the owner's local node. With the existing
+genesis identity already installed there, start it using:
+
+```sh
+LEOFCOIN_PASSWORD_FILE=/absolute/path/genesis-credentials/leofcoin-peach/genesis-password.txt npm run validator
+```
+
+In its interactive shell, fund the faucet (replace ADDRESS):
+
+```text
+transfer ADDRESS 1000
+```
+
+Wait for canonical confirmation. Keep at least one eligible validator online;
+additional validators join using the existing launcher and funded accounts.
+Do not regenerate genesis to fund the faucet.
+
+## API
+
+- `GET /status`: network, readiness, public account and claim amount.
+- `POST /claims` with JSON `{ "address": "...", "requestId": "UUID" }`: 202 and a claim ID/hash.
+  Generate and retain the UUID before sending. Repeating the same request ID
+  returns its original receipt without another payment. A lost HTTP response
+  is not proof of failure: query its receipt or retry with the same UUID.
+- `GET /claims/ID`: reserved, pending, confirmed or failed. Public responses
+  never contain IP addresses or identity material.
+
+Use `npm test -w @leofcoin/faucet` for durable reservation, concurrency,
+rate/budget, restart and HTTP tests.
+
+## Remote installation
+
+Install the reviewed repository at `/opt/leofcoin-monorepo` and use a system
+Node runtime >=24.15.0. Build dependencies before starting the service. Copy
+`deploy/faucet.env.example` to `/etc/leofcoin-faucet.env` and
+`deploy/leofcoin-faucet.service` to `/etc/systemd/system/`. Set `ExecStart` to
+the actual absolute Node binary if it differs from `/usr/bin/node`.
+
+```sh
+useradd --system --user-group --home-dir /var/lib/leofcoin-faucet --shell /usr/sbin/nologin leofcoin-faucet
+systemctl daemon-reload
+systemctl enable --now leofcoin-faucet
+journalctl -u leofcoin-faucet -f
+```
+
+Add `deploy/nginx-location.conf` inside the existing HTTPS server for
+`remote.leofcoin.org`, then validate/reload Nginx. It exposes
+`https://remote.leofcoin.org/faucet` while the signing service binds only to
+loopback. `FAUCET_TRUST_PROXY=1` accepts `X-Real-IP` only from a loopback proxy;
+the supplied Nginx config overwrites that header. Do not expose port 8088.
+
+The owner funds the address printed by the remote service. Then verify
+`/faucet/status` reports Peach and `ready: true`, request a small claim from a
+test wallet, wait for confirmed status and verify the receiving node's balance.
+The scheduled public observer workflow keeps checking two additional temporary
+nodes. GitHub runners are observers, not permanent validator infrastructure.

package/deploy/faucet.env.example

@@ -0,0 +1,7 @@
+FAUCET_NETWORK=leofcoin:peach
+FAUCET_DATA_DIR=/var/lib/leofcoin-faucet
+FAUCET_PORT=8088
+FAUCET_AMOUNT=10
+FAUCET_DAILY_BUDGET=1000
+FAUCET_ORIGINS=https://leofcoin.org,https://leofcoin.github.io
+FAUCET_TRUST_PROXY=1

package/deploy/leofcoin-faucet.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=Leofcoin Peach testnet faucet
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=simple
+User=leofcoin-faucet
+Group=leofcoin-faucet
+WorkingDirectory=/opt/leofcoin-monorepo
+EnvironmentFile=/etc/leofcoin-faucet.env
+ExecStart=/usr/bin/node /opt/leofcoin-monorepo/packages/faucet/src/cli.js
+Restart=on-failure
+RestartSec=10
+TimeoutStopSec=30
+UMask=0077
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+StateDirectory=leofcoin-faucet
+StateDirectoryMode=0700
+ReadWritePaths=/var/lib/leofcoin-faucet
+
+[Install]
+WantedBy=multi-user.target

package/deploy/nginx-location.conf

@@ -0,0 +1,9 @@
+# Include inside the existing HTTPS server{} for remote.leofcoin.org.
+location /faucet/ {
+    client_max_body_size 2k;
+    proxy_pass http://127.0.0.1:8088/;
+    proxy_set_header Host $host;
+    # Overwrite rather than forward a client-controlled value.
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_read_timeout 30s;
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@leofcoin/faucet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Operator-funded faucet for the Leofcoin Peach testnet",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/leofcoin/monorepo.git",
+    "directory": "packages/faucet"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "leofcoin-faucet": "./src/cli.js"
+  },
+  "files": [
+    "src/cli.js",
+    "src/server.js",
+    "src/service.js",
+    "deploy",
+    "README.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@leofcoin/binary": "^1.1.0",
+    "@leofcoin/launch-chain": "^0.5.0",
+    "@leofcoin/lib": "^1.4.0",
+    "@leofcoin/multi-wallet": "^3.1.9",
+    "@leofcoin/utils": "^1.1.45",
+    "@vandeurenglenn/wrtc": "^0.7.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { unlinkSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { resolve, join, relative } from 'node:path'
+import { homedir } from 'node:os'
+import MultiWallet from '@leofcoin/multi-wallet'
+import { parseUnits } from '@leofcoin/utils'
+import { signTransaction, calculateFee } from '@leofcoin/lib'
+import { startNode } from '@leofcoin/launch-chain/node'
+import { Faucet, FaucetError } from './service.js'
+import { faucetServer } from './server.js'
+
+const network = process.env.FAUCET_NETWORK || 'leofcoin:peach'
+if (network !== 'leofcoin:peach') throw new Error('The faucet is restricted to the Peach testnet.')
+const directory = resolve(process.env.FAUCET_DATA_DIR || join(homedir(), '.leofcoin', 'peach-faucet'))
+await mkdir(directory, { recursive: true, mode: 0o700 })
+const lockPath = join(directory, 'faucet.lock')
+try {
+  await writeFile(lockPath, JSON.stringify({ pid: process.pid }), { mode: 0o600, flag: 'wx' })
+} catch (error) {
+  if (error.code === 'EEXIST')
+    throw new Error(
+      `Faucet directory is locked: ${lockPath}. Stop the existing process before starting another. After an unclean shutdown, verify no faucet process is running before removing this lock.`
+    )
+  throw error
+}
+process.once('exit', () => {
+  try {
+    unlinkSync(lockPath)
+  } catch {}
+})
+const passwordPath = join(directory, 'password.txt')
+try {
+  await writeFile(passwordPath, randomBytes(32).toString('base64url'), { mode: 0o600, flag: 'wx' })
+} catch (error) {
+  if (error.code !== 'EEXIST') throw error
+}
+const password = (await readFile(passwordPath, 'utf8')).trim()
+if (!password) throw new Error('Faucet password file is empty')
+globalThis.wrtc = await import('@vandeurenglenn/wrtc')
+const node = await startNode({
+  network,
+  networkVersion: 'peach',
+  root: relative(homedir(), join(directory, 'node')),
+  password,
+  httpPort: false,
+  wsPort: false
+})
+const accountPath = join(directory, 'account.json')
+try {
+  const previous = JSON.parse(await readFile(accountPath, 'utf8'))
+  if (previous.address !== node.account)
+    throw new Error('Faucet identity changed. Refusing startup; restore the original identity.')
+} catch (error) {
+  if (error.code !== 'ENOENT') throw error
+  await writeFile(accountPath, JSON.stringify({ network, address: node.account }), { mode: 0o600, flag: 'wx' })
+}
+const backupPath = join(directory, 'identity.backup')
+try {
+  await writeFile(backupPath, await globalThis.peernet.identity.export(password), { mode: 0o600, flag: 'wx' })
+} catch (error) {
+  if (error.code !== 'EEXIST') throw error
+}
+const amount = parseUnits(process.env.FAUCET_AMOUNT || '10')
+const dailyBudget = parseUnits(process.env.FAUCET_DAILY_BUDGET || '1000')
+const faucet = await new Faucet({
+  ledger: join(directory, 'claims.json'),
+  amount,
+  dailyBudget,
+  adapter: {
+    validateAddress: async (address) => {
+      try {
+        await new MultiWallet(network).fromAddress(address, null, network)
+      } catch {
+        throw new FaucetError(400, 'Invalid Peach recipient address')
+      }
+      if (address === node.account) throw new FaucetError(400, 'Cannot claim to the faucet account')
+    },
+    health: async () => {
+      const balance = BigInt((await node.chain.balanceOf(node.account)) || 0n)
+      const connected = Object.values(globalThis.peernet.connections || {}).some((peer) => peer.connected)
+      return {
+        account: node.account,
+        balance,
+        ready: connected && node.chain.state.sync === 'synced' && balance > amount
+      }
+    },
+    quote: async (to, amount) => {
+      const raw = await node.chain.createTransaction({
+        from: node.account,
+        to: node.chain.nativeToken,
+        method: 'transfer',
+        params: [to, amount.toString()]
+      })
+      const signed = await signTransaction(raw, globalThis.peernet.identity)
+      const fee = BigInt(await calculateFee(signed))
+      if (BigInt((await node.chain.balanceOf(node.account)) || 0n) < amount + fee)
+        throw new Error('Faucet balance cannot cover amount and fee')
+      return { signed, fee }
+    },
+    submit: async (_to, _amount, quote) => node.chain.sendTransaction(quote.signed),
+    reportError: (error) => console.error('Faucet claim needs operator attention:', error.message)
+  }
+}).init()
+const origins = (process.env.FAUCET_ORIGINS || 'https://leofcoin.org,https://leofcoin.github.io')
+  .split(',')
+  .map((value) => value.trim())
+  .filter(Boolean)
+const port = Number(process.env.FAUCET_PORT || 8088)
+if (!Number.isSafeInteger(port) || port < 1 || port > 65535) throw new Error('Invalid faucet port')
+const server = faucetServer(faucet, { origins, trustProxy: process.env.FAUCET_TRUST_PROXY === '1' })
+server.listen(port, '127.0.0.1', () => {
+  console.log(`Peach faucet account: ${node.account}`)
+  console.log(
+    `Password file: ${passwordPath}; encrypted identity backup: ${backupPath}. Back up the complete ${directory} directory securely.`
+  )
+  console.log(`Faucet listening on 127.0.0.1:${port}; fund this account from the testnet owner before enabling claims.`)
+})
+for (const signal of ['SIGTERM', 'SIGINT'])
+  process.once(signal, async () => {
+    server.close()
+    await faucet.flush()
+    node.stop()
+    process.exit(0)
+  })

package/src/server.js

@@ -0,0 +1,84 @@
+import { encodeWire, decodeWire, BINARY_CONTENT_TYPE } from '@leofcoin/binary'
+import { createServer } from 'node:http'
+import { isIP } from 'node:net'
+import { FaucetError } from './service.js'
+
+export function faucetServer(faucet, { origins = [], trustProxy = false } = {}) {
+  const allowed = new Set(origins)
+  const clients = new Map()
+  return createServer(async (request, response) => {
+    const send = (status, value) => {
+      response.writeHead(status, { 'Content-Type': BINARY_CONTENT_TYPE, 'Cache-Control': 'no-store' })
+      response.end(encodeWire('rpc', value))
+    }
+    try {
+      const origin = request.headers.origin
+      if (origin && !allowed.has(origin)) throw new FaucetError(403, 'Origin is not allowed')
+      if (origin) {
+        response.setHeader('Access-Control-Allow-Origin', origin)
+        response.setHeader('Vary', 'Origin')
+      }
+      response.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+      response.setHeader('Access-Control-Allow-Headers', 'Content-Type')
+      const socketIp = request.socket.remoteAddress
+      const forwarded =
+        trustProxy && ['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(socketIp)
+          ? request.headers['x-real-ip']
+          : undefined
+      const ip = typeof forwarded === 'string' && isIP(forwarded) ? forwarded : socketIp.replace(/^::ffff:/, '')
+      const now = Date.now()
+      for (const [key, value] of clients) if (value.until < now) clients.delete(key)
+      const rate = clients.get(ip) || { count: 0, until: now + 60000 }
+      if (++rate.count > 60 || clients.size > 10000) throw new FaucetError(429, 'Too many requests', 60)
+      clients.set(ip, rate)
+      if (request.method === 'OPTIONS') {
+        response.writeHead(204)
+        response.end()
+        return
+      }
+      const path = new URL(request.url, 'http://faucet').pathname
+      if (request.method === 'GET' && path === '/status') {
+        const status = await faucet.status()
+        send(200, status)
+        return
+      }
+      if (request.method === 'GET' && /^\/claims\/[a-f0-9-]{36}$/.test(path)) {
+        send(200, faucet.get(path.slice(8)))
+        return
+      }
+      if (request.method !== 'POST' || path !== '/claims') throw new FaucetError(404, 'Not found')
+      if (request.headers['content-type']?.split(';')[0] !== BINARY_CONTENT_TYPE)
+        throw new FaucetError(415, 'Use application/octet-stream')
+      const chunks = []
+      let size = 0
+      for await (const chunk of request) {
+        size += chunk.length
+        if (size > 2048) throw new FaucetError(413, 'Request too large')
+        chunks.push(chunk)
+      }
+      let value
+      try {
+        value = decodeWire('rpc', Buffer.concat(chunks), { maxBytes: 2048 })
+      } catch {
+        throw new FaucetError(400, 'Invalid binary request')
+      }
+      if (!value || typeof value.address !== 'string' || value.address.length > 100)
+        throw new FaucetError(400, 'Recipient address required')
+      if (
+        value.requestId !== undefined &&
+        (typeof value.requestId !== 'string' ||
+          !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(value.requestId))
+      )
+        throw new FaucetError(400, 'Invalid request ID')
+      const claim = await faucet.claim(value.address.trim(), ip, value.requestId)
+      send(202, claim)
+    } catch (error) {
+      if (error.retryAfter) response.setHeader('Retry-After', String(error.retryAfter))
+      send(error.status || 500, {
+        error: error.status ? error.message : 'Faucet request failed',
+        accepted: Boolean(error.claimId),
+        ...(error.claimId ? { claimId: error.claimId } : {})
+      })
+    }
+  })
+}

package/src/service.js

@@ -0,0 +1,186 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, open, rename } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { formatUnits } from '@leofcoin/utils'
+
+export class FaucetError extends Error {
+  constructor(status, message, retryAfter = 0) {
+    super(message)
+    this.status = status
+    this.retryAfter = retryAfter
+  }
+}
+
+export class Faucet {
+  #records = []
+  #queue = Promise.resolve()
+  constructor({ ledger, amount, dailyBudget, cooldownMs = 86400000, adapter, now = Date.now }) {
+    if (amount <= 0n || dailyBudget < amount || !Number.isSafeInteger(cooldownMs) || cooldownMs < 60000)
+      throw new Error('Invalid faucet limits')
+    Object.assign(this, { ledger, amount, dailyBudget, cooldownMs, adapter, now })
+  }
+  async init() {
+    await mkdir(dirname(this.ledger), { recursive: true, mode: 0o700 })
+    try {
+      const data = JSON.parse(await readFile(this.ledger, 'utf8'))
+      if (
+        data.version !== 1 ||
+        !Array.isArray(data.claims) ||
+        data.claims.some(
+          (claim) =>
+            typeof claim.id !== 'string' ||
+            typeof claim.address !== 'string' ||
+            typeof claim.ip !== 'string' ||
+            !Number.isSafeInteger(claim.createdAt) ||
+            !['reserved', 'pending', 'confirmed', 'failed'].includes(claim.state) ||
+            !/^\d+$/.test(claim.amount) ||
+            BigInt(claim.amount) <= 0n ||
+            (claim.fee !== undefined && !/^\d+$/.test(claim.fee))
+        )
+      )
+        throw new Error('Invalid faucet ledger')
+      this.#records = data.claims
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    }
+    return this
+  }
+  async #persist() {
+    const temporary = `${this.ledger}.tmp`
+    const file = await open(temporary, 'w', 0o600)
+    try {
+      await file.writeFile(JSON.stringify({ version: 1, claims: this.#records }))
+      await file.sync()
+    } finally {
+      await file.close()
+    }
+    await rename(temporary, this.ledger)
+    const directory = await open(dirname(this.ledger), 'r')
+    try {
+      await directory.sync()
+    } finally {
+      await directory.close()
+    }
+  }
+  #serialized(task) {
+    const next = this.#queue.then(task)
+    this.#queue = next.catch(() => {})
+    return next
+  }
+  async flush() {
+    await this.#queue
+  }
+  publicClaim(claim) {
+    if (!claim) throw new FaucetError(404, 'Claim not found')
+    return {
+      id: claim.id,
+      address: claim.address,
+      amount: formatUnits(BigInt(claim.amount)),
+      state: claim.state,
+      hash: claim.hash || null,
+      createdAt: claim.createdAt,
+      nextClaimAt: claim.createdAt + this.cooldownMs
+    }
+  }
+  get(id) {
+    return this.publicClaim(this.#records.find((record) => record.id === id))
+  }
+  async status() {
+    const health = await this.adapter.health()
+    return {
+      network: 'leofcoin:peach',
+      testnet: true,
+      amount: formatUnits(this.amount),
+      cooldownMs: this.cooldownMs,
+      ready: health.ready,
+      account: health.account,
+      balance: formatUnits(BigInt(health.balance || 0n))
+    }
+  }
+  claim(address, ip, requestId) {
+    return this.#serialized(async () => {
+      await this.adapter.validateAddress(address)
+      if (requestId) {
+        const existing = this.#records.find((record) => record.id === requestId)
+        if (existing) {
+          if (existing.address !== address) throw new FaucetError(409, 'Claim ID belongs to a different recipient')
+          return this.publicClaim(existing)
+        }
+      }
+      const health = await this.adapter.health()
+      if (!health.ready)
+        throw new FaucetError(503, 'Testnet faucet is not ready. It needs a synced node, peers and funds.')
+      const now = this.now()
+      const previous = this.#records
+        .filter((record) => record.address === address || record.ip === ip)
+        .sort((a, b) => b.createdAt - a.createdAt)[0]
+      if (previous && now < previous.createdAt + this.cooldownMs)
+        throw new FaucetError(
+          429,
+          'You can request test LFC once per day per address and IP.',
+          Math.ceil((previous.createdAt + this.cooldownMs - now) / 1000)
+        )
+      const spent = this.#records
+        .filter((record) => record.createdAt > now - 86400000 && record.state !== 'failed')
+        .reduce((total, record) => total + BigInt(record.amount), 0n)
+      if (spent + this.amount > this.dailyBudget)
+        throw new FaucetError(429, 'The daily faucet budget has been reached.', 3600)
+      const quote = await this.adapter.quote?.(address, this.amount)
+      const fee = BigInt(quote?.fee || 0n)
+      const outstanding = this.#records
+        .filter((record) => record.state === 'reserved' || record.state === 'pending')
+        .reduce((total, record) => total + BigInt(record.amount) + BigInt(record.fee || 0n), 0n)
+      if (BigInt(health.balance || 0n) < outstanding + this.amount + fee)
+        throw new FaucetError(503, 'Faucet funds are reserved for pending claims. Wait for confirmation.')
+      const record = {
+        id: requestId || randomUUID(),
+        address,
+        ip,
+        amount: this.amount.toString(),
+        fee: fee.toString(),
+        createdAt: now,
+        state: 'reserved'
+      }
+      this.#records.push(record)
+      // A reservation is durable BEFORE broadcasting. A crash or timeout cannot
+      // erase its rate/budget charge or cause an automatic duplicate payment.
+      await this.#persist()
+      try {
+        const pending = await this.adapter.submit(address, this.amount, quote)
+        if (!pending?.hash || !pending.wait || typeof pending.wait.then !== 'function')
+          throw new Error('Missing canonical completion handle')
+        // A completion may reject while disk IO is still pending. Observe it
+        // immediately; persistence failure still requires manual reconciliation.
+        Promise.resolve(pending.wait).catch(() => {})
+        record.hash = pending.hash
+        record.state = 'pending'
+        await this.#persist()
+        Promise.resolve(pending.wait)
+          .then(
+            () =>
+              this.#serialized(async () => {
+                record.state = 'confirmed'
+                await this.#persist()
+              }),
+            () =>
+              this.#serialized(async () => {
+                record.state = 'failed'
+                await this.#persist()
+              })
+          )
+          .catch((error) => this.adapter.reportError?.(error))
+      } catch (error) {
+        // The node may already have broadcast before an IO error. Keep the
+        // reservation for manual reconciliation, never refund and auto-resend.
+        this.adapter.reportError?.(error)
+        const failure = new FaucetError(
+          503,
+          'Claim reserved but submission could not be verified. Do not retry; contact the testnet operator.'
+        )
+        failure.claimId = record.id
+        throw failure
+      }
+      return this.publicClaim(record)
+    })
+  }
+}