From c1ea4001d4f184ac13054dfa73f47e666f12546f Mon Sep 17 00:00:00 2001
From: Daniel Rocha <daniel.rocha@consensys.net>
Date: Fri, 25 Aug 2023 16:36:08 +0200
Subject: [PATCH] feat: add a `redirect` field to asynchronous request
 responses (#75)

This new field should allow snap keyrings that implement the async flow
to redirect users to a dapp to continue the transaction signature. This
is specially useful for MPC keyrings, since they require some
interaction with other participants to sign the transaction.
---
 src/KeyringClient.test.ts |  1 +
 src/api.ts                | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/src/KeyringClient.test.ts b/src/KeyringClient.test.ts
index 2d6bc684f..cde4254b4 100644
--- a/src/KeyringClient.test.ts
+++ b/src/KeyringClient.test.ts
@@ -227,6 +227,7 @@ describe('KeyringClient', () => {
       };
       const expectedResponse: KeyringResponse = {
         pending: true,
+        redirect: null,
       };
 
       mockSender.send.mockResolvedValue(expectedResponse);
diff --git a/src/api.ts b/src/api.ts
index 75bcbab79..086a2d2be 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -8,6 +8,7 @@ import {
   record,
   string,
   union,
+  nullable,
 } from 'superstruct';
 
 import { JsonRpcRequestStruct } from './JsonRpcRequest';
@@ -115,10 +116,37 @@ export type KeyringAccountData = Infer<typeof KeyringAccountDataStruct>;
 
 export const KeyringResponseStruct = union([
   object({
+    /**
+     * Pending flag.
+     *
+     * Setting the pending flag to true indicates that the request will be
+     * handled asynchronously. The keyring must be called with `approveRequest`
+     * or `rejectRequest` to resolve the request.
+     */
     pending: literal(true),
+
+    /**
+     * Redirect URL.
+     *
+     * If present in the response, MetaMask will display a confirmation dialog
+     * with a link to the redirect URL. The user can choose to follow the link
+     * or cancel the request.
+     */
+    redirect: nullable(string()),
   }),
   object({
+    /**
+     * Pending flag.
+     *
+     * Setting the pending flag to false indicates that the request will be
+     * handled synchronously. The keyring must return the result of the
+     * request execution.
+     */
     pending: literal(false),
+
+    /**
+     * Request result.
+     */
     result: JsonStruct,
   }),
 ]);
@@ -129,6 +157,11 @@ export const KeyringResponseStruct = union([
  * Keyring implementations must return a response with `pending: true` if the
  * request will be handled asynchronously. Otherwise, the response must contain
  * the result of the request and `pending: false`.
+ *
+ * In the asynchronous case, the keyring can return a redirect URL to be shown
+ * to the user. The user can choose to follow the link or cancel the request.
+ * The main use case for this is to redirect the user to a third-party service
+ * to approve the request.
  */
 export type KeyringResponse = Infer<typeof KeyringResponseStruct>;