Due to modern web-browsers' security measures, the opening of the tab with the checkout flow internally might look like
a connection establishment via an exchange of
The protocol follows web security best practices (opens new window), associated with cross-origin communication.
The internal part of the checkout consists of the following stages:
- The client calls
- When the tab is open, the zkSync page will send the
ZKSYNC_OPENEDmessage. If it fails to do so within
OPENING_TIMEOUTms, the checkout promise resolves with
OPENING_TIMEOUT_ERROR. After receiving the
ZKSYNC_OPENmessage, the client's page will send a
START_SESSIONmessage to the zkSync page. The message contains:
- Array of the transactions, specified by the user.
- Token to pay the fee with.
- The origin of the opener. Must be equal to the origin of the opener (zkSync checks it on its side).
- The checkout id — a feature that enables multiple checkouts at the same time.
- If at least in one transaction the
fromfield differs from the user's address, the zkSync page will tell the user about it and will offer him to log in with the other account. The zkSync page will remember the client's origin. Now, all the
postMessage-s sent from the zkSync page will only go to the remembered origin.
CLOSE_POLL_INTERVALms the client's page will check if the zkSync page is closed. If the zkSync page is closed without starting the transactions, the client waits for
FOLLOWUP_HASHES_TIMEOUTms in case the hashes were sent to the client, but the browser was too slow. If the hashes don't arrive within this time, the checkout promise will be rejected with
ZKSYNC_CLOSED_ERROR. On the other hand, every
OPENER_CLOSED_POLL_INTERVALms the zkSync page checks if the client's page is closed. If it is closed before the transactions' hashes were sent, there is a danger that the hashes that the zkSync page will send won't be processed by the client. To prevent this from happening the zkSync page will warn the user about that and advice her not to continue the checkout.
- When the user clicks on transfer, the zkSync page sends to the opener the array of hashes of the transactions.
- (Optional for the client) After the client receives the transactions, he can either wait until they are committed or
verified using the
Time constants (all in ms):
# Making sure that the user knows about an error
In order to prevent the situation, where the checkout promise was rejected on the client's webpage, but the user does not know it, the following measures are taken:
If the checkout promise is rejected, an
ABORT_CHECKOUT message is sent to the zkSync page. The message is then handled
by the zkSync page accordingly (show a modal with the error message and suggest the user not to continue the checkout).