Claude Review PR - Pay with AI3 feature review - Not intended to be merged

.github/workflows/claude-review.yml

@@ -0,0 +1,28 @@
+name: Claude Code Review
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  claude-review:
+    runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude'))
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 1
+      - uses: anthropics/claude-code-action@df37d2f0760a4b5683a6e617c9325bc1a36443f6 # v1.0.75
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

CLAUDE.md

@@ -27,8 +27,11 @@ Yarn 4.2.2 monorepo with workspaces in `apps/`, `packages/`, and `submodules/`.
 # Install dependencies
 yarn install
 
-# Initialize git submodules (required first time)
+# Initialize git submodules (required first time, and in each new worktree)
 make init-submodules
+# ⚠️ Worktrees do NOT inherit initialized submodules from the main repo.
+# If `yarn install` fails with "Workspace not found (@auto-files/rpc-apis)",
+# run `git submodule update --init --recursive` or `make init-submodules`.
 
 # Build everything (submodules + models + ui + s3 + frontend + backend)
 make all

apps/backend/.env.sample

@@ -4,5 +4,60 @@ FILES_GATEWAY_URL=http://changeme.com # change to your own (or it'll fail when f
 FILES_GATEWAY_TOKEN=changeme # change to your own (or it'll fail when fetching archived files)
 AUTH_SERVICE_API_KEY=1234567890 # change to your own if updated in auth
 RABBITMQ_URL=amqp://guest:guest@localhost:5672
-EVM_CHAIN_ENDPOINT=http://localhost:8545 # update it you want to simulate/test buy credits feature
-EVM_CHAIN_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000 # update it you want to simulate/test buy credits feature
+
+# ---------------------------------------------------------------------------
+# Pay-with-AI3 / purchased credits feature
+# ---------------------------------------------------------------------------
+
+# Feature flags — set BUY_CREDITS_ACTIVE=true to enable the purchase flow.
+# BUY_CREDITS_STAFF_ONLY=true restricts it to admin/staff accounts only,
+# useful for a staged rollout before opening to all users.
+BUY_CREDITS_ACTIVE=false
+BUY_CREDITS_STAFF_ONLY=false
+
+# EVM endpoint for the AutoDriveCreditsReceiver contract.
+# Point this at the Auto-EVM RPC for the target network (mainnet or Taurus
+# testnet).  The payment manager watches this chain for deposit events.
+EVM_CHAIN_ENDPOINT=http://localhost:8545
+
+# Address of the deployed AutoDriveCreditsReceiver contract.
+# Must match the chain pointed to by EVM_CHAIN_ENDPOINT.
+EVM_CHAIN_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000
+
+# Number of block confirmations to wait before treating a payment as final.
+# Higher values reduce the risk of processing a payment that is later
+# reversed by a chain reorganisation. Default: 6.
+EVM_CHAIN_CONFIRMATIONS=6
+
+# How often (in milliseconds) the payment manager polls for CONFIRMED intents
+# that have not yet had credits applied. This is a fallback for cases where
+# the event watcher misses a log. Default: 30000 (30 seconds).
+EVM_CHAIN_CHECK_INTERVAL=30000
+
+# Price multiplier applied on top of the raw Autonomys consensus fee to
+# determine the AI3 cost per byte. A value of 5.0 means users pay 5× the
+# current on-chain transaction byte fee. Default: 5.00.
+CREDITS_PRICE_MULTIPLIER=5.00
+
+# ---------------------------------------------------------------------------
+# Credit lifecycle
+# ---------------------------------------------------------------------------
+
+# Number of days after purchase before a credit batch expires.
+# Users see this value on the purchase confirmation screen and in their credit
+# history. Default: 90.
+CREDIT_EXPIRY_DAYS=90
+
+# Maximum total purchased upload bytes allowed per user across all active
+# (non-expired) credit rows. Attempts to purchase beyond this cap result in
+# an OVER_CAP intent requiring admin review. Default: 107374182400 (100 GiB).
+MAX_CREDITS_PER_USER=107374182400
+
+# How often (in milliseconds) the background job runs to mark expired credit
+# rows and clean up stale PENDING intents. Default: 3600000 (1 hour).
+CREDIT_EXPIRY_CHECK_INTERVAL=3600000
+
+# How many minutes a PENDING intent remains valid before it is treated as
+# expired. Users must submit their on-chain transaction within this window
+# after creating an intent. Default: 10.
+INTENT_EXPIRY_MINUTES=10

apps/backend/__tests__/e2e/users/credits.spec.ts

@@ -1,6 +1,8 @@
 import {
   InteractionType,
+  InteractionSource,
   AccountModel,
+  IntentStatus,
   UserWithOrganization,
 } from '@auto-drive/models'
 import { PreconditionError } from '../../utils/error.js'
@@ -14,7 +16,22 @@ import { dbMigration } from '../../utils/dbMigrate.js'
 import { AccountsUseCases } from '../../../src/core/users/accounts.js'
 import { AuthManager } from '../../../src/infrastructure/services/auth/index.js'
 import { accountsRepository } from '../../../src/infrastructure/repositories/index.js'
+import { purchasedCreditsRepository } from '../../../src/infrastructure/repositories/users/purchasedCredits.js'
+import { interactionsRepository } from '../../../src/infrastructure/repositories/objects/interactions.js'
 import { jest } from '@jest/globals'
+import { v4 as uuidv4 } from 'uuid'
+
+// Inserts a minimal intent row so the purchased_credits.intent_id FK is satisfied.
+const createTestIntent = async (userPublicId: string): Promise<string> => {
+  const db = await getDatabase()
+  const id = `test-intent-${uuidv4()}`
+  await db.query(
+    `INSERT INTO intents (id, user_public_id, status, shannons_per_byte, expires_at)
+     VALUES ($1, $2, $3, $4, $5)`,
+    [id, userPublicId, IntentStatus.COMPLETED, '1', new Date()],
+  )
+  return id
+}
 
 describe('CreditsUseCases', () => {
   let mockUser: UserWithOrganization
@@ -33,7 +50,7 @@ describe('CreditsUseCases', () => {
     await dbMigration.down()
   })
 
-  it('should create credits for a user', async () => {
+  it('should consume free-tier credits on upload interaction', async () => {
     const interactionType = InteractionType.Upload
     const size = BigInt(1024)
 
@@ -54,7 +71,7 @@ describe('CreditsUseCases', () => {
     expect(initialCredits - pendingCredits).toEqual(Number(size))
   })
 
-  it('should create credits for a user on download', async () => {
+  it('should consume free-tier credits on download interaction', async () => {
     const interactionType = InteractionType.Download
     const size = BigInt(2048)
 
@@ -75,50 +92,198 @@ describe('CreditsUseCases', () => {
     expect(initialCredits - pendingCredits).toBe(Number(size).valueOf())
   })
 
-  it('should add credits to a OneOff subscription', async () => {
+  it('should create a purchased_credits row when credits are added', async () => {
     jest.spyOn(AuthManager, 'getUserFromPublicId').mockResolvedValue(mockUser)
-    const subscription = await AccountsUseCases.getOrCreateAccount(mockUser)
-    // Ensure subscription is OneOff
-    await accountsRepository.updateAccount(
-      subscription.id,
-      AccountModel.OneOff,
-      subscription.uploadLimit,
-      subscription.downloadLimit,
-    )
+    const account = await AccountsUseCases.getOrCreateAccount(mockUser)
 
-    const before = await AccountsUseCases.getAccountById(subscription.id)
-    if (!before) throw new Error('Subscription not found')
+    const creditsToAdd = BigInt(123)
+    const intentId = await createTestIntent(mockUser.publicId)
 
-    const creditsToAdd = 123
     const result = await AccountsUseCases.addCreditsToAccount(
       mockUser.publicId,
       creditsToAdd,
+      intentId,
     )
 
     expect(result.isOk()).toBe(true)
 
-    const after = await AccountsUseCases.getAccountById(subscription.id)
-    if (!after) throw new Error('Subscription not found')
+    // A purchased_credits row should now exist for this account.
+    const rows = await purchasedCreditsRepository.getByAccountId(account.id)
+    expect(rows).toHaveLength(1)
+    expect(rows[0].uploadBytesOriginal).toBe(creditsToAdd)
+    expect(rows[0].uploadBytesRemaining).toBe(creditsToAdd)
+    expect(rows[0].intentId).toBe(intentId)
+
+    // The free/one-off account limits must remain untouched.
+    const after = await AccountsUseCases.getAccountById(account.id)
+    if (!after) throw new Error('Account not found')
+    expect(after.uploadLimit).toBe(account.uploadLimit)
+    expect(after.downloadLimit).toBe(account.downloadLimit)
+  })
+
+  it('purchased credits should count toward the total available credits', async () => {
+    jest.spyOn(AuthManager, 'getUserFromPublicId').mockResolvedValue(mockUser)
+    const account = await AccountsUseCases.getOrCreateAccount(mockUser)
+
+    const creditsToAdd = BigInt(100 * 1024)
+    const intentId = await createTestIntent(mockUser.publicId)
+
+    const before = await AccountsUseCases.getPendingCreditsByUserAndType(
+      mockUser,
+      InteractionType.Upload,
+    )
+
+    await AccountsUseCases.addCreditsToAccount(
+      mockUser.publicId,
+      creditsToAdd,
+      intentId,
+    )
+
+    const after = await AccountsUseCases.getPendingCreditsByUserAndType(
+      mockUser,
+      InteractionType.Upload,
+    )
 
-    expect(after.uploadLimit - before.uploadLimit).toBe(creditsToAdd)
-    expect(after.model).toBe(AccountModel.OneOff)
+    // The total pending credits must have grown by exactly the purchased amount.
+    expect(after - before).toBe(Number(creditsToAdd))
+
+    // And the free-tier account limits remain unchanged.
+    const acct = await AccountsUseCases.getAccountById(account.id)
+    if (!acct) throw new Error('Account not found')
+    expect(acct.uploadLimit).toBe(account.uploadLimit)
   })
 
-  it('should fail to add credits if subscription is not OneOff', async () => {
+  it('should add credits to accounts of any model (not restricted to OneOff)', async () => {
     jest.spyOn(AuthManager, 'getUserFromPublicId').mockResolvedValue(mockUser)
-    const subscription = await AccountsUseCases.getOrCreateAccount(mockUser)
+    const account = await AccountsUseCases.getOrCreateAccount(mockUser)
+
+    // Switch to Monthly model — purchased credits should still work.
     await accountsRepository.updateAccount(
-      subscription.id,
+      account.id,
       AccountModel.Monthly,
-      subscription.uploadLimit,
-      subscription.downloadLimit,
+      account.uploadLimit,
+      account.downloadLimit,
     )
 
+    const intentId = await createTestIntent(mockUser.publicId)
     const result = await AccountsUseCases.addCreditsToAccount(
       mockUser.publicId,
-      10,
+      BigInt(50),
+      intentId,
+    )
+
+    expect(result.isOk()).toBe(true)
+
+    const rows = await purchasedCreditsRepository.getByAccountId(account.id)
+    expect(rows).toHaveLength(1)
+    expect(rows[0].uploadBytesOriginal).toBe(BigInt(50))
+  })
+
+  it('should reject a purchase that would exceed the per-user cap', async () => {
+    jest.spyOn(AuthManager, 'getUserFromPublicId').mockResolvedValue(mockUser)
+
+    // Manually insert a row that consumes most of the cap (100 GiB).
+    // We mock getRemainingCredits to simulate a near-full account rather than
+    // inserting 100 GiB worth of real rows.
+    const account = await AccountsUseCases.getOrCreateAccount(mockUser)
+
+    // Insert a large existing credit row directly so the cap check fires.
+    const largeBytes = BigInt(100 * 1024 * 1024 * 1024) // 100 GiB
+    const existingIntentId = await createTestIntent(mockUser.publicId)
+    await purchasedCreditsRepository.createPurchasedCredit({
+      accountId: account.id,
+      intentId: existingIntentId,
+      uploadBytesOriginal: largeBytes,
+      downloadBytesOriginal: largeBytes,
+      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000),
+    })
+
+    // Trying to add even 1 more byte should be rejected.
+    const overCapIntentId = await createTestIntent(mockUser.publicId)
+    const result = await AccountsUseCases.addCreditsToAccount(
+      mockUser.publicId,
+      BigInt(1),
+      overCapIntentId,
     )
 
     expect(result.isErr()).toBe(true)
   })
+
+  it('should prevent double-spend when two concurrent 90 MB uploads race against 100 MB of purchased credits', async () => {
+    jest.spyOn(AuthManager, 'getUserFromPublicId').mockResolvedValue(mockUser)
+    const account = await AccountsUseCases.getOrCreateAccount(mockUser)
+
+    const MB = (n: number) => BigInt(n * 1024 * 1024)
+
+    // Seed exactly 100 MB of purchased credits and zero out the free-tier
+    // allocation so the only available budget is the purchased pool.
+    const intentId = await createTestIntent(mockUser.publicId)
+    await purchasedCreditsRepository.createPurchasedCredit({
+      accountId: account.id,
+      intentId,
+      uploadBytesOriginal: MB(100),
+      downloadBytesOriginal: MB(100),
+      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000),
+    })
+    await accountsRepository.updateAccount(
+      account.id,
+      AccountModel.OneOff,
+      0, // uploadLimit = 0 (no free-tier bytes)
+      0, // downloadLimit = 0
+    )
+
+    // Fire two concurrent 90 MB upload interactions simultaneously.
+    // consumeUpTo serialises access via FOR UPDATE: one caller gets 90 MB,
+    // the other only gets 10 MB from purchased credits.  The free-tier guard
+    // then detects that the remaining 80 MB cannot be covered by free-tier
+    // (uploadLimit = 0), refunds the 10 MB back, and throws.
+    const [result1, result2] = await Promise.allSettled([
+      AccountsUseCases.registerInteraction(
+        mockUser,
+        InteractionType.Upload,
+        MB(90),
+      ),
+      AccountsUseCases.registerInteraction(
+        mockUser,
+        InteractionType.Upload,
+        MB(90),
+      ),
+    ])
+
+    // Exactly one upload succeeds and exactly one is rejected.
+    const statuses = [result1.status, result2.status].sort()
+    expect(statuses).toEqual(['fulfilled', 'rejected'])
+
+    // The rejected upload must have thrown PaymentRequiredError and refunded
+    // the partial purchased-credit deduction.  10 MB (= 100 - 90) must remain.
+    const remaining =
+      await purchasedCreditsRepository.getRemainingCredits(account.id)
+    expect(remaining.uploadBytesRemaining).toBe(MB(10))
+
+    // Only 90 MB should be recorded as consumed from purchased credits —
+    // the second caller's partial deduction was rolled back via refundCredits.
+    const now = new Date()
+    const purchasedInteractions =
+      await interactionsRepository.getInteractionsByAccountIdAndTypeInTimeRange(
+        account.id,
+        InteractionType.Upload,
+        new Date(0),
+        now,
+        InteractionSource.Purchased,
+      )
+    const totalPurchasedConsumed = purchasedInteractions.reduce(
+      (sum, i) => sum + i.size,
+      0,
+    )
+    expect(totalPurchasedConsumed).toBe(Number(MB(90)))
+
+    // After the race, only 10 MB of purchased credits remain and 0 free-tier
+    // bytes are available — a new 90 MB upload must be denied at the gate.
+    const pendingAfter =
+      await AccountsUseCases.getPendingCreditsByUserAndType(
+        mockUser,
+        InteractionType.Upload,
+      )
+    expect(pendingAfter).toBe(Number(MB(10)))
+  })
 })