AEX-2 - Js SDK interfaces for Wallets

Hello, this is the discussion topic for the AEX-2 Proposal:



so I have a couple of questions:

  1. How does this handle errors? e.g. when the handshake fails
  2. What does DH—I assume Diffie Hellman?— mean here? And how do a provider and sdk agree on which cryptographic primitives get used? Are they hardcoded? If so, please specify them
  3. The spec mentions a nonce. Are there any requirements for the nonce?
  4. For the callback url, what is the allowed format?

Also, it would be great to have at least a basic threat model section, because unless I’m misunderstanding something, the current model does not protect against MitM scenarios, among other things.

  1. It is a stateless message exchange system and defining and handling errors is out of the scope. The spec should not define how an SDK or wallet implementation handles errors on non-receipt of messages or receipt of corrupted messages.
    One of the solutions can be that the SDK and Wallet define a timeout to reinitiate the handshake but this should not be part of the spec.
    That being said, we’re planning to put in place a success message for broadcast method so to inform the wallet that the message has been transferred/broadcasted to the network.

  2. Yes, DH means Diffie Hellman and we’ll expand on that in the AEX.
    We have proposed the use of box implementation from NaCl and it has the selected primitive curve25519xsalsa20poly1305.

  3. it is the nonce that will be used for encryption and is required for decryption.
    Please refer to Public-key authenticated encryption: crypto_box

  4. we have not exactly finalized the spec for this and all suggestions are welcome. For now, we are planning to keep it open and allow all URL/URI formats including any custom ones too.

Thanks for the suggestion on putting the threat model section. Will try to attach that to the document.

I wasn’t really concerned with the method of handling errors but how they can be communicated between wallet and sdk. There is a ae:registrationComplete but no ae:registrationFailed. Does that imply that everything will just be done via timeouts?


this is PoC implementation of AEX-2: GitHub - nduchak/identity-provider-PoC: Aepp with identity extension example
We will appreciate for your comments and suggestions.

1 Like

We’ve added a method for communicating errors occurred on the broadcast of transactions.

As for ae:registrationFailed I don’t feel a need for it.
Can you provide an example where this might fit and might be required?

1 Like


Already add new ae:broadcastResponse message and onBroadcast hook(for Extension stamp) to AEX-2 implementation.
You can find it here:

Hi guys,

I extended our documentation of the sync protocol that we are using in AirGap. It should give you a good overview of how it works. For anything a more complex, it’s easiest to just take a look at the code (eg. if you want to compare how the serialization of different protocols compare to each other).

The protocol should be easily extendible to support more use cases. As soon as we know what features we want to support with our wallets, we can make another call to discuss those.

Maybe to expand a bit on what @andreas has posted. There were discussions and recently a call with the focus on AEX-2 to gather feedback about the approach described in this proposal.

We (as in the AirGap team, specifically Andreas, Alessandro and I) are the opinion that the proposed encryption brings and added complexity and think this should not be part of this proposal. The encryption should be handled by the transportation layer itself and should only be added if that layer is inherently insecure.

In the call we’ve also talked about the approach AirGap uses RLP for transaction serialization/deserialisation.

We use RLP for the following reasons:

  • RLP is enjoying more adaption in crypto, with Aeternity adapting RLP as well after Ethereum
  • It is able to serialize and deserialize data in a predictable way
  • Easy to understand and implement
  • Encoded Data as Binary, size-efficient

A detailed write-up by Andreas, how the data is structured etc. can be found in the documentation linked.

After multiple discussions, following are the changes that I propose for the final draft of aex-2:

  • As mentioned by many, encryption should not be part of the document.
  • Transport layer should also not be part of the document.
  • As above two, same goes for transaction/message serialization and deserialization and it should have its own proposal.
  • Finally, AEX should only specify the protocol messages and messages should use the who - what - how rule for naming convention as described by the state channel doc here

We’ll start working on the above points and present the updated document in the next sprint cycle.
Please let us know what do you think about the above points by 30/04/2019 so that we can include the necessary changes in the next update.


Every extension should also define a name that can be displayed to the user.
Additionally, we should define a standard how the ID can be displayed. I propose we use the same identicon we already use for addresses.

aex-2 will be marked Final on June 5th. Currently, it has been moved to Last Call status.
As per the AEX-1, no unaddressed substantiated objections are left hence this should be done. in case of any issues please open an issue in the repo or address it in the forums.

1 Like

Updates to AEX-2 published waiting for PR to be merged.


due to the difficulty to agree on the details of the specification it was decided to withdraw the AEX-2

1 Like