refactor(token-interface): migrate tests from vitest to cucumber-js

.github/workflows/js-token-interface-v2.yml

@@ -0,0 +1,102 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+
+name: js-token-interface-v2
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  token-interface-js-v2:
+    name: token-interface-js-v2
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+
+    services:
+      redis:
+        image: redis:8.0.1
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      LIGHT_PROTOCOL_VERSION: V2
+      REDIS_URL: redis://localhost:6379
+      CI: true
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v6
+        with:
+          submodules: true
+
+      - name: Setup and build
+        uses: ./.github/actions/setup-and-build
+        with:
+          skip-components: "redis,disk-cleanup,go"
+          cache-key: "js"
+
+      - name: Build token-interface with V2
+        run: |
+          cd js/token-interface
+          pnpm build:v2
+
+      - name: Build CLI
+        run: |
+          just cli build
+
+      - name: Run token-interface unit tests with V2
+        run: |
+          echo "Running token-interface unit tests with retry logic (max 2 attempts)..."
+          attempt=1
+          max_attempts=2
+          until just js test-token-interface-unit-v2; do
+            attempt=$((attempt + 1))
+            if [ $attempt -gt $max_attempts ]; then
+              echo "Tests failed after $max_attempts attempts"
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts failed, retrying..."
+            sleep 5
+          done
+          echo "Tests passed on attempt $attempt"
+
+      - name: Run token-interface e2e tests with V2
+        run: |
+          echo "Running token-interface e2e tests with retry logic (max 2 attempts)..."
+          attempt=1
+          max_attempts=2
+          until just js test-token-interface-e2e-v2; do
+            attempt=$((attempt + 1))
+            if [ $attempt -gt $max_attempts ]; then
+              echo "Tests failed after $max_attempts attempts"
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts failed, retrying..."
+            sleep 5
+          done
+          echo "Tests passed on attempt $attempt"
+
+      - name: Display prover logs on failure
+        if: failure()
+        run: |
+          echo "=== Displaying prover logs ==="
+          find . -path "*/test-ledger/*prover*.log" -type f -exec echo "=== Contents of {} ===" \; -exec cat {} \; -exec echo "=== End of {} ===" \; || echo "No prover logs found"

.github/workflows/js-v2.yml

@@ -4,7 +4,7 @@ on:
       - main
   pull_request:
     branches:
-      - "*"
+      - "**"
     types:
       - opened
       - synchronize

.gitignore

@@ -66,6 +66,7 @@ api-docs/
 # Third-party dependencies
 /.local
 /.vscode
+.cursor/
 
 **/.idea
 **/*.iml

js/justfile

@@ -6,22 +6,34 @@ default:
 build:
     cd stateless.js && pnpm build
     cd compressed-token && pnpm build
+    cd token-interface && pnpm build
 
-test: test-stateless test-compressed-token
+test: test-stateless test-compressed-token test-token-interface
 
 test-stateless:
     cd stateless.js && pnpm test
 
 test-compressed-token:
     cd compressed-token && pnpm test
 
+test-token-interface:
+    cd token-interface && pnpm test
+
+test-token-interface-unit-v2:
+    cd token-interface && pnpm test:unit:all
+
+test-token-interface-e2e-v2:
+    cd token-interface && pnpm test:e2e:all
+
 test-compressed-token-unit-v2:
     cd compressed-token && pnpm test:unit:all:v2
 
 lint:
     cd stateless.js && pnpm lint
     cd compressed-token && pnpm lint
+    cd token-interface && pnpm lint
 
 format:
     cd stateless.js && pnpm format
     cd compressed-token && pnpm format
+    cd token-interface && pnpm format

js/token-interface/.prettierrc

@@ -0,0 +1,10 @@
+{
+    "semi": true,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "printWidth": 80,
+    "useTabs": false,
+    "tabWidth": 4,
+    "bracketSpacing": true,
+    "arrowParens": "avoid"
+}

js/token-interface/README.md

@@ -0,0 +1,104 @@
+# `@lightprotocol/token-interface`
+
+Payments-focused helpers for Light rent-free token flows.
+
+Use this when you want SPL-style transfers with unified sender handling:
+
+- sender side auto wraps/loads into light ATA
+- recipient ATA can be light (default), SPL, or Token-2022 via `tokenProgram`
+
+## RPC client (required)
+
+All builders expect `createRpc()` from `@lightprotocol/stateless.js`.
+
+```ts
+import { createRpc } from '@lightprotocol/stateless.js';
+
+// Add this to your client. It is a superset of web3.js Connection RPC plus Light APIs.
+const rpc = createRpc();
+// Optional: createRpc(clusterUrl)
+```
+
+## Canonical for Kit users
+
+Use `createTransferInstructionPlan` from `/kit`.
+
+```ts
+import { createTransferInstructionPlan } from '@lightprotocol/token-interface/kit';
+
+const transferPlan = await createTransferInstructionPlan({
+    rpc,
+    payer: payer.publicKey,
+    mint,
+    sourceOwner: sender.publicKey,
+    authority: sender.publicKey,
+    recipient: customer.publicKey,
+    // Optional destination program:
+    // tokenProgram: TOKEN_PROGRAM_ID
+    amount: 25n,
+});
+```
+
+If you prefer Kit instruction arrays instead of plans:
+
+```ts
+import { createTransferInstructions } from '@lightprotocol/token-interface/kit';
+```
+
+## Canonical for web3.js users
+
+Use `createTransferInstructions` from the root export.
+
+```ts
+import { createTransferInstructions } from '@lightprotocol/token-interface';
+
+const instructions = await createTransferInstructions({
+    rpc,
+    payer: payer.publicKey,
+    mint,
+    sourceOwner: sender.publicKey,
+    authority: sender.publicKey,
+    recipient: customer.publicKey,
+    amount: 25n,
+});
+
+// add memo if needed, then build/sign/send transaction
+```
+
+## Raw single-instruction helpers
+
+Use these when you want manual orchestration:
+
+```ts
+import {
+    createAtaInstruction,
+    createLoadInstruction,
+    createTransferCheckedInstruction,
+} from '@lightprotocol/token-interface/instructions';
+```
+
+## No-wrap instruction-flow builders (advanced)
+
+If you explicitly want to disable automatic sender wrapping, use:
+
+```ts
+import { createTransferInstructionsNowrap } from '@lightprotocol/token-interface/instructions';
+```
+
+## Read account
+
+```ts
+import { getAta } from '@lightprotocol/token-interface';
+
+const account = await getAta({ rpc, owner: customer.publicKey, mint });
+console.log(account.amount, account.hotAmount, account.compressedAmount);
+```
+
+## Important rules
+
+- Only one compressed sender account is loaded per call; smaller ones are ignored for that call.
+- Transfer always builds checked semantics.
+- Canonical builders always use wrap-enabled sender setup (`createTransferInstructions`, `createLoadInstructions`, `createApproveInstructions`, `createRevokeInstructions`).
+- If sender SPL/T22 balances are wrapped by the flow, source SPL/T22 ATAs are not auto-closed.
+- Recipient ATA is derived from `(recipient, mint, tokenProgram)`; default is light token program.
+- Recipient-side load is still intentionally disabled.

js/token-interface/cucumber.js

@@ -0,0 +1,26 @@
+const common = {
+    requireModule: ['tsx'],
+    require: [
+        'tests/support/**/*.ts',
+        'tests/step-definitions/**/*.steps.ts',
+    ],
+    format: ['progress'],
+    formatOptions: { snippetInterface: 'async-await' },
+};
+
+const defaultProfile = {
+    ...common,
+    paths: ['features/**/*.feature'],
+};
+
+export { defaultProfile as default };
+
+export const unit = {
+    ...common,
+    paths: ['features/unit/**/*.feature'],
+};
+
+export const e2e = {
+    ...common,
+    paths: ['features/e2e/**/*.feature'],
+};