Wallet Interaction Standard

Currently there is no standard of how a decentralized application interacts with a wallet, resulting in uncertainty from the developers perspective. In order to guarantee broad adoption of applications leveraging Tezos smart contracts the right developer tools need to be provided.

Not having a standard also results in bad end user experience, having a dedicated wallet for each service hat the user needs to setup first is not feasible.

We’ve gathered our initial thoughts and put them in a draft proposal and tentatively made it available in a repository.


The proposal describes the various message types and provides examples of transport layers.

Message Types
The different message types that exist between the app and wallet.

  • PermissionRequest
  • SignTransaction
  • PaymentRequest
  • Broadcast Transactions

Transport Layers
Example of possible transport layers using these message types, we only describe two here that are distinctly different.

  • QR Codes
  • Push Notification / Relay Network

Feedback - Round 1

We came together for a workshop with parties like Stove Labs, Cryptonomics, CamlCase, ECAD Labs, Keefer Taylor & Cryptium Labs during the TQuorum Global Summit.

The workshop was immensely valuable and productive as were able to gather a lot of feedback and discuss eventual scenarios and why certain changes to the draft are required.

Additional Feedback

Now we’re also looking to you, please share your thoughts on such a standard and the proposed message types. Keep in mind the great feedback we have already received and will incorporate in the next iteration of the proposal.

Next Steps

The next steps from our side to continue this effort will happen shortly.

  • Adapt draft with feedback for the next iteration
  • Implementation -> first step: wallet browser extension MVP (signing, broadcasting)

Hey! Could you, while you’re at it, create a standard for actual “Messaging” between tz addresses? Which could then be integrated to wallets and people can switch of or on whether they want this to apply for them. Would be great for baking services to communicate directly with delegates etc.


A few immediate comments

  1. It’s not clear what PermissionScope means or what “address” “sign” and “network” mean and why there is an array of those.

  2. For payment requests, an address is given, but that should really be an address + an optional entry point.

  3. Thinking in terms of “signing” is a bit limiting. Rather, think in terms of triggering a specific message to be sent between address A controlled by the wallet and address B controlled by the application. That likely implies a signature from the user but, in some cases, it may be a signature that’s unrelated to address A and that’s fine.


Hey @murbard see answers:

  1. we’ll make sure to specify that in more detail, but what it means is:
  • addresses : the dApp is requesting to retrieve the state of what addresses are managed from the wallet. This can be e.g. for a portfolio app, wallet app, etc basically everything that requires that state (most dapps will be requesting this scope). Note however that the wallet/user can still decide to disclose only some of the addresses under management.
  • sign : the dapp is requesting to be able to sign transactions and/or messages.
  • network : the dapp wants to know which rpc endpoint is used by the wallet including credentials in case it requires authentication.
  1. are you talking here about an entrypoint like e.g. rpc node or what entrypoint are you talking about?

  2. dapp and wallet will be communicating with signed messages. Those messages will be transferred over a P2P transport layer (we’re proposing an xtz authenticated matrix implementation at the moment). At the moment the idea is to have specific messages in that layer that every wallet would understand, so that as long as a wallet and a dapp implement that standard they will be interoperable -> the user can choose freely which wallet to use. From what I understand in your comment you are proposing that wallet and dapp should be free to use this channel with an own/custom messages/protocol. I think we can provide support for that however some axioms like being able to request signatures for messages should be following a standard so that we don’t loose interoperability.

Please let me know in case I misunderstood some of the comments.

1 Like

In a first stage the message types discussed here are more related to the wallet and app communication that said if there is a transport layer, like the one we’ve quickly touched on in the feedback, that uses a decentralized messaging protocol like Matrix, sending messages between addresses becomes more feasible as having them to store on-chain.

This would then also allow to have a more real-time communication for sending messages between address or passing data like a prepared transaction from one device to another.

1 Like

Do you mean a list of addresses or do you mean that the addresses have a state attached to them?

Is the idea that this lets the dapp sign any message or is the user still prompted? If the user is prompted every time, why is a permission needed?

What rpc endpoint?

An entry point in a smart contract, this can be necessary for sending funds.

I don’t get it… what are those messages? Why do you need them?

I’m not sure what you mean. I think we are talking about very different things here. What I imagined is that a dapp would want you to send a message/transaction to its smart contract, it would craft that transaction for you, and it would be the wallet’s job to make sure that transaction is emitted towards the right address. What you’re talking about (dapp talking with a wallet over a p2p network with signed messages) seems very different and I’m not sure what it accomplishes. Am I missing something?

1 Like

List of addresses. The dapp is itself is responsible to fetch (e.g. from blockchain and/or ipfs) the required state (or store the required state) for its use case.

That’s a fair question. The idea is that there might be some threshold (e.g. 10xtz per hour) that will simply pass through without need of accepting every time. But maybe that is not a relevant use case and we can just say the user always has to acknowledge on a per signature basis.

The JSON-RPC from the node the dapp is using to fetch the blockchain data/perform contract calls.

This clears things up thank you. We’ll make sure to take the different entry points into consideration. This is very valuable feedback. In the beginning we thought of having similar action calls like specified here https://tezos-uri.smartcontractlabs.ee/tool/, but to widen the scope and also include any entry point makes sense and will take make it easier for simple dapps to be developed.

Messages are in this case part of the protocol, “the packets” both parties must understand and exchange. This is mostly the underlying transport layer used for this app<->wallet protocol.

Ok all clear now. Of course this protocol will provide support for arbitrary transaction/contract calls the dapp will be responsible to prepare the payload accordingly (because only the dapp has the domain knowledge) and then the wallet take over the responsibility of signing + broadcasting.

1 Like

I’m very happy that this conversation is happening! Question, for R&D of these standards, should we not have a few dApps running before we can properly institute their respective needs.

Would the establishment of an initial wallet standard (even though it will of course evolve over time) prior to the proliferation of the first generation of dApps not narrow the scope of wallet interoperability for which the subsequent dApps could design? That is, is this a push or pull situation?

This is not really a chicken, egg dilemma. Currently dapps are in the process of being built, if there is no standard which they can use then they are forced to come up with a solution on their own, which in the end will most likely not be compatible with others.

I agree that it’s important to recognise all the needs but a start somewhere is needed, this dialog and the draft are the first step. With that the awareness and requirements can be gathered and included in such a standard. Down the road if new requirements arise, adjustments with a new standard built on top of the existing one can be made.


We’ve updated the draft to reflect the new proposed transport layer for the app-wallet communication using a decentralised messaging service, in a first step use the matrix protocol with the long term vision that the Tezos reference node will eventually include such a messaging service by default, replacing the matrix network.

# Transport Layer

This standard requires a transport layer that can cover the following use cases:

* Same Device Desktop to Desktop (e.g. Galleon)
* Same Device Desktop to Hardware Wallet (e.g. Ledger)
* Same Device Mobile to Mobile (e.g. Cortez)
* Two Device Desktop to online Mobile (e.g. Wetez)
* Two Device Desktop to offline Mobile (e.g. AirGap)

The transport layer used for app-wallet communication we propose is using a decentralised messaging service. We are proposing to use the [matrix protocol](https://matrix.org/). Other projects in the blockchain space like [Raiden](https://medium.com/raiden-network/raiden-transport-explained-939d7741b6f4%5C) have been using matrix successfully to cover very similar requirements. The long term vision is that the Tezos reference node will eventually include such a messaging service by default, replacing the matrix network in the long term.

The main reasons why we propose to use a decentralized messaging service as the transport layer between app and wallet are:

* decentralization
* enables modern user experience
* covers all of the scenarios described above
* easy to integrate with all kind of wallets
* minimal effort to "join" for a wallet
* support for oracles (e.g. push service)

The complete update can be found on https://github.com/airgap-it/tezos-standards/blob/master/proposals/wallet-interaction.md#transport-layer

We hope to gather feedback to this approach, we’ll make changes to the proposal with the feedback we’ve recieved so far in a next step.

1 Like

I’m still very confused about this and why any type of transport layer is needed. It seems to me what you need is a URI scheme to pass transactions around and for wallets to register as external handler. I don’t understand at all what’s being proposed here and what it accomplishes.

A URL based protocol will only cover the same device scenarios. In order to support all scenarios we need a decentralized and generic transport layer. Since we want interoperability between all dapps<->wallets we need a standard that is flexible enough to cover all scenarios.

To elaborate a bit more on why we think it’s important to have an additional transport layer that is generic as well as decentralized.

Let’s imagine the following scenarios.

Scenario 1

  • Decentralized application in a browser on a mobile phone
  • secret (private keys) on a wallet on a mobile phone

The user wants to interact with a dapp on his mobile device and sign a transaction with the wallet on the same device.

  1. The wallet can be called through a URL based protocol and open the wallet with a deeplink
  2. The transaction is signed and broadcasted

Conclusion: This could be solved by a URL based protocol

Scenario 2

  • Decentralized application in a browser on a notebook
  • secret (private keys) on a wallet installed on a mobile phone

The user wants to interact with a dapp on his notebook and the sign a transaction with the wallet on his mobile device.

  1. The dapp and the wallet need to be aware of each other, we cannot directly do this over a URL based protocol
  2. A communication channel is being setup between the browser on the notebook and the wallet on the mobile phone
  3. The transaction data is being passed from the browser over this channel to the mobile device
  4. The user signs the transaction on the mobile device
  5. The transaction is being broadcasted

Conclusion: We cannot solve this by a URL based protocol

As mentioned the goal of this standard is to have a unified approach for every possible scenario. To avoid the introduction of a centralized component like a relay server responsible for passing the data between these two devices our suggestion is to use a transport layer to pass this messages between these two devices that is still decentralized.

1 Like

Do you think with the explanations given that it makes sense to introduce such a transport layer component?

Everyone, we’re scheduling a feedback call on Thursday 24th of October at 16:00 - 17:30 GMT+2 / 10:00 - 11:30 EDT. Please reach out to me and let me know if you would like to take part and contribute.

1 Like

We’ve had a really productive call and were able able to discuss the proposed protocol layer in depth as well as the individual messages. Thanks to the feedback provided by Arthur Breitmann, Jev (ECAD Labs), Vishakh (Cryptonomic), Simon (ECAD Labs), Istvan (Stove Labs).

The unedited meeting notes from the call on October 24th which will be reviewed again and then incorporated into the proposal by @dcale.

Transport Layer

  • any javascript dapp can connect to this (web rtc)
  • authentication
    – needed to send messages between the dapp and wallet
    – authentication modul needs to be written
  1. can be authenticated by Tezos accounts (arbitrary message signing)
  2. with a signed transaction, that does not need to be broadcasted
    –> which approach will be used?
  • how does dapp now that there is a wallet?
  1. chrome extension can directly inject to dapp
  2. SDK included in dapp can generate authentication QR code as a fallback
  3. push notification send to wallet for authentication
  • Why RLP and not use json or any other approach for serialisation
    – with rlp you have a unique serialisation
    – does it have to be rlp as the expected content of the message is known ahead of type

  • would it make sense to have fallback method for same device approaches and not use the p2p network in that case
    – as they probably have the same peer this will be an instant experience
    – for later improvement a fallback channel could be used

Message Types


  • threshold, should something like this be optional or not as implementations or not might not include optional parameters
  • room for evolution should be respected in the standard ex. threshold approach for automatic signing transactions without user input
  • what would happen with layer 2 application ex. state channels
  • threshold definition number of amounts, number of transactions, definition for certain asset/tokens
  • suboperation is send over the manager operation is done by the wallet, recommended parameters like gas, fees, storage can be interpreted by the wallet but they can be changed
    –> threshold will be in the standard as an optional marker
    –> thresholds should be revisited in a separate standard

Sign Payload

  • interaction with a dapp doesn’t have to happen necessarily with a signature
  • message that entails an entry point for a contract and a set of parameters and the potential sender
  • send over only the suboperation

Payment Request

  • recipientType should be introduced to distinguish the value of recipient to support more types


  • all messages also should have a version code for simpler debugging

@murbard provided additional feedback in written form after call, referenced here for the sake of completion

Next steps

  • Alessandro will adapt the changes
  • Last feedback iteration of the changes
  • Setting up multiple Matrix test-network nodes by parties involved in setting up the standard
  • Alessandro will share the custom auth provider and setup a quick guide, call will be setup to test the network
1 Like

How many lines of code is the matrix client with dependencies?

It’s not a good idea for wallets to add more code that needs to be audited and can cause security problems.

The best use case I can come up with for what you are trying to do is that you want the app to know whether the user confirmed or cancelled in the wallet dialog. You can infer that from watching the mempool. If you have any other use cases where you need more than a URI based solution, please share them.

Even if using the mempool is too slow, asking every wallet to add thousands of lines of code is not a good way to solve this. It looks like just the matrix JS SDK itself is 50k LOC. Is there something smaller? How big is it? How big is it if you include all the dependencies it pulls?

This is valuable feedback, also I agree that adding the SDK is overkill. However the matrix protocol itself is fairly straight forward and does not really require us to use the SDK, because you basically just need to setup the secure communication channel and not use all features the SDK offers, then it boils down to actually a couple of AJAX calls, which will result in max 200-500 LOC’s.

Watching the mempool can cover the use case of transactions actually hitting the blockchain, but what do you do if you “just” require a message signing or you don’t want to broadcast the transaction (yet)? For those use cases a two way communication channel is important.

Some time has passed and we were deeply involved with the development of a reference implementation of the wallet interaction standard that consists of a SDK for application and wallet developers, a browser extension and a reference implementation of an application that uses the SDK.

We will hold an initial short webinar to showcase the current state of development and gather feedback on Thursday 7th of November at 16:00 - 17:30 GMT+2 / 10:00 - 11:30 EDT. Please reach out to me if you would like to join the call.

More details will be shared soon.

1 Like

Did you mean February?

My bad, copied the wrong date I meant the Thursday 23 of January at 16:00 - 17:30 GMT+1 / 10:00 - 11:30 EST