From 5ebdf9dc2ef40e5da3e138919ac5790286d9d07a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Friedger=20M=C3=BCffke?= Date: Thu, 20 Jan 2022 16:00:07 +0100 Subject: [PATCH 1/3] initial draft --- sips/sip-x/sip-wallet-protocol.md | 84 +++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 sips/sip-x/sip-wallet-protocol.md diff --git a/sips/sip-x/sip-wallet-protocol.md b/sips/sip-x/sip-wallet-protocol.md new file mode 100644 index 00000000..f3ee10e4 --- /dev/null +++ b/sips/sip-x/sip-wallet-protocol.md @@ -0,0 +1,84 @@ + +# Preamble + +SIP Number: X + +Title: Specification of the Wallet Protcol + +Author: Friedger Müffke (mail@friedger.de) + +Consideration: Technical + +Type: Standard + +Status: Draft + +Created: 20 January 2022 + +License: CC0-1.0 + +Sign-off: + +# Abstract + +Decentralized application do not handle private keys of users. Instead users have wallets that manage private keys, authentication, message signing etc. This SIP specifies a ways to exchange messages between applications and wallets and how to agree on one. + +# License and Copyright + +This SIP is made available under the terms of the Creative Commons CC0 1.0 Universal license, available at https://creativecommons.org/publicdomain/zero/1.0/ +This SIP’s copyright is held by the Stacks Open Internet Foundation. + +# Introduction + +Decentralized application do not want to store credentials of their users. Instead users use a trusted wallet that manages the user's private keys savely. Therefore, applications needs a way to communicate with the user's wallet e.g. for requesting signatured of a transaction, authentication or message signing. + +Different transport protocols for exchanging messages between applications and wallets have been established in the web3 ecosystem. In the following sections the transport protocols are described and a standardized way how to agree on a transport protocol is defined. + +# Specification + +## Transport Protocols + +The communication between application and authenticator can happen in various ways. The subsections below define common transport protocols. + +### Stacks Provider + +Stacks Provider is a common interface used for web applications to communicate with the authenticator via a browser extension. + +It provides functions to handle + +1. authentication +2. transaction signing + +https://github.com/hirosystems/connect/blob/main/packages/connect/src/types/provider.ts + +The function `authenticationRequest` expects the JWT of the authentication request as parameter and must return the authentication response as encoded JWT. + +This transport protocol is implemented by the [Hiro Wallet web extension](https://github.com/blockstack/stacks-wallet-web/). Examples for client libraries are [Connect](https://github.com/blockstack/connect) and [Micro Stacks](https://github.com/fungible-systems/micro-stacks). + +### HTTPS + +Authentication requests can be sent via HTTPS to a hosted authenticator. The encoded JWT of the request must be set as query parameter `authRequest` when calling the url of the authenticator. + +The authentication request must contain a redirect url. The authenticator must open this url with the authentication response as encoded JWT in the query parameter `authResponse`. + +This transport protocol is implemented by the Blockstack Browser and the Stacks cli. + +### App Links + +On mobile devices, applications can use app links/deep links to send authentication requests and receive the response. They must use the same query parameters for the authentication requests and responses as the HTTPS protocol, i.e. `authRequest` and `authResponse`. + +This transport protocol is implemented by the following authenticator apps: + +- [Wise app](https://github.com/PravicaInc/wise-js) and client library[wise-js](https://github.com/PravicaInc/wise-js) +- [Circles app](https://github.com/blocoio/stacks-circles-app) for Android. + +### Android Accounts + +Android provides an open account management system. An authenticator can make use of it and provide an account service that application can use to authenticate and to access content providers of the user. + +The communication happens via Android Intents. The used data uris must use the query parameters `authRequest` and `authResponse`. + +Proof of concept implementation in [OI Calendar](https://github.com/openintents/calendar-sync/blob/master/app/src/main/java/org/openintents/calendar/common/accounts/GenericAccountService.kt). + + +## Transport Protocol Selection From 89b6fc66137e54c5b1a910bd9afa3c29ade987fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Friedger=20M=C3=BCffke?= Date: Mon, 16 May 2022 11:40:58 +0200 Subject: [PATCH 2/3] Update sips/sip-x/sip-wallet-protocol.md Co-authored-by: kyranjamie --- sips/sip-x/sip-wallet-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-x/sip-wallet-protocol.md b/sips/sip-x/sip-wallet-protocol.md index f3ee10e4..40adb706 100644 --- a/sips/sip-x/sip-wallet-protocol.md +++ b/sips/sip-x/sip-wallet-protocol.md @@ -30,7 +30,7 @@ This SIP’s copyright is held by the Stacks Open Internet Foundation. # Introduction -Decentralized application do not want to store credentials of their users. Instead users use a trusted wallet that manages the user's private keys savely. Therefore, applications needs a way to communicate with the user's wallet e.g. for requesting signatured of a transaction, authentication or message signing. +Decentralized applications, _dApps_, do not want to store credentials of their users. Instead users use a trusted wallet that manages the user's private keys savely. Therefore, applications needs a way to communicate with the user's wallet e.g. for requesting signatured of a transaction, authentication or message signing. Different transport protocols for exchanging messages between applications and wallets have been established in the web3 ecosystem. In the following sections the transport protocols are described and a standardized way how to agree on a transport protocol is defined. From f1441a1b34b508d1220594de05a328247d37175e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Friedger=20M=C3=BCffke?= Date: Mon, 16 May 2022 11:41:36 +0200 Subject: [PATCH 3/3] Update sips/sip-x/sip-wallet-protocol.md Co-authored-by: kyranjamie --- sips/sip-x/sip-wallet-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/sip-x/sip-wallet-protocol.md b/sips/sip-x/sip-wallet-protocol.md index 40adb706..44fc7005 100644 --- a/sips/sip-x/sip-wallet-protocol.md +++ b/sips/sip-x/sip-wallet-protocol.md @@ -42,7 +42,7 @@ The communication between application and authenticator can happen in various wa ### Stacks Provider -Stacks Provider is a common interface used for web applications to communicate with the authenticator via a browser extension. +The _Stacks Provider_ is a common interface exposed to dApps as a JavaScript object, often injected by a Web Extension. It provides functions to handle