iframeis used for all background requests such as transaction signing and message decryption, whereas the
windowcontext serves requests that require user interaction such as log in, sign up, and account management.
this.handleMessage(event)is a function defined by the developer to handle the logic around incoming messages. This handler function is likely the most important piece of code that you'll have to write when interacting with Identity. When working with Identity for the first time, we recommend a simple
console.log(event)to get a sense of how it works. The
event.datafield will contain the payload of messages sent by the DeSo Identity Service.
initialize. This message is sent in both
windowcontexts and will require a response. In this section, we will be assuming that we've already opened either an
windowcontext, but don't worry about it for now. Each context has a dedicated guide explaining its inner workings in more detail, and we'll get to that later. Below is an example of the
event.datathat your event handler will receive on
initialize. And here's a corresponding handler logic on line #226 in the implementation.
payloadfield will contain the data sent by Identity, such as user information, signed transactions, etc. In the case of
initializemessage, it's left as an empty JSON.
methodfield describes the message sent, which is
'initialize'in our example.
idfield should be set to match the
idvalue present in the
initializemessage. We set the
idfield as a string in the above code snippet, but you should set
id: event.data.idin your code. You may have noticed that in the example above we've added the string
"https://identity.deso.org"at the end of the
postMessage()call. This specifies the target origin, or the accepted URL for the destination of the
postMessage. We can alternatively pass the wildcard
"*"to accept any URL, which is less safe, but we will use it throughout this documentation for simplicity. However, we recommend setting
"https://identity.deso.org"for better security.
methodare requests that expect a response. (like
methodare responses to requests.
iddo not expect a response.
windowcontext API. For now, we will solely focus on the general intuition about account management, and leave the details of each API endpoint for the guide on the Window API. The account workflow involves the following steps:
windowcontexts to handle other actions requiring user interaction.
PublicUserInfo. This information can be thought of as secure user credentials consisting of three important fields:
encryptedSeedHexis used to verify user accounts between the
accessLevelHmacinformation is used to verify the permission that the user has given to your application
windowcontext, you will always want to add a
accessLevelRequestURL parameter to the request, such as below:
paramsvariable when handling URL parameters, and
accessLevelRequestlogic can be found at line #85. The access level request ranges from
4and determines what actions the user has authorized your application for. Higher permission level means higher number of authorized actions. The available access levels are:
2,3,4(increasing downwards) look like in the DeSo Identity UI:
windowcontext so that user can review and manually confirm a transaction. The approval mechanism is explained in more detail in approve. You should only require access level
4if your app really needs it. In general, you should deliberately request the minimal permission level that fits the requirements of your application For an exhaustive list of
accessLevelrequirements for each action, check out our iframe API documentation.
/api/v0/buy-or-sell-creator-cointo get an unsigned user transaction.
TransactionHexfrom the construct step's response, which encodes the user transaction, and signs it using the DeSo Identity.
/api/v0/submit-transactionby the developer so that it can be added to the blockchain ledger.
AccessLevelyou've requested in
/log-in, as mentioned in access-levels, will determine which transactions you can sign using the
iframecontext. The required AccessLevel for each
iframeAPI is detailed in the iframe API guide. If the transaction you intend to sign matches this AccessLevel, you could simply ask the DeSo Identity Service to issue a signature in the background through the
iframecontext. This would be done by sending a
iframesuch as in line #274.
postMessageon the iframe
contentWindow. We will explain the details of what belongs in the
reqvariable in the
iframecontext guide, though we will essentially have to pass
method: "sign"field, the
accessLevelHmacfields, and pass the
transactionHexof the transaction we want to sign (example on line #125). The response will contain either the
signedTransactionHex, meaning the request was successful, or a
approvalRequired: truefield that will indicate we need to launch the Identity window with the approval flow. To do so, we will launch a
windowcontext with the
/approveendpoint and pass the desired transaction as URL param:
signedTransactionHex, we can then broadcast it to the network. We will further describe the
method: "sign"iframe API message and
/approvewindow API endpoint in the corresponding API documentations.
V1, and current
V2; and we're expecting to move to a
V3version soon. Older blocks will still contain messages following the legacy
V1messages so they ought to be handled differently than the
V2messages. If you've read our core documentation, you should remember the transaction
ExtraData. New message transactions will have a
V: bytefield in
ExtraDatawhich should determine the used version (
2) - if a message transaction doesn't have the
Vfield, it means it's following
V1scheme. Here's how each version works:
V1: (LEGACY) Messages encrypted to the recipient public key using AES-128-CTR scheme. Messages can be decrypted with the private key of the user specified in transaction metadata field
V2: (CURRENT) Messages encrypted to both the recipient and sender using AES-128-CTR scheme with shared secrets derived via ECDH and run through a simple SHA256 ConcatKDF. Under
V1, once a message was broadcasted to the blockchain, the sender of the message was unable to decrypt it on other devices. On the other hand, shared secrets are available both to the recipient and sender, so both can decrypt messages.
V3: (PLANNED) We intend to expand the
V2scheme so it uses rotating messaging keys. Keys will be computed via HD wallet scheme with hardened derivation. Messaging keys can then be shared with third-party apps, specifically mobile clients, to simplify message handling.
iframecontext, with the exception of mobile clients relying on derived keys. These clients will handle messages through the
windowcontext. The goal of this subsection is to give you a general intuition about message handling. We leave the communication details to the section on
transactionHexwill finally be signed by the DeSo Identity and broadcast to the network as described in the Transactions section.