feat(orchestrator): add staking orchestrator POC

.eslintrc.js

@@ -0,0 +1,13 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  env: {
+    node: true,
+    jest: true
+  }
+};

.github/workflows/poc-staking-orchestrator-v1.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+    branches: [poc/staking-orchestrator-v1]
+  pull_request:
+    branches: [poc/staking-orchestrator-v1]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test

README.md

@@ -1,4 +1,5 @@
 # Goblin Services — API • Indexer • Timekeeper
+[![CI](https://github.com/goblin-sh/goblin-services/actions/workflows/poc-staking-orchestrator-v1.yml/badge.svg?branch=poc/staking-orchestrator-v1)](https://github.com/goblin-sh/goblin-services/actions/workflows/poc-staking-orchestrator-v1.yml)
 Off-chain smarts that connect the wallet and bots to on-chain programs.
 
 Day-1: minimal pilot (DEV only) to exercise basic flows.
@@ -7,8 +8,24 @@ Day-1: minimal pilot (DEV only) to exercise basic flows.
 - **Indexer**: reads chain → local state
 - **Timekeeper**: schedules payouts/dividend policies
 
-**Bucket:** Off-Chain Smarts (platform-agnostic)  
+**Bucket:** Off-Chain Smarts (platform-agnostic)
 **Status:** PILOT (DEV)
 
-- Overview → /docs/OVERVIEW.md  
+- Overview → /docs/OVERVIEW.md
 - Runbook → /ops/RUNBOOK.md
+
+## Staking Orchestrator POC
+
+This proof-of-concept adds a minimal staking orchestrator.
+
+### Run
+
+```
+npm install
+npm run build
+node dist/orchestrator-svc/index.js
+```
+
+### Env Vars
+
+See [.env.example](.env.example). `DRY_RUN=true` will log driver calls without executing them.

config/strategy.json

@@ -0,0 +1,7 @@
+{
+  "mode": "mSOL",
+  "skimPeriodDays": 2.5,
+  "preferInstantUnstake": true,
+  "minProfitLamports": 10000,
+  "maxUnstakeFeeBps": 50
+}

docs/CONFIG.md

@@ -0,0 +1,9 @@
+# Configuration
+
+`config/strategy.json` controls the orchestrator behaviour.
+
+- `mode`: staking mode identifier.
+- `skimPeriodDays`: number of days between skims.
+- `preferInstantUnstake`: try instant unstake before delayed.
+- `minProfitLamports`: minimum profit before payout.
+- `maxUnstakeFeeBps`: maximum fee tolerated for instant unstake.

docs/POC_LIMITATIONS.md

@@ -0,0 +1,6 @@
+# POC Limitations
+
+- Staking driver is fully mocked and does not touch the blockchain.
+- Timers use `setTimeout` instead of Cloud Tasks.
+- State is kept in memory; restarting the process loses progress.
+- No authentication or security is implemented.

docs/STATE_MACHINE.md

@@ -0,0 +1,8 @@
+# State Machine
+
+```
+AWAITING_DEPOSIT -> STAKED -> SKIM_SCHEDULED -> UNSTAKING -> CLAIMABLE -> SETTLED -> PAY_PROFIT -> RESTAKE
+```
+
+Each transition only occurs on the events defined in [TOPICS.md](TOPICS.md).
+Replaying an event that has already been applied leaves the state unchanged.

docs/TOPICS.md

@@ -0,0 +1,16 @@
+# POC Pub/Sub Topics
+
+All topics are prefixed with `poc.` for the proof-of-concept.
+Each message carries an `idempotencyKey` to allow safe retries.
+
+| Topic | Payload | Idempotency Key |
+|-------|---------|-----------------|
+| `poc.stake.ordered` | `{ positionId, amount }` | `positionId:cycle:stake` |
+| `poc.deposit.confirmed` | `{ positionId, user, amount }` | `positionId:cycle:deposit` |
+| `poc.stake.done` | `{ positionId }` | `positionId:cycle:stake` |
+| `poc.skim.due` | `{ positionId }` | `positionId:cycle:skim` |
+| `poc.unstake.requested` | `{ positionId }` | `positionId:cycle:unstake` |
+| `poc.unstake.claimable` | `{ positionId, out }` | `positionId:cycle:claim` |
+| `poc.profit.paid` | `{ positionId, profit }` | `positionId:cycle:payout` |
+| `poc.restake.done` | `{ positionId }` | `positionId:cycle:restake` |
+| `poc.error` | `{ positionId, step, message }` | N/A |

jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts']
+};