Enhance service verification request/response

Author: ryanberckmans

packages/service/gen/python/threecities/v1/transfer_verification_pb2.py

@@ -8,6 +8,7 @@ message TransferVerificationRequest {
     repeated string token_ticker_allowlist = 3; // allowlist of tokens to permit for a successfully verified transfer. WARNING today, not all supported tokens by 3cities are supported by 3cities on every chain (ie. the matrix of tokens * chains is incomplete), so if a ticker in tokenTickerAllowList is not available on the passed chainId, then any transfers of that token will not be detected and verification will fail as if the transfer never happened
     double usd_per_eth = 4; // ETH price in USD exchange rate to be used when verifying logical asset amounts
     string receiver_address = 5; // receiver address on the passed chainId where transfer being verified is expected to have been sent
+    string external_id = 6; // an optional external ID that may be provided by the client for tracking purposes. Not used by 3cities
   }
 
   message UntrustedData { // from the point of view of the verification client (caller), these data are untrusted and will be verified. Verification will be successful if and only if all these untrusted data are proven to be correct and match/correspond to the trusted data. NB as always, the RPC providers used by verification are assumed to be trustworthy - clients are trusting their RPC providers to facilitate verification
@@ -31,6 +32,8 @@ message TransferVerificationResponse {
   bool is_verified = 1; // true iff the transfer verification was successful
   string description = 2; // description of verification result. Eg. if success, "0.023 ETH sent on Arbitrum One", if failure, "ChainID 3933 is not supported", "Insufficient confirmations, wanted=2, found=1"
   string error = 3; // optional error. Empty string indicates undefined. Always undefined if is_verified
+  string external_id = 4; // an optional external ID that may be provided by the client for tracking purposes. Not used by 3cities
+  bool verification_failed_permanently = 5; // true iff the verification is guaranteed to have failed permanently (eg. due to the transaction having reverted) and should not be retried. Must be ignored if is_verified
 }
 
 service TransferVerificationService {

packages/service/proto/threecities/v1/transfer_verification.proto

@@ -18,11 +18,15 @@ export default (router: ConnectRouter) =>
           wagmiConfig,
           req,
         });
-        return {
+        const resPb: TransferVerificationResponse = new TransferVerificationResponse({
           isVerified: res.isVerified,
           description: res.description,
           ...(res.error && { error: res.error?.message } satisfies Pick<TransferVerificationResponse, 'error'>),
-        };
+          ...(res.externalId && { externalId: res.externalId } satisfies Pick<TransferVerificationResponse, 'externalId'>),
+          ...(res.verificationFailedPermanently && { verificationFailedPermanently: res.verificationFailedPermanently } satisfies Pick<TransferVerificationResponse, 'verificationFailedPermanently'>),
+        });
+        console.info(`req=${reqPb.toJsonString()} resp=${resPb.toJsonString()}`);
+        return resPb;
       }
     },
   });

packages/service/src/connect.ts

@@ -76,6 +76,7 @@ export function transferVerificationRequestFromProto(pb: TransferVerificationReq
     })();
     const req: TransferVerificationRequest = {
       trusted: {
+        ...(pb.trusted.externalId.length > 0 && { externalId: pb.trusted.externalId } satisfies Pick<TransferVerificationRequest['trusted'], 'externalId'>),
         currency,
         logicalAssetAmount,
         tokenTickerAllowlist: pb.trusted.tokenTickerAllowlist,

packages/service/src/fromProto.ts

@@ -90,6 +90,13 @@ export class TransferVerificationRequest_TrustedData extends Message<TransferVer
    */
   receiverAddress = "";
 
+  /**
+   * an optional external ID that may be provided by the client for tracking purposes. Not used by 3cities
+   *
+   * @generated from field: string external_id = 6;
+   */
+  externalId = "";
+
   constructor(data?: PartialMessage<TransferVerificationRequest_TrustedData>) {
     super();
     proto3.util.initPartial(data, this);
@@ -103,6 +110,7 @@ export class TransferVerificationRequest_TrustedData extends Message<TransferVer
     { no: 3, name: "token_ticker_allowlist", kind: "scalar", T: 9 /* ScalarType.STRING */, repeated: true },
     { no: 4, name: "usd_per_eth", kind: "scalar", T: 1 /* ScalarType.DOUBLE */ },
     { no: 5, name: "receiver_address", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 6, name: "external_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
   ]);
 
   static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): TransferVerificationRequest_TrustedData {
@@ -257,6 +265,20 @@ export class TransferVerificationResponse extends Message<TransferVerificationRe
    */
   error = "";
 
+  /**
+   * an optional external ID that may be provided by the client for tracking purposes. Not used by 3cities
+   *
+   * @generated from field: string external_id = 4;
+   */
+  externalId = "";
+
+  /**
+   * true iff the verification is guaranteed to have failed permanently (eg. due to the transaction having reverted) and should not be retried. Must be ignored if is_verified
+   *
+   * @generated from field: bool verification_failed_permanently = 5;
+   */
+  verificationFailedPermanently = false;
+
   constructor(data?: PartialMessage<TransferVerificationResponse>) {
     super();
     proto3.util.initPartial(data, this);
@@ -268,6 +290,8 @@ export class TransferVerificationResponse extends Message<TransferVerificationRe
     { no: 1, name: "is_verified", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
     { no: 2, name: "description", kind: "scalar", T: 9 /* ScalarType.STRING */ },
     { no: 3, name: "error", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 4, name: "external_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 5, name: "verification_failed_permanently", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
   ]);
 
   static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): TransferVerificationResponse {