Set up repo for managing our cross platform plans

README.md

@@ -1,3 +1,22 @@
-# Specifications
+# MetaMask Wallet Specification
+
+This repository is designed to represent the MetaMask wallet in its current state, quirks and platform inconsistencies and all, so that changes may be proposed, and those issues and pull requests may be used to facilitate conversation and process towards the deliberate evolution of the wallet experience across platforms and products, either to consolidate platform differences or emphasize and relish them.
+
+## Specification Principles
+
+### Incremental Completeness
+
+Since the wallet evolved to its current state without this specification existing yet, and is a project in motion, it would be impractical to try to complete this specification before inviting participation in its evolution. For that reason, it should be assumed that at any moment this document is incomplete, and so contributions to this repository should make clear whether they are:
+
+- Clarifications of current state (simply requires verification to merge)
+- Proposals for revisions of state in one or more product (requires completion in the proposed products to merge)
+
+Just to emphasize again, I'm proposing this repository represents _the current state of the wallet, with all of its flaws_, and any changes merged to it should represent those changes being "done" in the wallet itself.
+
+## Contents
+
+- [In-browser API](./api/browser.md)
+- [RPC API](./api/rpc.md)
+- [Mobile Deep Link API](./api/mobile-deep-link.md)
+- [User interface](./ui/index.md)
 
-Specifications that we've developed internally that may be destined to become EIPs, or simply here for everyone's reference.

api/browser.md

@@ -0,0 +1,10 @@
+# MetaMask In Browser API
+
+MetaMask injects an EIP-1193 style provider object into the context of websites the user visits.
+
+On desktop, this API is provided to child iframes as well as any parent frames.
+
+On mobile due to current platform constraints, this API is provided only to the top-level frame, and cannot be relied on in iframes.
+
+The EIP-1193 JavaScript object exposes methods to interact with an [Ethereum JSON-RPC API](./rpc.md).
+

api/mobile-deep-link.md

@@ -0,0 +1,4 @@
+# Mobile Deep Link API
+
+The MetaMask Mobile client allows native apps to initiate any [JSON-RPC API](./rpc.md) method via deep linking, using the below method...
+

api/rpc.md

@@ -0,0 +1,21 @@
+# MetaMask JSON-RPC API
+
+MetaMask exposes methods to untrusted parties like websites to interact with the user's wallet via an Ethereum JSON-RPC API. Some of its methods are simple pass-throughs to the user's current selected Ethereum network node, as defined by the Ethereum JSON-RPC API. Additional methods are provided by the wallet to interact with the user's accounts, including:
+
+- `eth_requestAccounts`: To request access to the user's accounts.
+- `eth_accounts`: Access to the user's accounts.
+- `eth_sendTransaction`: To propose Ethereum transactions to the user.
+- `wallet_watchAssets`: To propose ERC-20 assets to the user's
+- `personal_sign`: To propose human-readable signature challenges to the user.
+- `eth_signTypedData_v3`: To propose the signature of structured data to the user.
+- `eth_signTypedData_v4`: To propose the signature of structured data to the user which can also support recursive structs and null values.
+- `eth_sign`: To propose low-level binary signatures to the user (this method will show the user a hazardous warning and is not recommended for good user experience)
+- `wallet_getEncryptionKey`: (Desktop only) To request a public encryption key from the user that can be used to send them encrypted messages.
+- `wallet_decrypt`: (Desktop only) To propose the user decrypts a message that is intended for their public encryption key. The prompt allows the user to view the message before optionally returning it to the requesting site.
+
+## EIP 2255 Permissions System
+
+On desktop, an invocation of `eth_requestAccounts` will prompt the user to select any number of accounts to expose to the requesting website, and only those selected accounts will be exposed to the website.
+
+On mobile, after a user connected to a website, subsequent calls to `eth_accounts` will return whatever the user's current selected account is, which is whatever account the user has most recently looked at.
+

ui/index.md

@@ -0,0 +1,4 @@
+# Wallet User Interface Specification
+
+Coming soon!
+