From de7ec1537a106effefc8b9f10464b613646591f8 Mon Sep 17 00:00:00 2001
From: siddharth <sid@siddharthks.com>
Date: Thu, 26 Sep 2024 14:21:56 -0700
Subject: [PATCH] Add instructions to setup extra context api (#4)

---
 README.md                                    | 67 ++++++++++++++++++++
 cdk/gasolina/config/index.ts                 |  2 +
 cdk/gasolina/constants/envVariables/index.ts |  1 +
 cdk/gasolina/lib/gasolinaApi.ts              |  7 ++
 cdk/gasolina/lib/gasolinaCdkStack.ts         |  1 +
 5 files changed, 78 insertions(+)

diff --git a/README.md b/README.md
index 17ae8f0..02d24d2 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,73 @@ cdk bootstrap
         -   Configure the `address` of the signer
         -   Configure the `secretName` of that signer. This is used by the application to fetch the mnemonics when it needs to sign the payload
 
+### [Optional] Setup Extra Context Verification
+
+You can enhance message verification by adding your own custom rules.
+
+To implement this, setup an API that would be called by gasolina whenever a message is received. The API will receive the complete context of the message, including additional onchain data, and will return a boolean value indicating whether the message can be signed.
+
+API Input:
+
+```typescript
+{
+    sentEvent: { // PacketSent event, emitted from the Endpoint contract
+        lzMessageId: {
+            pathwayId: {
+                srcEid: number // Soure chain eid (https://github.com/LayerZero-Labs/LayerZero-v2/blob/main/packages/layerzero-v2/evm/protocol/contracts/EndpointV2.sol#L23)
+                dstEid: number
+                sender: string // Sender oapp address on source chain
+                receiver: string // Receiver oapp address on destination chain
+                srcChainName: string // Source Chain Name
+                dstChainName: string // Destination Chain Name
+            }
+            nonce: number
+            ulnSendVersion: UlnVersion
+        }
+        guid: string // onchain guid
+        message: string
+        options: {
+            // Adapter Params set on the source transaction
+            lzReceive?: {
+                gas: string
+                value: string
+            }
+            nativeDrop?: {
+                amount: string
+                receiver: string
+            }[]
+            compose?: {
+                index: number
+                gas: string
+                value: string
+            }[]
+            ordered?: boolean
+        }
+        payload?: string
+        sendLibrary?: string
+        onChainEvent: { // Transaction on the source chain
+            chainName: string
+            txHash: string
+            blockHash: string
+            blockNumber: number
+        }
+    }
+    from: string // Address of the sender
+    blockConfirmation: number
+    expiration: number
+    ulnVersion: UlnVersion
+}
+```
+
+API Output:
+
+-   The API is expected to return a boolean value indicating whether the message can be signed.
+
+Setup:
+
+-   In `cdk/gasolina/config/index.ts` in the CONFIG object:
+    -   Set `extraContextGasolinaUrl` to the URL of your API
+
 ### 4. CDK Deploy
 
 Setup infrastructure and deploy the Gasolina application.
diff --git a/cdk/gasolina/config/index.ts b/cdk/gasolina/config/index.ts
index 21b37e5..1a09311 100644
--- a/cdk/gasolina/config/index.ts
+++ b/cdk/gasolina/config/index.ts
@@ -7,6 +7,7 @@ export const CONFIG: {
         availableChainNames: string
         signerType: string
         kmsNumOfSigners?: number
+        extraContextRequestUrl?: string
     }
 } = {
     // EDIT: aws account number
@@ -19,5 +20,6 @@ export const CONFIG: {
             'ethereum,bsc,avalanche,polygon,arbitrum,optimism,fantom', // EDIT: all the chains gasolina will support that matches those listed in providers
         signerType: 'MNEMONIC', // EDIT: MNEMONIC or KMS
         // kmsNumOfSigners: 1, // EDIT: only required if signerType is KMS
+        // extraContextRequestUrl: undefined // EDIT: optional
     },
 }
diff --git a/cdk/gasolina/constants/envVariables/index.ts b/cdk/gasolina/constants/envVariables/index.ts
index 597bdb3..0d68dc3 100644
--- a/cdk/gasolina/constants/envVariables/index.ts
+++ b/cdk/gasolina/constants/envVariables/index.ts
@@ -10,4 +10,5 @@ export const ENV_VAR_NAMES = {
     LZ_AVAILABLE_CHAIN_NAMES: 'LAYERZERO_AVAILABLE_CHAIN_NAMES',
     LZ_KMS_CLOUD_TYPE: 'KMS_CLOUD_TYPE',
     LZ_KMS_IDS: 'LAYERZERO_KMS_IDS',
+    LZ_EXTRA_CONTEXT_REQUEST_URL: 'EXTRA_CONTEXT_REQUEST_URL',
 }
diff --git a/cdk/gasolina/lib/gasolinaApi.ts b/cdk/gasolina/lib/gasolinaApi.ts
index 0628892..0baf2f6 100644
--- a/cdk/gasolina/lib/gasolinaApi.ts
+++ b/cdk/gasolina/lib/gasolinaApi.ts
@@ -41,6 +41,7 @@ interface CreateGasolinaServiceProps {
     appVersion: string
     availableChainNames: string
     kmsNumOfSigners?: number
+    extraContextRequestUrl?: string
 }
 
 export const createGasolinaService = (props: CreateGasolinaServiceProps) => {
@@ -149,6 +150,12 @@ export const createGasolinaService = (props: CreateGasolinaServiceProps) => {
                           .join(','),
                   }
                 : {}),
+            ...(props.extraContextRequestUrl
+                ? {
+                      [ENV_VAR_NAMES.LZ_EXTRA_CONTEXT_REQUEST_URL]:
+                          props.extraContextRequestUrl,
+                  }
+                : {}),
         },
         scaleOnNetwork: true,
     })
diff --git a/cdk/gasolina/lib/gasolinaCdkStack.ts b/cdk/gasolina/lib/gasolinaCdkStack.ts
index ac8368e..bf7134c 100644
--- a/cdk/gasolina/lib/gasolinaCdkStack.ts
+++ b/cdk/gasolina/lib/gasolinaCdkStack.ts
@@ -41,6 +41,7 @@ export class GasolinaCdkStack extends LZCdkStack {
             availableChainNames: config.availableChainNames,
             signerType: config.signerType,
             kmsNumOfSigners: config.kmsNumOfSigners,
+            extraContextRequestUrl: config.extraContextRequestUrl,
         })
     }
 }