Introduction

This is some introductory text about stablenotes

Stablenotes ("notes") are simply strings of text that represent money within the stablenote system. Losing access to a note's text is completely unrecoverable and while integrating with stablenotes, ensuring that there are no circumstances in which these strings are lost is of the utmost importance.

Each note is a signed JWT that contains, among other information, a unique identifier or "code" as well as the value of the note. This is an example of a payload contained inside a note.

{
  "code": "jgo8LsPjgV7yTbIp0q6r08yITVZDWCbl",
  "type": "balance",
  "consumes": [],
  "amount": "20", // Amounts are in string form
  "encryptedText": "",
  "iat": 1706490099,
}

Since notes are JWTs they are immutable and can only be invalidated once created. Therefore, when changing the amount of a note, such as on a deposit, withdrawal, or transfer, the entire note will be invalidated, and a new one issued.

Due to the limited storage of data by stablenotes, there are no accounts or any way to identify a user, across their notes.

This means that in order to transfer money, a new note must be created, which will have a type of transfer, which contains the value of the transfer, which will then be redeemed by the user receiving the transaction. In the case that a user wishes to cancel a transaction for any reason, the transfer note can be redeemed by the same user who initiated the transfer as if they were receiving it.

The process of changing a note, involves passing your current note to the server, along with a transfer note, which will invalidate both the previous wallet note and transfer note and issue a new valid wallet note.

The same process occurs when creating a transfer note, where you pass the current balance note to the server as well as the amount to transfer, the wallet note will then be invalidated, and two notes will be returned: a balance note with a reduced amount, and a transfer note with the amount removed.

Confirming

Because the current note is the only claim to a balance within stablenotes, if a note is lost for any reason, it is a catastrophic failure that results in a loss of the balance. Even if the previous token was saved, it will have been invalidated in the process of creating a new note, and will not be able to recover the funds.

Stablenotes will never be able to recover lost notes for any reason as there is simply not a way to verify claims to lost funds due to the privacy of the system.

Because of the importance of ensuring data is saved, every time a note would be invalidated, the action must be confirmed.

Example

When creating a transfer note out of your existing note the following process will occur:

User has a note with a type of wallet and amount of "100". This note has the following payload:

{
  "code": "CODE1",
  "type": "balance",
  "consumes": [],
  "amount": "100",
  "encryptedText": "",
  "iat": 1,
}

User requests to create a transfer with an amount of 25. Passing the wallet note, and amount "25" to the stablenotes server.

The server returns a new wallet note with the following payload

{
  "code": "CODE2",
  "type": "balance",
  "consumes": ["CODE1"],
  "transferCode": "CODE3",
  "amount": "75",
  "encryptedText": "",
  "iat": 2,
}

as well as a transfer note with the following payload

{
  "code": "CODE3",
  "type": "balance",
  "transferCode": "CODE2",
  "amount": "25",
  "encryptedText": "",
  "iat": 2,
}

Both CODE2 and CODE3 will be marked as pending upon creation and are not yet valid notes. CODE1 has not been invalidated yet, and is still a valid note.

The user saves the new notes to a secure location, making sure to not delete CODE1 as that is still the valid code that holds their money.

The user sends the the notes CODE2 and CODE3 to the confirm endpoint on the stablenotes server, which will finally invalidate CODE1, and move CODE2 and CODE3 from pending to valid.

The user may then delete the previously valid code CODE1

This process ensures that not only is the valid not always saved on the user's device, but that at any point in the process, the user could lose internet connection or lose power, and no money will be lost, as by the time the confirm request is sent, the user will have already saved the pending codes, so even if the response to confirm is never received, the valid notes are still saved.

At any point during this process, there is an endpoint provided that will return the validity of the notes passed in, this allows a program to pick up where it left off in the case of an issue occurring that means the entire process was not completed. Therefore if prior to sending the confirmation request, power is lost, it is possible that upon reconnecting to the server, the validity of the pending note can be checked, and if it is observed that it is still pending, the confirmation request can be sent, resuming the process.

This chart summarizes the process: