chore: v0.1.1 for token-interface

.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"

.gitignore

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

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightprotocol/zk-compression-cli",
-  "version": "0.28.1",
+  "version": "0.28.3",
   "description": "ZK Compression: Secure Scaling on Solana",
   "maintainers": [
     {

js/compressed-token/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lightprotocol/compressed-token",
-    "version": "0.23.1",
+    "version": "0.23.3",
     "description": "JS client to interact with the compressed-token program",
     "sideEffects": false,
     "main": "dist/cjs/node/index.cjs",

js/compressed-token/src/v3/instructions/unwrap.ts

@@ -77,7 +77,6 @@ export function createUnwrapInstruction(
     const SOURCE_INDEX = 2;
     const DESTINATION_INDEX = 3;
     const POOL_INDEX = 4;
-    const _SPL_TOKEN_PROGRAM_INDEX = 5;
     const LIGHT_TOKEN_PROGRAM_INDEX = 6;
 
     // Unwrap flow: compress from light-token, decompress to SPL

js/compressed-token/src/v3/instructions/wrap.ts

@@ -46,7 +46,6 @@ export function createWrapInstruction(
     const SOURCE_INDEX = 2;
     const DESTINATION_INDEX = 3;
     const POOL_INDEX = 4;
-    const _SPL_TOKEN_PROGRAM_INDEX = 5;
     const LIGHT_TOKEN_PROGRAM_INDEX = 6;
 
     const compressions: Compression[] = [

js/compressed-token/tests/e2e/approve-revoke-light-token.test.ts

@@ -485,7 +485,9 @@ describe('LightToken approve/revoke - E2E', () => {
         const { blockhash } = await rpc.getLatestBlockhash();
         const tx = buildAndSignTx([ix], payer, blockhash, [wrongSigner]);
 
-        await expect(sendAndConfirmTx(rpc, tx)).rejects.toThrow();
+        await expect(sendAndConfirmTx(rpc, tx)).rejects.toThrow(
+            /owner|authority|custom program error|instruction error/i,
+        );
     }, 60_000);
 
     it('should work with separate fee payer', async () => {

js/compressed-token/tests/e2e/transfer-delegated-failures.test.ts

@@ -95,7 +95,7 @@ describe('transferDelegatedInterface - failure cases', () => {
                 undefined,
                 undefined,
             ),
-        ).rejects.toThrow();
+        ).rejects.toThrow(/Insufficient delegated balance/);
     }, 30_000);
 
     it('rejects transfer from unapproved signer', async () => {
@@ -112,7 +112,7 @@ describe('transferDelegatedInterface - failure cases', () => {
                 undefined,
                 undefined,
             ),
-        ).rejects.toThrow();
+        ).rejects.toThrow(/Signer is not the owner or a delegate/);
     }, 30_000);
 
     it('rejects transfer after revoke', async () => {
@@ -132,6 +132,6 @@ describe('transferDelegatedInterface - failure cases', () => {
                 undefined,
                 undefined,
             ),
-        ).rejects.toThrow();
+        ).rejects.toThrow(/Signer is not the owner or a delegate/);
     }, 60_000);
 });

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/stateless.js/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lightprotocol/stateless.js",
-    "version": "0.23.1",
+    "version": "0.23.3",
     "description": "JavaScript API for Light & ZK Compression",
     "sideEffects": false,
     "main": "dist/cjs/node/index.cjs",

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,105 @@
+# `@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,
+    createLoadInstructions,
+    createTransferCheckedInstruction,
+} from '@lightprotocol/token-interface/instructions';
+```
+
+## No-wrap instruction-flow builders (advanced)
+
+If you explicitly want to disable automatic sender wrapping, use the dedicated
+`/nowrap` entrypoint with the same function names:
+
+```ts
+import { createTransferInstructions } from '@lightprotocol/token-interface/nowrap';
+```
+
+## 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.