Nyzo techMicropaySystem design

System design

Micropay supports a number of different functionalities. New functionalities are in development.

Sending tips

To allow users to send tips to you, first create an HTML element with the class nyzo-tip-button.

<div class="nyzo-tip-button">
</div>

Add the following data fields to the element:

With these fields, the element will look similar to the following.

<div class="nyzo-tip-button"
data-client-url="https://client.nyzo. co/api/forwardTransaction"
data-receiver-id="id__8cdasPC2QVZ13iG4 2RWhp47gow9SsIXZgp0Aga59oEITG2X-M7Ur"
data-tag="thank you for the content!">
</div>

When the Nyzo extension loads, it searches for all elements of the class nyzo-tip-button. In addition to loading the data fields of these elements, the extension removes the nyzo-extension-not-installed class and adds the nyzo-extension-installed class.

So, while not required, one may wish to add the nyzo-extension-not-installed class to a Nyzo tip element:

<div class="nyzo-tip-button nyzo-extension-not-installed"
data-client-url="https://client.nyzo.co/api/forward Transaction"
data-receiver-id="id__8cdasPC2QVZ13iG42RWhp47gow9SsIXZgp0A ga59oEITG2X-M7Ur"
data-tag="thank you for the content!">
</div>

When the extension loads, the element above would change to:

<div class="nyzo-tip-button nyzo-extension-installed"
data-client-url="https://client.nyzo.co/api/forward Transaction"
data-receiver-id="id__8cdasPC2QVZ13iG42RWhp47gow9SsIXZgp0A ga59oEITG2X-M7Ur"
data-tag="thank you for the content!">
</div>

Please note that the nyzo-extension-installed class will be added to all elements of the nyzo-tip-button class, regardless of whether the nyzo-extension-not-installed class is also present.

Also, please note that the extension processes all elements of the nyzo-tip-button class. If multiple elements with valid data-client-url and data-receiver-id fields are found, the last element that the extension encounters will be used for the tip configuration that is presented to the user. To avoid potentially confusing behavior, we recommend that pages are written according to one of the two following rules:

When the Nyzo extension finds a correctly configured Micropay tip button, the extension will present a tip option in the popup menu. Tip amounts are determined by the user in the options menu. The user sets a base tip amount, and the extension provides buttons with values of 1x, 2x, and 5x the user-specified amount.

screenshot of extension popup showing tip buttons

Paying for content

To allow users to purchase content with Nyzo Micropay, first create an element with the class nyzo-micropay-button.

<div class="nyzo-micropay-button">
</div>

Add the following data fields to the element:

With these fields, the element will look similar to the following.

<div class="nyzo-micropay-button"
data-client-url="https://client.nyzo. co/api/forwardTransaction"
data-receiver-id="id__8cdasPC2QVZ13iG4 2RWhp47gow9SsIXZgp0Aga59oEITG2X-M7Ur"
data-amount="0.1"
data-display-name="Demo article"
data-tag="article">
</div>

When the Nyzo extension loads, it searches for all elements of the class nyzo-micropay-button. In addition to loading the data fields of these elements, the extension removes the nyzo-extension-not-installed class and adds the nyzo-extension-installed class.

So, while not required, one may wish to add the nyzo-extension-not-installed class to Nyzo Micropay elements:

<div class="nyzo-micropay-button nyzo-extension-not-installed"
data-client-url="https://client.nyzo.co/api/forward Transaction"
data-receiver-id="id__8cdasPC2QVZ13iG42RWhp47gow9SsIXZgp0A ga59oEITG2X-M7Ur"
data-amount="0.1"
data-display-name="Demo article"
data-tag="article">
</div>

When the extension loads, the element would change to:

<div class="nyzo-micropay-button nyzo-extension-installed"
data-client-url="https://client.nyzo.co/api/forward Transaction"
data-receiver-id="id__8cdasPC2QVZ13iG42RWhp47gow9SsIXZgp0A ga59oEITG2X-M7Ur"
data-amount="0.1"
data-display-name="Demo article"
data-tag="article">
</div>

Please note that the nyzo-extension-installed class will be added to all elements of the nyzo-micropay-button class, regardless of whether the nyzo-extension-not-installed class is also present.

When the Nyzo extension finds a correctly configured Micropay payment button, the extension will present the payment option in the popup menu.

screenshot of extension popup showing payment button

When the user clicks the payment button, a transaction is generated and sent to the Nyzo client at the URL indicated by the data-client-url attribute of the Micropay button. If the client accepts the transaction, a success message is displayed.

screenshot of extension popup showing acceptance of Micropay transaction

When the client accepts a transaction, the extension sends that transaction back to the page along with a supplemental transaction with an amount of ∩0.0. The transaction can then be presented by the page to the web server to prove that payment was made for the content. The supplemental transaction, which is always generated on demand with a recent timestamp, can be used to provide reasonable certainty that the user sending the transaction holds the private key of that transaction. Without this supplemental transaction, a user could watch the blockchain for specific Micropay transactions and then potentially reuse those transactions to obtain content.

At this point, the page interacts with the web server providing Nyzo Micropay content. So, the rest of the process can proceed as the content web server chooses. The Nyzo documentation server provides a reference implementation of Micropay content delivery, and this documentation repository provides examples of an article, an image, and multiple items on one page purchased with the Micropay mechanism.

In the reference implementation, the page listens for the transaction from the extension and uses that transaction to request Micropay content.

document.addEventListener('micropayTransactionAvailable', function(event) {
if (!isUndefined(event.detail)) {
var transaction = event.detail.transaction;
var supplementalTransaction = event.detail.supplemental Transaction;
requestMicropayResource(transaction, supplementalTransaction);
}
});

The requestMicropayResource() function fetches the content from the web server, sending the transaction and supplemental Transaction as URL query parameters encoded in Nyzo string form.

function requestMicropayResource(transaction, supplementalTransaction) {
// Get the installed button. Set it to a "requesting..." state.
const installedButton = document.getElementBy Id('installed-button');
installedButton.classList.remove('error-button');
installedButton.innerHTML = 'Requesting content...';

const httpRequest = new XMLHttpRequest();
httpRequest.onreadystatechange = function() {
if (this.readyState == 4) { // 4 == "DONE"
if (this.status == 200) {
document.getElementById('micropay-target'). innerHTML = this.response;
document.getElementById('micropay-mask'). style.display = 'none';
document.getElementById('micropay-button'). style.display = 'none';
} else {
if (this.status === 402) {
installedButton.innerHTML = 'The payment was not accepted by the web server. Please clear ' +
'the payment from the Nyzo extension and try again.';
} else {
installedButton.innerHTML = 'An error occurred. Please try sending the payment again.';
}
installedButton.classList.add('error-button');
}
}
};
httpRequest.onerror = function() {
installedButton.innerHTML = 'An error occurred. Please try sending the payment again.';
installedButton.classList.add('error-button');
}

var fullUrl = '/micropay/resources/article.htm?transaction=' + transaction + '&supplementalTransaction=' +
supplementalTransaction;
httpRequest.open('GET', fullUrl, true);
httpRequest.send();
}

On the documentation server, any resource can be configured to require payment by adding a file with the extension .micropay and the same name as the resource file. So, to require payment for the file nyzo_logo_256.png, one would need to add a file in the same directory with the name nyzo_logo_256.png.micropay containing an appropriate configuration. Following is the Micropay configuration file used for the image resource in the image example.

# This file contains the parameters necessary for Micropay. The "price" and "receiver_identifier" parameters are
# required. The "sender_data" parameter is optional but recommended. If "sender_data" is not provided or is empty, all
# transactions to the receiver with an appropriate amount will authorize delivery of content.

# "price" is specified in nyzos
price=0.2

# "receiver_identifier" is a Nyzo public identifier string
receiver_identifier=id__8cdasPC2QVZ13iG42RWhp47gow9SsIXZgp0Aga59oEITG2X-M7Ur

# "sender_data" is either a UTF-8 string or a normalized sender-data string
sender_data=X(696d616765__________________________________________________ ____)

This section is not yet complete.

Playing games

Micropay functionality for playing games was developed with the initial example of tic-tac-toe. More sophisticated games are in development.

Nyzo vault

The vault example shows how content can be registered and verified on the Nyzo blockchain.