Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SIP for Wallet Protocol #59

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions sips/sip-x/sip-wallet-protocol.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@

# Preamble

SIP Number: X

Title: Specification of the Wallet Protcol

Author: Friedger Müffke ([email protected])

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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 set of remote procedure call methods wallet providers must use.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either text is fine with me. RPC is a form of message exchange, and there will almost certainly be apps that use the message-passing paradigm instead of the RPC paradigm for communication.


# 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.
friedger marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is an authenticator different from a wallet here? If so, can you clarify the difference?


### Stacks Provider

Stacks Provider is a common interface used for web applications to communicate with the authenticator via a browser extension.
friedger marked this conversation as resolved.
Show resolved Hide resolved

It provides functions to handle

1. authentication
2. transaction signing
Comment on lines +47 to +50

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If using RPC methods, these should be deprecated. Wallet's can warn developers of this, to avoid breaking changes until the majority have migrated.

This section should include details akin to https://eips.ethereum.org/EIPS/eip-1193#supported-rpc-methods


https://github.com/hirosystems/connect/blob/main/packages/connect/src/types/provider.ts
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is describing a particular implementation. The SIP should describe the public interfaces and API contracts, as well as the transport protocol used to send and receive messages to interact with them.


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.
Comment on lines +52 to +73

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aren't these details better suited to your other SIP?


### 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