Add instructions to setup extra context api (#4)

LayerZero-Labs · Sep 26, 2024 · de7ec15 · de7ec15
1 parent 3fc2052
commit de7ec15
Show file tree

Hide file tree

Showing 5 changed files with 78 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -41,6 +41,7 @@ export class GasolinaCdkStack extends LZCdkStack {
             availableChainNames: config.availableChainNames,
             signerType: config.signerType,
             kmsNumOfSigners: config.kmsNumOfSigners,
+            extraContextRequestUrl: config.extraContextRequestUrl,
         })
     }
 }