add snaps execution environment OpenRPC spec (#23)

* add snaps execution environment OpenRPC spec * fix EE usage to align with spec
MetaMask · Jun 18, 2021 · 6804291 · 6804291
1 parent 0ce2b7d
commit 6804291
Show file tree

Hide file tree

Showing 3 changed files with 190 additions and 7 deletions.
diff --git a/packages/controllers/src/services/WebWorkerExecutionEnvironmentService.ts b/packages/controllers/src/services/WebWorkerExecutionEnvironmentService.ts
@@ -191,7 +191,7 @@ export class WebWorkerExecutionEnvironmentService
 
     const result = await this._command(worker.id, {
       jsonrpc: '2.0',
-      method: 'installPlugin',
+      method: 'executePlugin',
       params: pluginData,
       id: nanoid(),
     });
@@ -252,7 +252,7 @@ export class WebWorkerExecutionEnvironmentService
 
     await this._command(workerId, {
       jsonrpc: '2.0',
-      method: 'ping',
+      method: 'handshake',
       id: nanoid(),
     });
 

diff --git a/packages/workers/execution-environment-openrpc.json b/packages/workers/execution-environment-openrpc.json
@@ -0,0 +1,183 @@
+{
+  "openrpc": "1.2.4",
+  "info": {
+    "title": "MetaMask Snaps Execution Environment API",
+    "version": "0.0.0-development"
+  },
+  "methods": [
+    {
+      "name": "handshake",
+      "description": "confirms that a connection has been established with the execution environment",
+      "params": [],
+      "result": {
+        "name": "HandshakeResult",
+        "schema": {
+          "$ref": "#/components/schemas/OK"
+        }
+      }
+    },
+    {
+      "name": "executePlugin",
+      "description": "executes a plugin in the environment. The plugin can then be interacted with via `pluginRpc`",
+      "paramStructure": "by-name",
+      "params": [
+        {
+          "name": "pluginName",
+          "required": true,
+          "description": "the name of the plugin",
+          "schema": {
+            "title": "PluginName",
+            "type": "string"
+          }
+        },
+        {
+          "name": "sourceCode",
+          "description": "a plugins source code that gets executed in the environment",
+          "required": true,
+          "schema": {
+            "title": "SourceCode",
+            "type": "string"
+          }
+        }
+      ],
+      "result": {
+        "name": "executePluginResult",
+        "schema": {
+          "$ref": "#/components/schemas/OK"
+        }
+      },
+      "examples": [
+        {
+          "name": "BasicTestPluginExecuteExample",
+          "params": [
+            {
+              "name": "pluginName",
+              "value": "TestPlugin"
+            },
+            {
+              "name": "sourceCode",
+              "value": "wallet.registerRpcMessageHandler(async (_, request) => { return request.method + request.id })"
+            }
+          ],
+          "result": {
+            "name": "BasicTestPluginExampleResult",
+            "value": "OK"
+          }
+        }
+      ]
+    },
+    {
+      "name": "pluginRpc",
+      "paramStructure": "by-name",
+      "params": [
+        {
+          "name": "target",
+          "required": true,
+          "description": "the name of the plugin method",
+          "schema": {
+            "title": "Target",
+            "type": "string"
+          }
+        },
+        {
+          "name": "origin",
+          "required": true,
+          "description": "Origin of the plugin JSON-RPC request",
+          "schema": {
+            "title": "Origin",
+            "type": "string"
+          }
+        },
+        {
+          "name": "request",
+          "required": true,
+          "description": "JSON-RPC request",
+          "schema": {
+            "title": "JSONRPCRequest",
+            "description": "JSON-RPC request object to pass through to the plugin",
+            "type": "object",
+            "required": ["method", "params"],
+            "properties": {
+              "jsonrpc": {
+                "title": "JSONRPCString",
+                "type": "string",
+                "const": "2.0"
+              },
+              "id": {
+                "title": "JSONRPCID",
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ]
+              },
+              "method": {
+                "title": "JSONRPCMethod",
+                "description": "the name of the method",
+                "type": "string"
+              },
+              "params": {
+                "title": "JSONRPCParams",
+                "type": ["array", "object"]
+              }
+            }
+          }
+        }
+      ],
+      "result": {
+        "name": "HandlePluginRpcResult",
+        "schema": {
+          "title": "PluginRpcResult",
+          "type": "object",
+          "properties": {
+            "result": true,
+            "error": true
+          }
+        }
+      },
+      "examples": [
+        {
+          "name": "TestPluginExample",
+          "params": [
+            {
+              "name": "target",
+              "value": "TestPlugin"
+            },
+            {
+              "name": "origin",
+              "value": "foo.com"
+            },
+            {
+              "name": "request",
+              "value": {
+                "method": "hello",
+                "params": [],
+                "id": 1
+              }
+            }
+          ],
+          "result": {
+            "name": "TestPluginResultExample",
+            "value": {
+              "jsonrpc": "2.0",
+              "id": 1,
+              "result": "hello1"
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "components": {
+    "schemas": {
+      "OK": {
+        "title": "OK",
+        "type": "string",
+        "const": "OK"
+      }
+    }
+  }
+}
diff --git a/packages/workers/src/PluginWorker.ts b/packages/workers/src/PluginWorker.ts
@@ -94,11 +94,11 @@ lockdown({
       }
 
       switch (method) {
-        case 'installPlugin':
-          this.installPlugin(id, (params as unknown) as PluginData);
+        case 'executePlugin':
+          this.executePlugin(id, (params as unknown) as PluginData);
           break;
 
-        case 'ping':
+        case 'handshake':
           this.respond(id, { result: 'OK' });
           break;
 
@@ -146,13 +146,13 @@ lockdown({
       }
     }
 
-    private installPlugin(
+    private executePlugin(
       id: JsonRpcId,
       { pluginName, sourceCode }: Partial<PluginData> = {},
     ) {
       if (!isTruthyString(pluginName) || !isTruthyString(sourceCode)) {
         this.respond(id, {
-          error: new Error('Invalid installPlugin parameters.'),
+          error: new Error('Invalid executePlugin parameters.'),
         });
         return;
       }