@yellow-org/sdk 1.1.1 → 1.2.0

package/README.md

@@ -1,7 +1,7 @@
 # Yellow TypeScript SDK
 
 [![npm version](https://img.shields.io/npm/v/@yellow-org/sdk.svg)](https://www.npmjs.com/package/@yellow-org/sdk)
-[![License](https://img.shields.io/npm/l/@yellow-org/sdk.svg)](https://github.com/erc7824/nitrolite/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/@yellow-org/sdk.svg)](https://github.com/layer-3/nitrolite/blob/main/LICENSE)
 
 TypeScript SDK for Clearnode payment channels providing both high-level and low-level operations in a unified client:
 - **State Operations**: `deposit()`, `withdraw()`, `transfer()`, `closeHomeChannel()`, `acknowledge()` - build and co-sign states off-chain
@@ -9,7 +9,7 @@ TypeScript SDK for Clearnode payment channels providing both high-level and low-
 - **Low-Level Operations**: Direct RPC access for custom flows and advanced use cases
 - **Full Feature Parity**: 100% compatibility with Go SDK functionality
 
-> If you are migrating from `@erc7824/nitrolite@v0.5.3`, please consider using the [@yellow-org/sdk-compat](https://www.npmjs.com/package/@yellow-org/sdk-compat) package. It is a translation layer that uses this SDK underneath and maps the familiar v0.5.3 API surfaces to this SDK.
+> If you are migrating from `@layer-3/nitrolite@v0.5.3`, please consider using the [@yellow-org/sdk-compat](https://www.npmjs.com/package/@yellow-org/sdk-compat) package. It is a translation layer that uses this SDK underneath and maps the familiar v0.5.3 API surfaces to this SDK.
 
 ## Method Cheat Sheet
 
@@ -52,11 +52,18 @@ client.getEscrowChannel(escrowChannelId)           // Escrow channel info
 client.getLatestState(wallet, asset, onlySigned)   // Latest state
 ```
 
+### App Registry
+```typescript
+client.getApps(opts)                                            // List registered apps
+client.registerApp(appID, metadata, approvalNotRequired)         // Register new app
+```
+
 ### App Sessions
 ```typescript
 client.getAppSessions(opts)                                     // List sessions
 client.getAppDefinition(appSessionId)                           // Session definition
 client.createAppSession(definition, sessionData, sigs)          // Create session
+client.createAppSession(def, data, sigs, { ownerSig })          // Create with owner approval
 client.submitAppSessionDeposit(update, sigs, asset, amount)     // Deposit to session
 client.submitAppState(update, sigs)                             // Update session
 client.rebalanceAppSessions(signedUpdates)                      // Atomic rebalance
@@ -145,7 +152,7 @@ main().catch(console.error);
 ```
 sdk/ts/src/
 ├── client.ts         # Core client, constructors, high-level operations
-├── signers.ts        # EthereumMsgSigner and EthereumRawSigner
+├── signers.ts        # Signers (EthereumMsg/Raw, Channel, AppSession)
 ├── config.ts         # Configuration options
 ├── asset_store.ts    # Asset metadata caching
 ├── utils.ts          # Type transformations
@@ -391,6 +398,21 @@ const state = await client.getLatestState(wallet, asset, onlySigned);
 
 **Note:** State submission and channel creation are handled internally by state operations (`deposit()`, `withdraw()`, `transfer()`). On-chain settlement is handled by `checkpoint()`.
 
+### App Registry
+
+```typescript
+// List registered applications with optional filtering
+const { apps, metadata } = await client.getApps({
+  appId: 'my-app',
+  ownerWallet: '0x1234...',
+  page: 1,
+  pageSize: 10,
+});
+
+// Register a new application
+await client.registerApp('my-app', '{"name": "My App"}', false);
+```
+
 ### App Sessions (Low-Level)
 
 ```typescript
@@ -417,6 +439,50 @@ await client.submitAppState(appUpdate, quorumSigs);
 const batchId = await client.rebalanceAppSessions(signedUpdates);
 ```
 
+#### Owner Approval for App Session Creation
+
+When an app is registered with `creationApprovalNotRequired: false`, the app owner must sign the session creation request. Pass the owner's signature via the options parameter:
+
+```typescript
+import { AppSessionWalletSignerV1, EthereumMsgSigner } from '@yellow-org/sdk';
+
+// Owner signs the create request using their app session signer
+const ownerMsgSigner = new EthereumMsgSigner(ownerPrivateKey);
+const ownerAppSessionSigner = new AppSessionWalletSignerV1(ownerMsgSigner);
+const ownerSig = await ownerAppSessionSigner.signMessage(createRequest);
+
+const { appSessionId } = await client.createAppSession(
+  definition,
+  sessionData,
+  quorumSigs,
+  { ownerSig }
+);
+```
+
+### App Session Signers
+
+App session operations require signatures with a type byte prefix, similar to channel signers:
+
+| Type | Byte | Class | Usage |
+|------|------|-------|-------|
+| Wallet | `0xA1` | `AppSessionWalletSignerV1` | Main wallet signs app session operations |
+| Session Key | `0xA2` | `AppSessionKeySignerV1` | Delegated session key signs on behalf of wallet |
+
+```typescript
+import { EthereumMsgSigner, AppSessionWalletSignerV1, AppSessionKeySignerV1 } from '@yellow-org/sdk';
+
+// Create app session wallet signer
+const msgSigner = new EthereumMsgSigner(privateKey);
+const appSessionSigner = new AppSessionWalletSignerV1(msgSigner);
+
+// Sign app session operations (create, deposit, state updates, etc.)
+const sig = await appSessionSigner.signMessage(packedRequest);
+
+// For session key delegation
+const sessionKeyMsgSigner = new EthereumMsgSigner(sessionKeyPrivateKey);
+const sessionKeySigner = new AppSessionKeySignerV1(sessionKeyMsgSigner);
+```
+
 ### App Session Keys
 
 ```typescript
@@ -734,8 +800,17 @@ queryTransactions().catch(console.error);
 
 ### Example 4: App Session Workflow
 
+For a comprehensive multi-party app session example including app registration, owner approval,
+session key delegation, deposits, redistribution, and more, see
+[examples/app_sessions/lifecycle.ts](examples/app_sessions/lifecycle.ts).
+
 ```typescript
-import { Client, createSigners, withBlockchainRPC } from '@yellow-org/sdk';
+import {
+  Client, createSigners, EthereumMsgSigner,
+  AppSessionWalletSignerV1, withBlockchainRPC
+} from '@yellow-org/sdk';
+import { AppStateUpdateIntent } from '@yellow-org/sdk/app/types';
+import { packCreateAppSessionRequestV1, packAppStateUpdateV1 } from '@yellow-org/sdk/app/packing';
 import Decimal from 'decimal.js';
 
 async function appSessionExample() {
@@ -748,42 +823,55 @@ async function appSessionExample() {
   );
 
   try {
+    // Register app (required before creating sessions)
+    await client.registerApp('chess-v1', '{}', true);
+
+    // Create app session signer
+    const msgSigner = new EthereumMsgSigner(process.env.PRIVATE_KEY!);
+    const appSessionSigner = new AppSessionWalletSignerV1(msgSigner);
+
     // Create app session
     const definition = {
-      application: 'chess-v1',
+      applicationId: 'chess-v1',
       participants: [
-        { walletAddress: client.getUserAddress(), signatureWeight: 1 },
-        { walletAddress: '0xOpponent...', signatureWeight: 1 },
+        { walletAddress: client.getUserAddress(), signatureWeight: 100 },
       ],
-      quorum: 2,
-      nonce: 1n,
+      quorum: 100,
+      nonce: BigInt(Date.now() * 1000000),
     };
 
+    const createRequest = packCreateAppSessionRequestV1(definition, '{}');
+    const createSig = await appSessionSigner.signMessage(createRequest);
+
     const { appSessionId } = await client.createAppSession(
       definition,
       '{}',
-      ['sig1', 'sig2']
+      [createSig]
     );
     console.log('Session created:', appSessionId);
 
     // Deposit to app session
+    const depositAmount = new Decimal(50);
     const appUpdate = {
       appSessionId,
-      intent: 1, // Deposit
-      version: 1n,
+      intent: AppStateUpdateIntent.Deposit,
+      version: 2n,
       allocations: [{
         participant: client.getUserAddress(),
         asset: 'usdc',
-        amount: new Decimal(50),
+        amount: depositAmount,
       }],
       sessionData: '{}',
     };
 
+    const depositRequest = packAppStateUpdateV1(appUpdate);
+    const depositSig = await appSessionSigner.signMessage(depositRequest);
+
     const nodeSig = await client.submitAppSessionDeposit(
       appUpdate,
-      ['sig1'],
+      [depositSig],
       'usdc',
-      new Decimal(50)
+      depositAmount
     );
     console.log('Deposit signature:', nodeSig);
 
@@ -854,6 +942,20 @@ import type {
   ChannelSessionKeyStateV1,
   PaginationMetadata,
 } from '@yellow-org/sdk';
+
+// Signer types
+import {
+  EthereumMsgSigner,
+  EthereumRawSigner,
+  ChannelDefaultSigner,
+  ChannelSessionKeyStateSigner,
+  AppSessionWalletSignerV1,
+  AppSessionKeySignerV1,
+  createSigners,
+} from '@yellow-org/sdk';
+
+// App Registry types (from rpc/types)
+import type { AppV1, AppInfoV1 } from '@yellow-org/sdk';
 ```
 
 ### BigInt for Chain IDs
@@ -976,8 +1078,8 @@ Part of the Nitrolite project. See [LICENSE](../../LICENSE) for details.
 ## Related Projects
 
 - [Nitrolite TS Compat](https://www.npmjs.com/package/@yellow-org/sdk-compat) - Compatibility layer for older TypeScript versions
-- [Nitrolite Go SDK](https://github.com/erc7824/nitrolite/tree/stable/sdk/go) - Go implementation with same API
-- [Nitrolite Smart Contracts](https://github.com/erc7824/nitrolite/tree/stable/contracts) - On-chain contracts
+- [Nitrolite Go SDK](https://github.com/layer-3/nitrolite/tree/stable/sdk/go) - Go implementation with same API
+- [Nitrolite Smart Contracts](https://github.com/layer-3/nitrolite/tree/stable/contracts) - On-chain contracts
 
 ---
 

package/dist/app/packing.d.ts

@@ -1,7 +1,9 @@
 import { AppDefinitionV1, AppStateUpdateV1, AppSessionKeyStateV1, AppSessionVersionV1 } from './types';
+import { AppV1 } from '../rpc/types';
 export declare function packCreateAppSessionRequestV1(definition: AppDefinitionV1, sessionData: string): `0x${string}`;
 export declare function packAppStateUpdateV1(stateUpdate: AppStateUpdateV1): `0x${string}`;
 export declare function generateAppSessionIDV1(definition: AppDefinitionV1): `0x${string}`;
 export declare function generateRebalanceBatchIDV1(sessionVersions: AppSessionVersionV1[]): `0x${string}`;
 export declare function generateRebalanceTransactionIDV1(batchId: string, sessionId: string, asset: string): `0x${string}`;
+export declare function packAppV1(app: AppV1): `0x${string}`;
 export declare function packAppSessionKeyStateV1(state: AppSessionKeyStateV1): `0x${string}`;

package/dist/app/packing.js

@@ -1,4 +1,4 @@
-import { encodeAbiParameters, keccak256 } from 'viem';
+import { encodeAbiParameters, keccak256, pad, toHex } from 'viem';
 export function packCreateAppSessionRequestV1(definition, sessionData) {
     const participantComponents = [
         { name: 'walletAddress', type: 'address' },
@@ -15,7 +15,7 @@ export function packCreateAppSessionRequestV1(definition, sessionData) {
         { type: 'uint64' },
         { type: 'string' },
     ], [
-        definition.application,
+        definition.applicationId,
         participants,
         definition.quorum,
         definition.nonce,
@@ -64,7 +64,7 @@ export function generateAppSessionIDV1(definition) {
         { type: 'tuple[]', components: participantComponents },
         { type: 'uint8' },
         { type: 'uint64' },
-    ], [definition.application, participants, definition.quorum, definition.nonce]);
+    ], [definition.applicationId, participants, definition.quorum, definition.nonce]);
     return keccak256(packed);
 }
 export function generateRebalanceBatchIDV1(sessionVersions) {
@@ -89,9 +89,43 @@ export function generateRebalanceTransactionIDV1(batchId, sessionId, asset) {
     ], [batchId, sessionId, asset]);
     return keccak256(packed);
 }
+export function packAppV1(app) {
+    const metadataHash = keccak256(toHex(new TextEncoder().encode(app.metadata)));
+    const packed = encodeAbiParameters([
+        { type: 'string' },
+        { type: 'address' },
+        { type: 'bytes32' },
+        { type: 'uint64' },
+        { type: 'bool' },
+    ], [
+        app.id,
+        app.owner_wallet,
+        metadataHash,
+        BigInt(app.version),
+        app.creation_approval_not_required,
+    ]);
+    return keccak256(packed);
+}
+function hexToBytes32(s) {
+    let hex = s.startsWith('0x') || s.startsWith('0X') ? s.slice(2) : s;
+    if (hex.length % 2 === 1) {
+        hex = '0' + hex;
+    }
+    if (!/^[0-9a-fA-F]*$/.test(hex)) {
+        return pad('0x00', { size: 32 });
+    }
+    if (hex.length === 0) {
+        return pad('0x00', { size: 32 });
+    }
+    if (hex.length > 64) {
+        hex = hex.slice(hex.length - 64);
+    }
+    const padded = hex.padStart(64, '0');
+    return `0x${padded}`;
+}
 export function packAppSessionKeyStateV1(state) {
-    const applicationIDHashes = state.application_ids.map((id) => id);
-    const appSessionIDHashes = state.app_session_ids.map((id) => id);
+    const applicationIDHashes = state.application_ids.map(hexToBytes32);
+    const appSessionIDHashes = state.app_session_ids.map(hexToBytes32);
     const packed = encodeAbiParameters([
         { type: 'address' },
         { type: 'address' },

package/dist/app/types.d.ts

@@ -31,7 +31,7 @@ export interface AppParticipantV1 {
     signatureWeight: number;
 }
 export interface AppDefinitionV1 {
-    application: string;
+    applicationId: string;
     participants: AppParticipantV1[];
     quorum: number;
     nonce: bigint;
@@ -58,12 +58,10 @@ export interface SignedAppStateUpdateV1 {
 }
 export interface AppSessionInfoV1 {
     appSessionId: string;
+    appDefinition: AppDefinitionV1;
     isClosed: boolean;
-    participants: AppParticipantV1[];
     sessionData: string;
-    quorum: number;
     version: bigint;
-    nonce: bigint;
     allocations: AppAllocationV1[];
 }
 export interface SessionKeyV1 {

package/dist/blockchain/evm/app_registry_abi.d.ts

@@ -0,0 +1,88 @@
+export declare const AppRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "asset";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "UNLOCK_PERIOD";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly inputs: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "lockStateOf";
+    readonly inputs: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "unlockTimestampOf";
+    readonly inputs: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "lock";
+    readonly inputs: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "relock";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "unlock";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "withdraw";
+    readonly inputs: readonly [{
+        readonly name: "destination";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}];

package/dist/blockchain/evm/app_registry_abi.js

@@ -0,0 +1,68 @@
+export const AppRegistryAbi = [
+    {
+        type: 'function',
+        name: 'asset',
+        inputs: [],
+        outputs: [{ name: '', type: 'address' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'UNLOCK_PERIOD',
+        inputs: [],
+        outputs: [{ name: '', type: 'uint256' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'balanceOf',
+        inputs: [{ name: 'user', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'lockStateOf',
+        inputs: [{ name: 'user', type: 'address' }],
+        outputs: [{ name: '', type: 'uint8' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'unlockTimestampOf',
+        inputs: [{ name: 'user', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'function',
+        name: 'lock',
+        inputs: [
+            { name: 'target', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+    {
+        type: 'function',
+        name: 'relock',
+        inputs: [],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+    {
+        type: 'function',
+        name: 'unlock',
+        inputs: [],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+    {
+        type: 'function',
+        name: 'withdraw',
+        inputs: [{ name: 'destination', type: 'address' }],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+];

package/dist/blockchain/evm/index.d.ts

@@ -4,3 +4,5 @@ export * from './utils';
 export * from './erc20';
 export * from './channel_hub_abi';
 export * from './client';
+export * from './app_registry_abi';
+export * from './locking_client';

package/dist/blockchain/evm/index.js

@@ -4,3 +4,5 @@ export * from './utils';
 export * from './erc20';
 export * from './channel_hub_abi';
 export * from './client';
+export * from './app_registry_abi';
+export * from './locking_client';

package/dist/blockchain/evm/locking_client.d.ts

@@ -0,0 +1,21 @@
+import { Address } from 'viem';
+import Decimal from 'decimal.js';
+import { EVMClient, WalletSigner } from './interface';
+export declare class LockingClient {
+    private contractAddress;
+    private evmClient;
+    private walletSigner?;
+    private tokenAddress?;
+    private tokenDecimals?;
+    constructor(contractAddress: Address, evmClient: EVMClient, walletSigner?: WalletSigner);
+    private requireWalletSigner;
+    private ensureTokenInfo;
+    lock(target: Address, amount: Decimal): Promise<string>;
+    relock(): Promise<string>;
+    unlock(): Promise<string>;
+    withdraw(destination: Address): Promise<string>;
+    approveToken(amount: Decimal): Promise<string>;
+    getBalance(user: Address): Promise<Decimal>;
+    getLockState(user: Address): Promise<number>;
+    getTokenDecimals(): Promise<number>;
+}

package/dist/blockchain/evm/locking_client.js

@@ -0,0 +1,124 @@
+import Decimal from 'decimal.js';
+import { decimalToBigInt } from '../../core/utils';
+import { AppRegistryAbi } from './app_registry_abi';
+import { Erc20Abi } from './erc20_abi';
+export class LockingClient {
+    constructor(contractAddress, evmClient, walletSigner) {
+        this.contractAddress = contractAddress;
+        this.evmClient = evmClient;
+        this.walletSigner = walletSigner;
+    }
+    requireWalletSigner() {
+        if (!this.walletSigner) {
+            throw new Error('Write operations require a wallet signer. In Node.js, use a TransactionSigner that implements getAccount() (e.g., EthereumRawSigner)');
+        }
+        return this.walletSigner;
+    }
+    async ensureTokenInfo() {
+        if (this.tokenAddress !== undefined && this.tokenDecimals !== undefined) {
+            return { address: this.tokenAddress, decimals: this.tokenDecimals };
+        }
+        const tokenAddress = await this.evmClient.readContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'asset',
+        });
+        const decimals = await this.evmClient.readContract({
+            address: tokenAddress,
+            abi: Erc20Abi,
+            functionName: 'decimals',
+        });
+        this.tokenAddress = tokenAddress;
+        this.tokenDecimals = decimals;
+        return { address: tokenAddress, decimals };
+    }
+    async lock(target, amount) {
+        const walletSigner = this.requireWalletSigner();
+        const { decimals } = await this.ensureTokenInfo();
+        const amountBig = decimalToBigInt(amount, decimals);
+        const { request } = await this.evmClient.simulateContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'lock',
+            args: [target, amountBig],
+            account: walletSigner.account.address,
+        });
+        const hash = await walletSigner.writeContract(request);
+        await this.evmClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    async relock() {
+        const walletSigner = this.requireWalletSigner();
+        const { request } = await this.evmClient.simulateContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'relock',
+            account: walletSigner.account.address,
+        });
+        const hash = await walletSigner.writeContract(request);
+        await this.evmClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    async unlock() {
+        const walletSigner = this.requireWalletSigner();
+        const { request } = await this.evmClient.simulateContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'unlock',
+            account: walletSigner.account.address,
+        });
+        const hash = await walletSigner.writeContract(request);
+        await this.evmClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    async withdraw(destination) {
+        const walletSigner = this.requireWalletSigner();
+        const { request } = await this.evmClient.simulateContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'withdraw',
+            args: [destination],
+            account: walletSigner.account.address,
+        });
+        const hash = await walletSigner.writeContract(request);
+        await this.evmClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    async approveToken(amount) {
+        const walletSigner = this.requireWalletSigner();
+        const { address: tokenAddress, decimals } = await this.ensureTokenInfo();
+        const amountBig = decimalToBigInt(amount, decimals);
+        const { request } = await this.evmClient.simulateContract({
+            address: tokenAddress,
+            abi: Erc20Abi,
+            functionName: 'approve',
+            args: [this.contractAddress, amountBig],
+            account: walletSigner.account.address,
+        });
+        const hash = await walletSigner.writeContract(request);
+        await this.evmClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    async getBalance(user) {
+        const { decimals } = await this.ensureTokenInfo();
+        const balance = await this.evmClient.readContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'balanceOf',
+            args: [user],
+        });
+        return new Decimal(balance.toString()).div(Decimal.pow(10, decimals));
+    }
+    async getLockState(user) {
+        return await this.evmClient.readContract({
+            address: this.contractAddress,
+            abi: AppRegistryAbi,
+            functionName: 'lockStateOf',
+            args: [user],
+        });
+    }
+    async getTokenDecimals() {
+        const { decimals } = await this.ensureTokenInfo();
+        return decimals;
+    }
+}

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import { Address, Hex } from 'viem';
 import Decimal from 'decimal.js';
 import * as core from './core';
 import * as app from './app';
-import { ChannelSessionKeyStateV1 } from './rpc/types';
+import { ChannelSessionKeyStateV1, AppInfoV1 } from './rpc/types';
 import { Option } from './config';
 import { StateSigner, TransactionSigner } from './signers';
 export declare const DEFAULT_CHALLENGE_PERIOD = 86400;
@@ -13,6 +13,7 @@ export declare class Client {
     private exitPromise;
     private exitResolve?;
     private blockchainClients;
+    private blockchainLockingClients;
     private homeBlockchains;
     private stateSigner;
     private txSigner;
@@ -34,6 +35,12 @@ export declare class Client {
     challenge(state: core.State): Promise<string>;
     approveToken(chainId: bigint, asset: string, amount: Decimal): Promise<string>;
     checkTokenAllowance(chainId: bigint, tokenAddress: string, owner: string): Promise<bigint>;
+    escrowSecurityTokens(targetWalletAddress: string, blockchainId: bigint, amount: Decimal): Promise<string>;
+    initiateSecurityTokensWithdrawal(blockchainId: bigint): Promise<string>;
+    cancelSecurityTokensWithdrawal(blockchainId: bigint): Promise<string>;
+    withdrawSecurityTokens(blockchainId: bigint, destinationWalletAddress: string): Promise<string>;
+    approveSecurityToken(chainId: bigint, amount: Decimal): Promise<string>;
+    getLockedBalance(chainId: bigint, wallet: string): Promise<Decimal>;
     ping(): Promise<void>;
     getConfig(): Promise<core.NodeConfig>;
     getBlockchains(): Promise<core.Blockchain[]>;
@@ -50,6 +57,7 @@ export declare class Client {
         transactions: core.Transaction[];
         metadata: core.PaginationMetadata;
     }>;
+    getActionAllowances(wallet: Address): Promise<core.ActionAllowance[]>;
     getChannels(wallet: Address, options?: {
         status?: string;
         asset?: string;
@@ -73,7 +81,9 @@ export declare class Client {
         metadata: core.PaginationMetadata;
     }>;
     getAppDefinition(appSessionId: string): Promise<app.AppDefinitionV1>;
-    createAppSession(definition: app.AppDefinitionV1, sessionData: string, quorumSigs: string[]): Promise<{
+    createAppSession(definition: app.AppDefinitionV1, sessionData: string, quorumSigs: string[], opts?: {
+        ownerSig?: string;
+    }): Promise<{
         appSessionId: string;
         version: string;
         status: string;
@@ -81,13 +91,26 @@ export declare class Client {
     submitAppSessionDeposit(appStateUpdate: app.AppStateUpdateV1, quorumSigs: string[], asset: string, depositAmount: Decimal): Promise<string>;
     submitAppState(appStateUpdate: app.AppStateUpdateV1, quorumSigs: string[]): Promise<void>;
     rebalanceAppSessions(signedUpdates: app.SignedAppStateUpdateV1[]): Promise<string>;
+    getApps(options?: {
+        appId?: string;
+        ownerWallet?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<{
+        apps: AppInfoV1[];
+        metadata: core.PaginationMetadata;
+    }>;
+    registerApp(appID: string, metadata: string, creationApprovalNotRequired: boolean): Promise<void>;
     signChannelSessionKeyState(state: ChannelSessionKeyStateV1): Promise<Hex>;
     submitChannelSessionKeyState(state: ChannelSessionKeyStateV1): Promise<void>;
     getLastChannelKeyStates(userAddress: string, sessionKey?: string): Promise<ChannelSessionKeyStateV1[]>;
     signSessionKeyState(state: app.AppSessionKeyStateV1): Promise<Hex>;
     submitSessionKeyState(state: app.AppSessionKeyStateV1): Promise<void>;
     getLastKeyStates(userAddress: string, sessionKey?: string): Promise<app.AppSessionKeyStateV1[]>;
+    private getBlockchainRPCInfo;
+    private createEVMClients;
     private initializeBlockchainClient;
+    private initializeLockingClient;
     private buildSigValidatorsBitmap;
     private getSupportedSigValidatorsBitmap;
     private getNodeAddress;

package/dist/client.js

@@ -5,7 +5,7 @@ import { RPCClient } from './rpc/client';
 import { WebsocketDialer } from './rpc/dialer';
 import { ClientAssetStore } from './asset_store';
 import { DefaultConfig } from './config';
-import { generateNonce, transformNodeConfig, transformAssets, transformBalances, transformChannel, transformState, transformTransaction, transformPaginationMetadata, transformAppDefinitionToRPC, transformAppStateUpdateToRPC, transformSignedAppStateUpdateToRPC, transformAppSessionInfo, transformAppDefinitionFromRPC, } from './utils';
+import { generateNonce, transformNodeConfig, transformAssets, transformBalances, transformChannel, transformState, transformTransaction, transformPaginationMetadata, transformAppDefinitionToRPC, transformAppStateUpdateToRPC, transformSignedAppStateUpdateToRPC, transformAppSessionInfo, transformAppDefinitionFromRPC, transformActionAllowance, } from './utils';
 import * as blockchain from './blockchain';
 import { nextState, applyChannelCreation, applyAcknowledgementTransition, applyHomeDepositTransition, applyHomeWithdrawalTransition, applyTransferSendTransition, applyFinalizeTransition, applyCommitTransition } from './core/state';
 import { newVoidState } from './core/types';
@@ -30,6 +30,7 @@ export class Client {
         this.txSigner = txSigner;
         this.assetStore = assetStore;
         this.blockchainClients = new Map();
+        this.blockchainLockingClients = new Map();
         this.homeBlockchains = new Map();
         this.exitPromise = new Promise((resolve) => {
             this.exitResolve = resolve;
@@ -376,6 +377,30 @@ export class Client {
         const blockchainClient = this.blockchainClients.get(chainId);
         return await blockchainClient.checkAllowanceByAddress(tokenAddress, owner);
     }
+    async escrowSecurityTokens(targetWalletAddress, blockchainId, amount) {
+        await this.initializeLockingClient(blockchainId);
+        return this.blockchainLockingClients.get(blockchainId).lock(targetWalletAddress, amount);
+    }
+    async initiateSecurityTokensWithdrawal(blockchainId) {
+        await this.initializeLockingClient(blockchainId);
+        return this.blockchainLockingClients.get(blockchainId).unlock();
+    }
+    async cancelSecurityTokensWithdrawal(blockchainId) {
+        await this.initializeLockingClient(blockchainId);
+        return this.blockchainLockingClients.get(blockchainId).relock();
+    }
+    async withdrawSecurityTokens(blockchainId, destinationWalletAddress) {
+        await this.initializeLockingClient(blockchainId);
+        return this.blockchainLockingClients.get(blockchainId).withdraw(destinationWalletAddress);
+    }
+    async approveSecurityToken(chainId, amount) {
+        await this.initializeLockingClient(chainId);
+        return this.blockchainLockingClients.get(chainId).approveToken(amount);
+    }
+    async getLockedBalance(chainId, wallet) {
+        await this.initializeLockingClient(chainId);
+        return this.blockchainLockingClients.get(chainId).getBalance(wallet);
+    }
     async ping() {
         await this.rpcClient.nodeV1Ping();
     }
@@ -420,6 +445,11 @@ export class Client {
             metadata: transformPaginationMetadata(resp.metadata),
         };
     }
+    async getActionAllowances(wallet) {
+        const req = { wallet };
+        const resp = await this.rpcClient.userV1GetActionAllowances(req);
+        return resp.allowances.map(transformActionAllowance);
+    }
     async getChannels(wallet, options) {
         const req = {
             wallet,
@@ -486,12 +516,15 @@ export class Client {
         const resp = await this.rpcClient.appSessionsV1GetAppDefinition(req);
         return transformAppDefinitionFromRPC(resp.definition);
     }
-    async createAppSession(definition, sessionData, quorumSigs) {
+    async createAppSession(definition, sessionData, quorumSigs, opts) {
         const req = {
             definition: transformAppDefinitionToRPC(definition),
             session_data: sessionData,
             quorum_sigs: quorumSigs,
         };
+        if (opts?.ownerSig) {
+            req.owner_sig = opts.ownerSig;
+        }
         const resp = await this.rpcClient.appSessionsV1CreateAppSession(req);
         return {
             appSessionId: resp.app_session_id,
@@ -530,6 +563,40 @@ export class Client {
         const resp = await this.rpcClient.appSessionsV1RebalanceAppSessions(req);
         return resp.batch_id;
     }
+    async getApps(options) {
+        const req = {
+            app_id: options?.appId,
+            owner_wallet: options?.ownerWallet,
+            pagination: options?.page && options?.pageSize ? {
+                offset: (options.page - 1) * options.pageSize,
+                limit: options.pageSize,
+            } : undefined,
+        };
+        const resp = await this.rpcClient.appsV1GetApps(req);
+        return {
+            apps: resp.apps,
+            metadata: transformPaginationMetadata(resp.metadata),
+        };
+    }
+    async registerApp(appID, metadata, creationApprovalNotRequired) {
+        const appDef = {
+            id: appID,
+            owner_wallet: this.txSigner.getAddress(),
+            metadata,
+            version: '1',
+            creation_approval_not_required: creationApprovalNotRequired,
+        };
+        const packed = app.packAppV1(appDef);
+        if (!this.txSigner.signPersonalMessage) {
+            throw new Error('TransactionSigner must implement signPersonalMessage for app registration');
+        }
+        const ownerSig = await this.txSigner.signPersonalMessage(packed);
+        const req = {
+            app: appDef,
+            owner_sig: ownerSig,
+        };
+        await this.rpcClient.appsV1SubmitAppVersion(req);
+    }
     async signChannelSessionKeyState(state) {
         const metadataHash = core.getChannelSessionKeyAuthMetadataHashV1(BigInt(state.version), state.assets, BigInt(state.expires_at));
         const packed = core.packChannelKeyStateV1(state.session_key, metadataHash);
@@ -569,10 +636,7 @@ export class Client {
         const resp = await this.rpcClient.appSessionsV1GetLastKeyStates(req);
         return resp.states;
     }
-    async initializeBlockchainClient(chainId) {
-        if (this.blockchainClients.has(chainId)) {
-            return;
-        }
+    async getBlockchainRPCInfo(chainId) {
         const rpcUrl = this.config.blockchainRPCs?.get(chainId);
         if (!rpcUrl) {
             throw new Error(`blockchain RPC not configured for chain ${chainId} (use withBlockchainRPC)`);
@@ -580,10 +644,11 @@ export class Client {
         const config = await this.getConfig();
         const blockchainInfo = config.blockchains.find((b) => b.id === chainId);
         if (!blockchainInfo) {
-            throw new Error(`blockchain ${chainId} not supported by node`);
+            throw new Error(`blockchain ${chainId} not found in node config`);
         }
-        const contractAddress = blockchainInfo.channelHubAddress;
-        const nodeAddress = config.nodeAddress;
+        return { rpcUrl, blockchainInfo, config };
+    }
+    createEVMClients(chainId, rpcUrl) {
         const publicClient = createPublicClient({
             transport: http(rpcUrl),
         });
@@ -597,7 +662,7 @@ export class Client {
             },
         };
         const isBrowser = typeof window !== 'undefined' && typeof window.ethereum !== 'undefined';
-        let walletClient;
+        let walletClient = null;
         if (isBrowser) {
             walletClient = createWalletClient({
                 chain,
@@ -606,15 +671,44 @@ export class Client {
             });
         }
         else {
-            walletClient = createWalletClient({
-                chain,
-                transport: http(rpcUrl),
-                account: this.txSigner.getAddress(),
-            });
+            const account = this.txSigner.getAccount ? this.txSigner.getAccount() : undefined;
+            if (account) {
+                walletClient = createWalletClient({
+                    chain,
+                    transport: http(rpcUrl),
+                    account,
+                });
+            }
         }
-        const blockchainClient = new blockchain.evm.Client(contractAddress, publicClient, walletClient, chainId, nodeAddress, this.assetStore);
+        return { publicClient, walletClient };
+    }
+    async initializeBlockchainClient(chainId) {
+        if (this.blockchainClients.has(chainId)) {
+            return;
+        }
+        const { rpcUrl, blockchainInfo, config } = await this.getBlockchainRPCInfo(chainId);
+        if (!blockchainInfo.channelHubAddress) {
+            throw new Error(`channel hub address not configured for blockchain ${chainId}`);
+        }
+        const { publicClient, walletClient } = this.createEVMClients(chainId, rpcUrl);
+        if (!walletClient) {
+            throw new Error('Node.js environment requires a TransactionSigner that implements getAccount() (e.g., EthereumRawSigner)');
+        }
+        const blockchainClient = new blockchain.evm.Client(blockchainInfo.channelHubAddress, publicClient, walletClient, chainId, config.nodeAddress, this.assetStore);
         this.blockchainClients.set(chainId, blockchainClient);
     }
+    async initializeLockingClient(chainId) {
+        if (this.blockchainLockingClients.has(chainId)) {
+            return;
+        }
+        const { rpcUrl, blockchainInfo } = await this.getBlockchainRPCInfo(chainId);
+        if (!blockchainInfo.lockingContractAddress) {
+            throw new Error(`locking contract address not configured for blockchain ${chainId}`);
+        }
+        const { publicClient, walletClient } = this.createEVMClients(chainId, rpcUrl);
+        const lockingClient = new blockchain.evm.LockingClient(blockchainInfo.lockingContractAddress, publicClient, walletClient || undefined);
+        this.blockchainLockingClients.set(chainId, lockingClient);
+    }
     buildSigValidatorsBitmap(signerTypes) {
         const bitmap = new Uint8Array(32);
         for (const t of signerTypes) {

package/dist/core/types.d.ts

@@ -120,6 +120,7 @@ export interface Blockchain {
     name: string;
     id: bigint;
     channelHubAddress: Address;
+    lockingContractAddress?: Address;
     blockStep: bigint;
 }
 export interface Token {
@@ -154,6 +155,12 @@ export interface BalanceEntry {
     asset: string;
     balance: Decimal;
 }
+export interface ActionAllowance {
+    gatedAction: string;
+    timeWindow: string;
+    allowance: bigint;
+    used: bigint;
+}
 export interface PaginationParams {
     offset?: number;
     limit?: number;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Client, DEFAULT_CHALLENGE_PERIOD, type StateSigner, type TransactionSigner } from './client';
-export { EthereumMsgSigner, EthereumRawSigner, ChannelDefaultSigner, ChannelSessionKeyStateSigner, createSigners, } from './signers';
+export { EthereumMsgSigner, EthereumRawSigner, ChannelDefaultSigner, ChannelSessionKeyStateSigner, AppSessionWalletSignerV1, AppSessionKeySignerV1, createSigners, } from './signers';
 export { type Config, DefaultConfig, type Option, withHandshakeTimeout, withErrorHandler, withBlockchainRPC } from './config';
 export { ClientAssetStore } from './asset_store';
 export * from './utils';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { Client, DEFAULT_CHALLENGE_PERIOD } from './client';
-export { EthereumMsgSigner, EthereumRawSigner, ChannelDefaultSigner, ChannelSessionKeyStateSigner, createSigners, } from './signers';
+export { EthereumMsgSigner, EthereumRawSigner, ChannelDefaultSigner, ChannelSessionKeyStateSigner, AppSessionWalletSignerV1, AppSessionKeySignerV1, createSigners, } from './signers';
 export { DefaultConfig, withHandshakeTimeout, withErrorHandler, withBlockchainRPC } from './config';
 export { ClientAssetStore } from './asset_store';
 export * from './utils';

package/dist/rpc/api.d.ts

@@ -1,5 +1,5 @@
 import { Address } from 'viem';
-import { ChannelV1, ChannelDefinitionV1, ChannelSessionKeyStateV1, StateV1, BalanceEntryV1, TransactionV1, PaginationParamsV1, PaginationMetadataV1, AssetV1, BlockchainInfoV1 } from './types';
+import { ChannelV1, ChannelDefinitionV1, ChannelSessionKeyStateV1, StateV1, BalanceEntryV1, TransactionV1, PaginationParamsV1, PaginationMetadataV1, AssetV1, BlockchainInfoV1, AppV1, AppInfoV1, ActionAllowanceV1 } from './types';
 import { AppDefinitionV1, AppStateUpdateV1, AppSessionInfoV1, AppAllocationV1, AppSessionKeyStateV1, SignedAppStateUpdateV1 } from '../app/types';
 import { TransactionType } from '../core/types';
 export interface ChannelsV1GetHomeChannelRequest {
@@ -115,6 +115,7 @@ export interface AppSessionsV1CreateAppSessionRequest {
     definition: AppDefinitionV1;
     session_data: string;
     quorum_sigs?: string[];
+    owner_sig?: string;
 }
 export interface AppSessionsV1CreateAppSessionResponse {
     app_session_id: string;
@@ -143,6 +144,21 @@ export interface AppSessionsV1GetLastKeyStatesRequest {
 export interface AppSessionsV1GetLastKeyStatesResponse {
     states: AppSessionKeyStateV1[];
 }
+export interface AppsV1GetAppsRequest {
+    app_id?: string;
+    owner_wallet?: string;
+    pagination?: PaginationParamsV1;
+}
+export interface AppsV1GetAppsResponse {
+    apps: AppInfoV1[];
+    metadata: PaginationMetadataV1;
+}
+export interface AppsV1SubmitAppVersionRequest {
+    app: AppV1;
+    owner_sig: string;
+}
+export interface AppsV1SubmitAppVersionResponse {
+}
 export interface UserV1GetBalancesRequest {
     wallet: Address;
 }
@@ -161,6 +177,12 @@ export interface UserV1GetTransactionsResponse {
     transactions: TransactionV1[];
     metadata: PaginationMetadataV1;
 }
+export interface UserV1GetActionAllowancesRequest {
+    wallet: Address;
+}
+export interface UserV1GetActionAllowancesResponse {
+    allowances: ActionAllowanceV1[];
+}
 export interface NodeV1PingRequest {
 }
 export interface NodeV1PingResponse {

package/dist/rpc/client.d.ts

@@ -24,8 +24,11 @@ export declare class RPCClient {
     appSessionsV1CloseAppSession(req: API.AppSessionsV1CloseAppSessionRequest, signal?: AbortSignal): Promise<API.AppSessionsV1CloseAppSessionResponse>;
     appSessionsV1SubmitSessionKeyState(req: API.AppSessionsV1SubmitSessionKeyStateRequest, signal?: AbortSignal): Promise<API.AppSessionsV1SubmitSessionKeyStateResponse>;
     appSessionsV1GetLastKeyStates(req: API.AppSessionsV1GetLastKeyStatesRequest, signal?: AbortSignal): Promise<API.AppSessionsV1GetLastKeyStatesResponse>;
+    appsV1GetApps(req: API.AppsV1GetAppsRequest, signal?: AbortSignal): Promise<API.AppsV1GetAppsResponse>;
+    appsV1SubmitAppVersion(req: API.AppsV1SubmitAppVersionRequest, signal?: AbortSignal): Promise<API.AppsV1SubmitAppVersionResponse>;
     userV1GetBalances(req: API.UserV1GetBalancesRequest, signal?: AbortSignal): Promise<API.UserV1GetBalancesResponse>;
     userV1GetTransactions(req: API.UserV1GetTransactionsRequest, signal?: AbortSignal): Promise<API.UserV1GetTransactionsResponse>;
+    userV1GetActionAllowances(req: API.UserV1GetActionAllowancesRequest, signal?: AbortSignal): Promise<API.UserV1GetActionAllowancesResponse>;
     nodeV1Ping(signal?: AbortSignal): Promise<void>;
     nodeV1GetConfig(signal?: AbortSignal): Promise<API.NodeV1GetConfigResponse>;
     nodeV1GetAssets(req: API.NodeV1GetAssetsRequest, signal?: AbortSignal): Promise<API.NodeV1GetAssetsResponse>;

package/dist/rpc/client.js

@@ -72,12 +72,21 @@ export class RPCClient {
     async appSessionsV1GetLastKeyStates(req, signal) {
         return this.call(Methods.AppSessionsV1GetLastKeyStatesMethod, req, signal);
     }
+    async appsV1GetApps(req, signal) {
+        return this.call(Methods.AppsV1GetAppsMethod, req, signal);
+    }
+    async appsV1SubmitAppVersion(req, signal) {
+        return this.call(Methods.AppsV1SubmitAppVersionMethod, req, signal);
+    }
     async userV1GetBalances(req, signal) {
         return this.call(Methods.UserV1GetBalancesMethod, req, signal);
     }
     async userV1GetTransactions(req, signal) {
         return this.call(Methods.UserV1GetTransactionsMethod, req, signal);
     }
+    async userV1GetActionAllowances(req, signal) {
+        return this.call(Methods.UserV1GetActionAllowancesMethod, req, signal);
+    }
     async nodeV1Ping(signal) {
         await this.call(Methods.NodeV1PingMethod, {}, signal);
     }

package/dist/rpc/methods.d.ts

@@ -20,9 +20,13 @@ export declare const AppSessionsV1CreateAppSessionMethod: Method;
 export declare const AppSessionsV1CloseAppSessionMethod: Method;
 export declare const AppSessionsV1SubmitSessionKeyStateMethod: Method;
 export declare const AppSessionsV1GetLastKeyStatesMethod: Method;
+export declare const AppsV1Group: Group;
+export declare const AppsV1GetAppsMethod: Method;
+export declare const AppsV1SubmitAppVersionMethod: Method;
 export declare const UserV1Group: Group;
 export declare const UserV1GetBalancesMethod: Method;
 export declare const UserV1GetTransactionsMethod: Method;
+export declare const UserV1GetActionAllowancesMethod: Method;
 export declare const NodeV1Group: Group;
 export declare const NodeV1PingMethod: Method;
 export declare const NodeV1GetConfigMethod: Method;

package/dist/rpc/methods.js

@@ -18,9 +18,13 @@ export const AppSessionsV1CreateAppSessionMethod = 'app_sessions.v1.create_app_s
 export const AppSessionsV1CloseAppSessionMethod = 'app_sessions.v1.close_app_session';
 export const AppSessionsV1SubmitSessionKeyStateMethod = 'app_sessions.v1.submit_session_key_state';
 export const AppSessionsV1GetLastKeyStatesMethod = 'app_sessions.v1.get_last_key_states';
+export const AppsV1Group = 'apps.v1';
+export const AppsV1GetAppsMethod = 'apps.v1.get_apps';
+export const AppsV1SubmitAppVersionMethod = 'apps.v1.submit_app_version';
 export const UserV1Group = 'user.v1';
 export const UserV1GetBalancesMethod = 'user.v1.get_balances';
 export const UserV1GetTransactionsMethod = 'user.v1.get_transactions';
+export const UserV1GetActionAllowancesMethod = 'user.v1.get_action_allowances';
 export const NodeV1Group = 'node.v1';
 export const NodeV1PingMethod = 'node.v1.ping';
 export const NodeV1GetConfigMethod = 'node.v1.get_config';

package/dist/rpc/types.d.ts

@@ -55,6 +55,17 @@ export interface ChannelSessionKeyStateV1 {
     expires_at: string;
     user_sig: string;
 }
+export interface AppV1 {
+    id: string;
+    owner_wallet: string;
+    metadata: string;
+    version: string;
+    creation_approval_not_required: boolean;
+}
+export interface AppInfoV1 extends AppV1 {
+    created_at: string;
+    updated_at: string;
+}
 export interface AssetV1 {
     name: string;
     symbol: string;
@@ -73,6 +84,7 @@ export interface BlockchainInfoV1 {
     name: string;
     blockchain_id: string;
     channel_hub_address: Address;
+    locking_contract_address?: Address;
 }
 export interface BalanceEntryV1 {
     asset: string;
@@ -93,6 +105,12 @@ export interface PaginationParamsV1 {
     offset?: number;
     limit?: number;
 }
+export interface ActionAllowanceV1 {
+    gated_action: string;
+    time_window: string;
+    allowance: string;
+    used: string;
+}
 export interface PaginationMetadataV1 {
     page: number;
     per_page: number;

package/dist/signers.d.ts

@@ -10,6 +10,8 @@ export interface TransactionSigner {
     signMessage(message: {
         raw: Hex;
     }): Promise<Hex>;
+    signPersonalMessage?(hash: Hex): Promise<Hex>;
+    getAccount?(): ReturnType<typeof privateKeyToAccount>;
 }
 export declare class EthereumMsgSigner implements StateSigner {
     private account;
@@ -25,6 +27,8 @@ export declare class EthereumRawSigner implements TransactionSigner {
     signMessage(message: {
         raw: Hex;
     }): Promise<Hex>;
+    signPersonalMessage(hash: Hex): Promise<Hex>;
+    getAccount(): ReturnType<typeof privateKeyToAccount>;
 }
 export declare class ChannelDefaultSigner implements StateSigner {
     private inner;
@@ -42,6 +46,18 @@ export declare class ChannelSessionKeyStateSigner implements StateSigner {
     getSessionKeyAddress(): Address;
     signMessage(hash: Hex): Promise<Hex>;
 }
+export declare class AppSessionWalletSignerV1 implements StateSigner {
+    private inner;
+    constructor(inner: StateSigner);
+    getAddress(): Address;
+    signMessage(hash: Hex): Promise<Hex>;
+}
+export declare class AppSessionKeySignerV1 implements StateSigner {
+    private inner;
+    constructor(inner: StateSigner);
+    getAddress(): Address;
+    signMessage(hash: Hex): Promise<Hex>;
+}
 export declare function createSigners(privateKey: Hex): {
     stateSigner: StateSigner;
     txSigner: TransactionSigner;

package/dist/signers.js

@@ -36,6 +36,12 @@ export class EthereumRawSigner {
     async signMessage(message) {
         return await this.account.sign({ hash: message.raw });
     }
+    async signPersonalMessage(hash) {
+        return await this.account.signMessage({ message: { raw: hash } });
+    }
+    getAccount() {
+        return this.account;
+    }
 }
 export class ChannelDefaultSigner {
     constructor(inner) {
@@ -87,6 +93,30 @@ export class ChannelSessionKeyStateSigner {
         return `0x01${encoded.slice(2)}`;
     }
 }
+export class AppSessionWalletSignerV1 {
+    constructor(inner) {
+        this.inner = inner;
+    }
+    getAddress() {
+        return this.inner.getAddress();
+    }
+    async signMessage(hash) {
+        const sig = await this.inner.signMessage(hash);
+        return `0xa1${sig.slice(2)}`;
+    }
+}
+export class AppSessionKeySignerV1 {
+    constructor(inner) {
+        this.inner = inner;
+    }
+    getAddress() {
+        return this.inner.getAddress();
+    }
+    async signMessage(hash) {
+        const sig = await this.inner.signMessage(hash);
+        return `0xa2${sig.slice(2)}`;
+    }
+}
 export function createSigners(privateKey) {
     const account = privateKeyToAccount(privateKey);
     return {

package/dist/utils.d.ts

@@ -1,6 +1,6 @@
 import * as core from './core/types';
 import * as API from './rpc/api';
-import { AssetV1, BalanceEntryV1, ChannelV1, LedgerV1, TransitionV1, StateV1, TransactionV1, PaginationMetadataV1 } from './rpc/types';
+import { AssetV1, BalanceEntryV1, ChannelV1, LedgerV1, TransitionV1, StateV1, TransactionV1, PaginationMetadataV1, ActionAllowanceV1 } from './rpc/types';
 export declare function generateNonce(): bigint;
 export declare function transformNodeConfig(resp: API.NodeV1GetConfigResponse): core.NodeConfig;
 export declare function transformAssets(assets: AssetV1[]): core.Asset[];
@@ -11,6 +11,7 @@ export declare function transformTransition(transition: TransitionV1): core.Tran
 export declare function transformState(state: StateV1): core.State;
 export declare function transformTransaction(tx: TransactionV1): core.Transaction;
 export declare function transformPaginationMetadata(metadata: PaginationMetadataV1): core.PaginationMetadata;
+export declare function transformActionAllowance(a: ActionAllowanceV1): core.ActionAllowance;
 import { AppDefinitionV1, AppStateUpdateV1, SignedAppStateUpdateV1, AppSessionInfoV1 } from './app/types';
 export declare function transformAppDefinitionToRPC(def: AppDefinitionV1): any;
 export declare function transformAppStateUpdateToRPC(update: AppStateUpdateV1): {

package/dist/utils.js

@@ -17,6 +17,7 @@ export function transformNodeConfig(resp) {
         name: info.name,
         id: BigInt(info.blockchain_id),
         channelHubAddress: info.channel_hub_address,
+        lockingContractAddress: info.locking_contract_address,
         blockStep: 0n,
     }));
     return {
@@ -164,9 +165,17 @@ export function transformPaginationMetadata(metadata) {
         pageCount: metadata.page_count,
     };
 }
+export function transformActionAllowance(a) {
+    return {
+        gatedAction: a.gated_action,
+        timeWindow: a.time_window,
+        allowance: BigInt(a.allowance),
+        used: BigInt(a.used),
+    };
+}
 export function transformAppDefinitionToRPC(def) {
     return {
-        application: def.application,
+        application_id: def.applicationId,
         participants: def.participants.map(p => ({
             wallet_address: p.walletAddress,
             signature_weight: p.signatureWeight,
@@ -197,15 +206,10 @@ export function transformSignedAppStateUpdateToRPC(signed) {
 export function transformAppSessionInfo(raw) {
     return {
         appSessionId: raw.app_session_id,
+        appDefinition: transformAppDefinitionFromRPC(raw.app_definition),
         isClosed: raw.status === 'closed',
-        participants: (raw.participants || []).map((p) => ({
-            walletAddress: p.wallet_address,
-            signatureWeight: p.signature_weight,
-        })),
         sessionData: raw.session_data || '',
-        quorum: raw.quorum,
         version: BigInt(raw.version),
-        nonce: BigInt(raw.nonce),
         allocations: (raw.allocations || []).map((a) => ({
             participant: a.participant,
             asset: a.asset,
@@ -214,8 +218,11 @@ export function transformAppSessionInfo(raw) {
     };
 }
 export function transformAppDefinitionFromRPC(raw) {
+    if (!raw.application_id || raw.nonce === undefined || raw.nonce === null) {
+        throw new Error('Invalid app definition: missing required fields (application_id, nonce)');
+    }
     return {
-        application: raw.application,
+        applicationId: raw.application_id,
         participants: (raw.participants || []).map((p) => ({
             walletAddress: p.wallet_address,
             signatureWeight: p.signature_weight,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@yellow-org/sdk",
-    "version": "1.1.1",
-    "description": "The Nitrolite SDK empowers developers to build high-performance, scalable web3 applications using state channels. It's designed to provide near-instant transactions and significantly improved user experiences by minimizing direct blockchain interactions.",
+    "version": "1.2.0",
+    "description": "The Yellow SDK empowers developers to build high-performance, scalable web3 applications using state channels. It's designed to provide near-instant transactions and significantly improved user experiences by minimizing direct blockchain interactions.",
     "type": "module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -34,7 +34,6 @@
         "prepublishOnly": "npm run clean && npm run build:prod"
     },
     "keywords": [
-        "erc7824",
         "yellow",
         "yellow-org",
         "statechannels",
@@ -53,7 +52,7 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/erc7824/nitrolite.git"
+        "url": "https://github.com/layer-3/nitrolite.git"
     },
     "engines": {
         "node": ">=20.0.0"