1 files changed, 63 insertions, 0 deletions
diff --git a/taler-wallet.rst b/taler-wallet.rst
index 78daad1a..2ac95df6 100644
--- a/taler-wallet.rst
+++ b/taler-wallet.rst
@@ -86,6 +86,69 @@ APIs and Data Formats
 
   These APIs are still a work in progress and *not* final.
 
+Envelope Format
+---------------
+
+All API responses and notifications are returned in the
+following envelope:
+
+.. ts:def:: WalletCoreResponseEnvelope
+
+   type WalletCoreResponseEnvelope =
+    | WalletCoreSuccess
+    | WalletCoreError
+    | WalletCoreNotification
+
+.. ts:def:: WalletCoreSuccess
+
+   export interface WalletCoreSuccess {
+     type: "response";
+     operation: string,
+     // ID to correlate success response to request
+     id: string;
+     // Result type depends on operation
+     result: unknown;
+   }
+
+.. ts:def:: WalletCoreError
+
+   export interface WalletCoreError {
+     type: "error";
+     operation: string,
+     // ID to correlate success response to request
+     id: string;
+     error: WalletCoreErrorInfo;
+   }
+
+.. ts:def:: WalletCoreNotification
+
+   export interface WalletCoreSuccess {
+     type: "notification";
+
+     // actual type is WalletNotification,
+     // to be documented here
+     payload: any;
+   }
+
+.. ts:def:: WalletCoreErrorInfo
+
+   export interface WalletCoreErrorInfo {
+     // Numeric error code defined defined in the
+     // GANA gnu-taler-error-codes registry.
+     talerErrorCode: number;
+
+     // English description of the error code.
+     talerErrorHint: string;
+
+     // English diagnostic message that can give details
+     // for the instance of the error.
+     message: string;
+
+     // Error details, type depends
+     // on talerErrorCode
+     details: unknown;
+   }
+
 Balances
 --------