Merge remote-tracking branch 'refs/remotes/origin/main'

GRIDS.md

@@ -1,12 +1,11 @@
-
 # GRIDS: Gajumaru Remote Instruction Dispatch System v1
 
 - **Document Created**: 2025-01-17
-- **Document Last Modified**: 2025-12-08
+- **Document Last Modified**: 2026-05-13
 - **Document Author**: Craig Everett `<craigeverett@qpq.swiss>`
-- **Document Version**: 3 (For Implementation)
+- **Document Version**: 5 (For Implementation)
 - **Wiki Page Created**: 2026-05-02
-- **Wiki Page Last Modified**: 2026-05-02
+- **Wiki Page Last Modified**: 2026-05-13
 - **Wiki Page Author**: Peter Harpending `<peterharpending@qpq.swiss>`
 - **Notes**: Copied from random PDF I (PRH) found on my computer written by
   Craig, dated 2025-01-17.
@@ -27,39 +26,24 @@ Gajumaru ecosystem:
 
 ## The Problem
 
-In computing there is a strong tradeoff between usability and security. In the
+In computing there is a strong tradeoff between usability and security.
-cryptocurrency world this is compounded by the inherent complexity of the
+In the cryptocurrency world this is compounded by the inherent complexity of the systems involved.
-systems involved. This has resulted in a common pattern of developers coding
+This has resulted in a common pattern of developers coding wallet features directly into the local execution environments of the applications they wish to integrate with a cryptocurrency system (typically a blockchain).
-wallet features directly into the local execution environments of the
-applications they wish to integrate with a cryptocurrency system (typically a
-blockchain).
 
-For example, it is common for games based around on-chain tokens to integrate
+For example, it is common for games based around on-chain tokens to integrate wallet features directly into the game client itself.
-wallet features directly into the game client itself. This prevents the user
+This prevents the user from having to leave the game, open another application (their wallet), sign a transaction, and then return to the game.
-from having to leave the game, open another application (their wallet), sign a
-transaction, and then return to the game.
 
-As another example, it is overwhelmingly common for developers to write
+As another example, it is overwhelmingly common for developers to write wallets as browser plugins that interact directly with in-page applications running in the same browser.
-wallets as browser plugins that interact directly with in-page applications
-running in the same browser.
 
-In both cases the incentives for bad actors to compromise the execution
+In both cases the incentives for bad actors to compromise the execution environment itself in order to capture private key data or seed phrases is overwhelming.
-environment itself in order to capture private key data or seed phrases is
+Separation of signature and app execution context is needed.
-overwhelming. Separation of signature and app execution context is needed.
+Separating the execution context requires a way for apps requesting signatures and apps capable of providing signatures to communicate not only across execution environments on a single system, but also across completely separate systems.
-Separating the execution context requires a way for apps requesting signatures
-and apps capable of providing signatures to communicate not only across
-execution environments on a single system, but also across completely separate
-systems.
 
-GRIDS defines a way to to combine communication of limited, known transaction
+GRIDS defines a way to to combine communication of limited, known transaction types (such as simple spends) with a way to convey arbitrarily complex transaction data that may require out-of-band communication with a signature client.
-types (such as simple spends) with a way to convey arbitrarily complex
-transaction data that may require out-of-band communication with a signature
-client.
 
 ## The Schema
 
-The GRIDS schema is very similar to HTTP/HTTPS, and even translates directly
+The GRIDS schema is very similar to HTTP/HTTPS, and even translates directly to an HTTP request URL in the case of a dead-drop instruction.
-to an HTTP request URL in the case of a dead-drop instruction.
 
 The basic schema is:
 
@@ -220,28 +204,25 @@ The response to the initial GET request takes the form of a JSON object with thi
 - The `"network_id"` is necessary for the client (and end-user) to verify that
   activity is occurring where expected and binds the resulting signature to
   that specific network.
-- The `"type"` may be `"message"`, `"tx"` or `"ack"`. A `"message"` signature
+- The `"type"` may be `"message"`, `"binary"`, `"tx"` or `"ack"`.
-  is used either for verifiable messages or login schemes. An `"ack"` is an
+  - A `"message"` signature is a UTF-8 string used either for verifiable messages or login schemes.
-  optional response to a `"tx"` or `"message"` response POST.
+  - A `"binary"` signature is the same as a `"message"` signature, but is performed over binary data encoded as base64.
-- The `"public_id"` can either be a public key (on-chain account) or the
+  - A `"tx"` is a request for signature of a transaction (usually call data or contract deployment).
-  **boolean** `false` (note absence of quotes).
+  - An `"ack"` is an optional response to a `"tx"` or `"message"` response POST.
-
+- The `"public_id"` can either be a public key (on-chain account) or the **boolean** `false` (note absence of quotes).
   - If the `public_id` is `false`, then it is up to the client to pick a key to
     use (and then populate this field).
   - If an ID is specified, then the client should select that account or fail if it is not available.
-
 - The `"payload"` is the data to be signed. In the case of a
-  `"tx"` request (a contract call, for example), this data
+  `"tx"` request (a contract call, for example), this data will be transaction data encoded according to the Gajumaru
-  will be transaction data encoded according to the Gajumaru
+  protocol's rules. Any Gajumaru signature routine will understand how to interpret and handle this data.
-  protocol's rules. Any Gajumaru signature routine will
+  Each signature context has its own requirements:
-  understand how to interpret and handle this data. In the
+  - `"tx"` signatures must be handled according to the Gajumaru protocol rules for transaction signatures.
-  case of a `"message"` request, this will typically be a
+  - `"message"`signatures are for simple UTF8 strings in plain text that the client interprets as a binary string.
-  simple string in plain text that the client interprets as a
+    The binary string `<<"Gajumaru Signed Message:\n">>` is prepended to the message text before the signature is performed.
-  binary string, appends the prefix (Erlang binary notation)
+    Prefixing message request payloads with this string prevents attackers from disguising transaction signature requests as text message signatures.
-  `<<"Gajumaru Signed Message:\n">>`, and then signs.
+  - `"binary"` signatures are for data encoded in base64.
-  Prefixing message request payloads with this string prevents
+    The contents are first decoded from base64, then the binary prefix `<<"Gajumaru Signed Binary:">>` is prepended to the binary data before the signature is performed.
-  attackers from disguising transaction signature requests as
-  text message signatures.
 
 ### Signed Data Messages (subsequent POST)