TON 359: new intent api design

packages/walletkit-android-bridge/src/api/eventListeners.ts

@@ -12,18 +12,36 @@ import type {
     RequestErrorEvent,
     SendTransactionRequestEvent,
     SignDataRequestEvent,
+    IntentRequestEvent,
+    BatchedIntentEvent,
 } from '@ton/walletkit';
 
-type ConnectEventListener = ((event: ConnectionRequestEvent) => void) | null;
-type TransactionEventListener = ((event: SendTransactionRequestEvent) => void) | null;
-type SignDataEventListener = ((event: SignDataRequestEvent) => void) | null;
-type DisconnectEventListener = ((event: DisconnectionEvent) => void) | null;
-type ErrorEventListener = ((event: RequestErrorEvent) => void) | null;
+/**
+ * Shared event listener references used to manage WalletKit callbacks.
+ */
+export type ConnectEventListener = ((event: ConnectionRequestEvent) => void) | null;
+export type TransactionEventListener = ((event: SendTransactionRequestEvent) => void) | null;
+export type SignDataEventListener = ((event: SignDataRequestEvent) => void) | null;
+export type DisconnectEventListener = ((event: DisconnectionEvent) => void) | null;
+export type ErrorEventListener = ((event: RequestErrorEvent) => void) | null;
+export type IntentEventListener = ((event: IntentRequestEvent | BatchedIntentEvent) => void) | null;
+
+/**
+ * Union type for all bridge event listeners.
+ */
+export type BridgeEventListener =
+    | ConnectEventListener
+    | TransactionEventListener
+    | SignDataEventListener
+    | DisconnectEventListener
+    | ErrorEventListener
+    | IntentEventListener;
 
 export const eventListeners = {
     onConnectListener: null as ConnectEventListener,
     onTransactionListener: null as TransactionEventListener,
     onSignDataListener: null as SignDataEventListener,
     onDisconnectListener: null as DisconnectEventListener,
     onErrorListener: null as ErrorEventListener,
+    onIntentListener: null as IntentEventListener,
 };

packages/walletkit-android-bridge/src/api/index.ts

@@ -19,6 +19,7 @@ import * as tonconnect from './tonconnect';
 import * as nft from './nft';
 import * as jettons from './jettons';
 import * as browser from './browser';
+import * as intents from './intents';
 import { eventListeners } from './eventListeners';
 
 export { eventListeners };
@@ -90,4 +91,14 @@ export const api: WalletKitBridgeApi = {
     emitBrowserPageFinished: browser.emitBrowserPageFinished,
     emitBrowserError: browser.emitBrowserError,
     emitBrowserBridgeRequest: browser.emitBrowserBridgeRequest,
+
+    // Intents
+    isIntentUrl: intents.isIntentUrl,
+    handleIntentUrl: intents.handleIntentUrl,
+    approveTransactionDraft: intents.approveTransactionDraft,
+    approveSignDataIntent: intents.approveSignDataIntent,
+    approveActionDraft: intents.approveActionDraft,
+    approveBatchedIntent: intents.approveBatchedIntent,
+    rejectIntent: intents.rejectIntent,
+    intentItemsToTransactionRequest: intents.intentItemsToTransactionRequest,
 } as unknown as WalletKitBridgeApi;

packages/walletkit-android-bridge/src/api/initialization.ts

@@ -18,6 +18,8 @@ import type {
     RequestErrorEvent,
     SendTransactionRequestEvent,
     SignDataRequestEvent,
+    IntentRequestEvent,
+    BatchedIntentEvent,
 } from '@ton/walletkit';
 
 import type { WalletKitBridgeInitConfig, SetEventsListenersArgs, WalletKitBridgeEventCallback } from '../types';
@@ -105,6 +107,17 @@ export async function setEventsListeners(args?: SetEventsListenersArgs): Promise
 
     kit.onRequestError(eventListeners.onErrorListener);
 
+    // Register intent listener
+    if (eventListeners.onIntentListener) {
+        kit.removeIntentRequestCallback(eventListeners.onIntentListener);
+    }
+
+    eventListeners.onIntentListener = (event: IntentRequestEvent | BatchedIntentEvent) => {
+        callback('intentRequest', event);
+    };
+
+    kit.onIntentRequest(eventListeners.onIntentListener);
+
     return { ok: true };
 }
 
@@ -139,5 +152,10 @@ export async function removeEventListeners(): Promise<{ ok: true }> {
         eventListeners.onErrorListener = null;
     }
 
+    if (eventListeners.onIntentListener) {
+        kit.removeIntentRequestCallback(eventListeners.onIntentListener);
+        eventListeners.onIntentListener = null;
+    }
+
     return { ok: true };
 }

packages/walletkit-android-bridge/src/api/intents.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * intents.ts – Bridge API for intent operations
+ */
+
+import { kit } from '../utils/bridge';
+
+export async function isIntentUrl(args: unknown[]) {
+    return kit('isIntentUrl', ...args);
+}
+
+export async function handleIntentUrl(args: unknown[]) {
+    return kit('handleIntentUrl', ...args);
+}
+
+export async function approveTransactionDraft(args: unknown[]) {
+    return kit('approveTransactionDraft', ...args);
+}
+
+export async function approveSignDataIntent(args: unknown[]) {
+    return kit('approveSignDataIntent', ...args);
+}
+
+export async function approveActionDraft(args: unknown[]) {
+    return kit('approveActionDraft', ...args);
+}
+
+export async function approveBatchedIntent(args: unknown[]) {
+    return kit('approveBatchedIntent', ...args);
+}
+
+export async function rejectIntent(args: unknown[]) {
+    return kit('rejectIntent', ...args);
+}
+
+export async function intentItemsToTransactionRequest(args: unknown[]) {
+    return kit('intentItemsToTransactionRequest', ...args);
+}

packages/walletkit-android-bridge/src/types/api.ts

@@ -24,6 +24,15 @@ import type {
     TransactionRequest,
     Wallet,
     WalletResponse,
+    IntentRequestEvent,
+    BatchedIntentEvent,
+    TransactionIntentRequestEvent,
+    SignDataIntentRequestEvent,
+    ActionIntentRequestEvent,
+    IntentTransactionResponse,
+    IntentSignDataResponse,
+    IntentErrorResponse,
+    IntentActionItem,
 } from '@ton/walletkit';
 
 /**
@@ -265,6 +274,56 @@ export interface HandleTonConnectUrlArgs {
     url: string;
 }
 
+// === Intent Args ===
+
+export interface HandleIntentUrlArgs {
+    url: string;
+    walletId: string;
+}
+
+export interface IsIntentUrlArgs {
+    url: string;
+}
+
+export interface ApproveTransactionDraftArgs {
+    event: TransactionIntentRequestEvent;
+    walletId: string;
+}
+
+export interface ApproveSignDataDraftArgs {
+    event: SignDataIntentRequestEvent;
+    walletId: string;
+}
+
+export interface ApproveActionDraftArgs {
+    event: ActionIntentRequestEvent;
+    walletId: string;
+}
+
+export interface ApproveBatchedIntentArgs {
+    batch: BatchedIntentEvent;
+    walletId: string;
+}
+
+export interface RejectIntentArgs {
+    event: IntentRequestEvent | BatchedIntentEvent;
+    reason?: string;
+    errorCode?: number;
+}
+
+export interface IntentItemsToTransactionRequestArgs {
+    items: IntentActionItem[];
+    walletId: string;
+}
+
+export interface WalletDescriptor {
+    address: string;
+    publicKey: string;
+    version: string;
+    index: number;
+    network: string;
+}
+
 export interface WalletKitBridgeApi {
     init(config?: WalletKitBridgeInitConfig): PromiseOrValue<{ ok: true }>;
     setEventsListeners(args?: SetEventsListenersArgs): PromiseOrValue<{ ok: true }>;
@@ -317,4 +376,17 @@ export interface WalletKitBridgeApi {
     emitBrowserPageFinished(args: EmitBrowserPageArgs): PromiseOrValue<{ success: boolean }>;
     emitBrowserError(args: EmitBrowserErrorArgs): PromiseOrValue<{ success: boolean }>;
     emitBrowserBridgeRequest(args: EmitBrowserBridgeRequestArgs): PromiseOrValue<{ success: boolean }>;
+    // Intent API
+    isIntentUrl(args: IsIntentUrlArgs): PromiseOrValue<boolean>;
+    handleIntentUrl(args: HandleIntentUrlArgs): PromiseOrValue<void>;
+    approveTransactionDraft(args: ApproveTransactionDraftArgs): PromiseOrValue<IntentTransactionResponse>;
+    approveSignDataIntent(args: ApproveSignDataDraftArgs): PromiseOrValue<IntentSignDataResponse>;
+    approveActionDraft(
+        args: ApproveActionDraftArgs,
+    ): PromiseOrValue<IntentTransactionResponse | IntentSignDataResponse>;
+    approveBatchedIntent(
+        args: ApproveBatchedIntentArgs,
+    ): PromiseOrValue<IntentTransactionResponse | IntentSignDataResponse>;
+    rejectIntent(args: RejectIntentArgs): PromiseOrValue<IntentErrorResponse>;
+    intentItemsToTransactionRequest(args: IntentItemsToTransactionRequestArgs): PromiseOrValue<TransactionRequest>;
 }

packages/walletkit-android-bridge/src/types/events.ts

@@ -16,6 +16,7 @@ export type WalletKitBridgeEventType =
     | 'signDataRequest'
     | 'disconnect'
     | 'requestError'
+    | 'intentRequest'
     | 'browserPageStarted'
     | 'browserPageFinished'
     | 'browserError'

packages/walletkit-android-bridge/src/types/walletkit.ts

@@ -8,19 +8,28 @@
 
 import type {
     ApiClient,
+    BatchedIntentEvent,
     BridgeEventMessageInfo,
     ConnectionApprovalResponse,
     ConnectionRequestEvent,
     DeviceInfo,
     DisconnectionEvent,
     InjectedToExtensionBridgeRequestPayload,
+    IntentActionItem,
+    IntentErrorResponse,
+    IntentRequestEvent,
+    IntentSignDataResponse,
+    IntentTransactionResponse,
+    ActionIntentRequestEvent,
     Network,
     RequestErrorEvent,
     SendTransactionApprovalResponse,
     SendTransactionRequestEvent,
     SignDataApprovalResponse,
+    SignDataIntentRequestEvent,
     SignDataRequestEvent,
     TONConnectSession,
+    TransactionIntentRequestEvent,
     TransactionRequest,
     Wallet,
     WalletAdapter,
@@ -116,4 +125,25 @@ export interface WalletKitInstance {
         event: SignDataRequestEvent,
         reason?: string | SendTransactionRpcResponseError['error'],
     ): Promise<void>;
+    // Intent API
+    isIntentUrl(url: string): boolean;
+    handleIntentUrl(url: string, walletId: string): Promise<void>;
+    onIntentRequest(cb: (event: IntentRequestEvent | BatchedIntentEvent) => void): void;
+    removeIntentRequestCallback(cb: (event: IntentRequestEvent | BatchedIntentEvent) => void): void;
+    approveTransactionDraft(event: TransactionIntentRequestEvent, walletId: string): Promise<IntentTransactionResponse>;
+    approveSignDataIntent(event: SignDataIntentRequestEvent, walletId: string): Promise<IntentSignDataResponse>;
+    approveActionDraft(
+        event: ActionIntentRequestEvent,
+        walletId: string,
+    ): Promise<IntentTransactionResponse | IntentSignDataResponse>;
+    approveBatchedIntent(
+        batch: BatchedIntentEvent,
+        walletId: string,
+    ): Promise<IntentTransactionResponse | IntentSignDataResponse>;
+    rejectIntent(
+        event: IntentRequestEvent | BatchedIntentEvent,
+        reason?: string,
+        errorCode?: number,
+    ): Promise<IntentErrorResponse>;
+    intentItemsToTransactionRequest(items: IntentActionItem[], walletId: string): Promise<TransactionRequest>;
 }

packages/walletkit/src/api/interfaces/WalletAdapter.ts

@@ -40,7 +40,9 @@ export interface WalletAdapter {
     getSignedSendTransaction(
         input: TransactionRequest,
         options?: {
-            fakeSignature: boolean;
+            fakeSignature?: boolean;
+            /** Use internal message opcode (0x73696e74) instead of external (0x7369676e) for gasless relaying */
+            internal?: boolean;
         },
     ): Promise<Base64String>;
     getSignedSignData(

packages/walletkit/src/api/models/bridge/SignMessageApprovalResponse.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { Base64String } from '../core/Primitives';
+
+/**
+ * Response after user approves a sign-message request.
+ */
+export interface SignMessageApprovalResponse {
+    /**
+     * Signed internal message BoC (Bag of Cells) format, encoded in Base64.
+     * This is a signed internal message (internal opcode) that the dApp can relay via a third-party relayer.
+     */
+    internalBoc: Base64String;
+}

packages/walletkit/src/api/models/bridge/SignMessageRequestEvent.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { TransactionRequest } from '../transactions/TransactionRequest';
+import type { BridgeEvent } from './BridgeEvent';
+
+/**
+ * Event containing a sign-message (sign-only transaction) request from a dApp via TON Connect.
+ * The wallet signs the transaction using the internal opcode and returns the signed BoC
+ * without broadcasting it on-chain.
+ */
+export interface SignMessageRequestEvent extends BridgeEvent {
+    /**
+     * Raw transaction request data
+     */
+    request: TransactionRequest;
+}

packages/walletkit/src/api/models/index.ts

@@ -50,6 +50,8 @@ export type {
     SendTransactionRequestEvent,
     SendTransactionRequestEventPreview,
 } from './bridge/SendTransactionRequestEvent';
+export type { SignMessageApprovalResponse } from './bridge/SignMessageApprovalResponse';
+export type { SignMessageRequestEvent } from './bridge/SignMessageRequestEvent';
 export type { RequestErrorEvent } from './bridge/RequestErrorEvent';
 export type { TONConnectSession } from './sessions/TONConnectSession';
 
@@ -106,6 +108,27 @@ export type {
     TransactionTraceMoneyFlowItem,
 } from './transactions/TransactionTraceMoneyFlow';
 
+// Intent models
+export type { SendTonAction, SendJettonAction, SendNftAction, IntentActionItem } from './intents/IntentActionItem';
+export type {
+    IntentOrigin,
+    IntentDeliveryMode,
+    IntentRequestBase,
+    TransactionIntentRequestEvent,
+    SignDataIntentRequestEvent,
+    ActionIntentRequestEvent,
+    ConnectIntentRequestEvent,
+    IntentRequestEvent,
+} from './intents/IntentRequestEvent';
+export type {
+    IntentTransactionResponse,
+    IntentSignDataResponse,
+    IntentErrorResponse,
+    IntentError,
+    IntentResponseResult,
+} from './intents/IntentResponse';
+export type { BatchedIntentEvent } from './intents/BatchedIntentEvent';
+
 // RPC models
 export type { GetMethodResult } from './rpc/GetMethodResult';