The PAKET Scheme on Stellar

In this story, I will describe an implementation of the PAKET L1 scheme (see previous post) over the Stellar distributed ledger.

A technical presentation to MVP workshop in Belgrade

Stellar Accounts in General

Stellar accounts must hold a minimum balance in XLM, and can therefore only be created by another account that has funds to spare. We assume that all participants (launchers, couriers, and recipients — see previous post for their definitions) have such accounts.

In addition, all the participating accounts have to trust the BUL token to a degree that will enable them to hold the necessary funds (see Stellar’s documentation regarding this).

The Escrow Account

The first step in setting up a virtual escrow that supports the PAKET scheme is creating a Stellar account for it, which incurs a cost in XLM. This account can be created by any existing account, and one can think of cases in which it will be created and funded by any of the participants, or even by a non-participant account. We call this account, whatever it is, the ESCROW FUNDER.

XLM in the Escrow Account

The escrow account must hold a minimum balance of XLM for as long as it exists (see Stellar’s documentation regarding this). Once the delivery is over (whether it fails or succeeds) and the payment and collateral are released, the account can and should be closed with the XLM balance withdrawn back to the escrow funder. This is done with an ACCOUNT MERGE operation.

Please note that the implementation described below leaves this merge operation as a separate transaction that needs to be separately submitted. This is done for separation of concerns, but the merge operation can be included automatically in the payment and refund transactions, and we are offering incentives to anyone creating forks of our software that support this.

In addition to the minimum balance, the escrow account will also pay, from its XLM balance, the transaction fees for its own setup and for the payment or refund. These fees will not be returned to the escrow funder as they will be spent, but they are extremely small (currently 1/100,000 of an XLM for each operation — see Stellar’s documentation regarding this).

BUL in the Escrow Account

The escrow account needs to be able to hold the payment and the collateral for the delivery, which means it has to trust the BUL token at least to the amount of payment + collateral. This is done with the CHANGE TRUST operation. Note that the account merge operation will fail if the escrow account is holding any tokens or trustlines. For this reason, it is highly recommended that the trust is not extended beyond that amount (otherwise, anyone holding BULs can send them into the escrow and disable the account merge, which means the account can never be closes and any XLM and BUL left in it will become inaccessible, or “burned”).

Setting up an Escrow Account in Detail

You can view the code that handles this here, and in this part of the video above, but note that both the video and the code it refers to reflect a slightly older and less baked version. Wherever there are inconsistencies, the and in this part of the video above,following description should take precedence.

1. Create the account and ensure it has enough XLM to cover the minimum balance + required transaction fees (account create operation)
2. Set the account’s trust in BUL to the amount of payment + collateral (change trust operation)
3. Get the sequence number of the account (n)
4. Create the payment transaction (txP) with sequence number n+1, releasing the payment + collateral BULs (which are not yet held in the escrow account!) to the first (and possibly only) courier (payment operation) and setting the trust in BUL to 0 to prevent anyone from sending extra BULs to the account (change trust operation)
5. Create a time-locked refund transaction (txR), identical to txP, except that the funds are released to the launcher instead of to the courier, and that the transaction is time-locked to the delivery deadline
6. Create a sequence-locked merge transaction (txM) with sequence number n+2, closing the account and moving any remaining XLM to the escrow funder
7. Create and submit a set options transaction (txO) with sequence number n, which does the following (using the set options operation):

a) Sets the threshold weights for operations to 2 for all operations

b) Add the hash of the payment transaction as a signer with a weight of 1

c) Add the hash of the refund transaction as a signer with a weight of 2

d) Add the hash of the merge transaction as a signer with a weight of 2

e) Add the recipient’s pubkey as a signer with a weight of 1

f) Set the original pubkey of the escrow (the MASTER KEY) to a weight of 0, thus effectively revoking it

Once this transaction is signed and submitted by the escrow account, the escrow is locked and ready for operation.

Note that the Stellar distributed ledger only holds the hashes of pre-authorized transactions, so the escrow funder must supply the launcher with the full payment transaction, and the courier with the full refund transaction, to allow both parties to trust the escrow.

Using the Escrow Account

At first, the escrow account is completely useless. Payment and refund transactions can’t be submitted because there are no BULs in the account, the merge transaction can’t be submitted because it has the wrong sequence number, the recipient can’t submit any transactions on his own because his weight is insufficient, and the private key from the original keypair of the account is entirely disabled.

Sending Funds to the Escrow

The only thing that can be done with the account is sending funds to it, and this state does not change until enough BULs are sent to it to cover the payment and the collateral. It is assumed (but not required) that the launcher will send the payment, and the first (and possibly only) courier will supply the collateral. Only once the balance of the escrow reaches the balance of payment + collateral BULs should the launcher pass the package to the courier and the courier accept it from the launcher.

Completing a Delivery

Once the final (and possibly only) courier reaches the recipient, the former will ask the latter to sign the payment transaction that was prepared earlier. Since the hash of this transaction was added as a signer it already has a weight of 1, and along with the recipient’s signature, it reaches a weight of 2 which is enough for the required payment operation. Anyone can then submit the transaction (the fees will be paid from the escrow’s XLM balance), thus releasing the payment and the collateral to the account of the first (and possibly only) courier.

Refunding a delivery

If the payment transaction was not submitted and the deadline passes, the refund transaction that was prepared earlier becomes valid. Its hash was added as a signer with a weight of 2, which is enough for the payment operation required. Anyone can then submit the transaction (the fees will be paid from the escrow’s XLM balance), releasing the payment and the collateral to the account of the launcher.

Closing the Escrow

The payment transaction and the refund transaction have the same sequence number, so they are mutually exclusive. Either one, once submitted, invalidates the other. Both of them, however, validate the merge transaction which has a higher sequence number, and a weight of 2, which is enough for the merge operation required. Once either the payment transaction or the refund transaction is submitted, anyone can submit the merge transaction which (assuming the escrow holds only XLM and trusts only BUL) will close the escrow account and move all remaining XLM back to the escrow funder.

Incomplete Funding

Note that it is impossible for the escrow funder (or anyone else) to close the account and reclaim his XLM until either a payment or a refund transaction was submitted, and it is impossible to submit either transaction until payment and collateral have been deposited in the escrow. If this happens for any reason (e.g. the courier reneged in the last minute), and assuming that the launcher is also the escrow funder (which is the common case), he can still retrieve his funds by waiting for the deadline to pass, sending the missing BULs to the escrow, submitting the refund transaction, and finally submitting the merge transaction.

The Relay Account

To implement a relay, the protocol demands that some changes be made to the account that is the beneficiary of the payment transaction of the escrow account (txP), namely: the Stellar account of the first courier.

Since these changes lock the account for at least the duration of the delivery, it is assumed that couriers will use a special disposable account for every delivery. This account will most likely be created by the first courier, but just like the escrow account, one can think of cases in which it will be created by any other account — participant or non-participant. We call this account, whatever it is, the RELAY FUNDER.

XLM and BUL in the Relay Account

Everything written above regarding the escrow account is also true for the relay account. Go read it again.

Setting up a Relay Account in Detail

You can view the code that handles this here, and in this part of the video above, but note that both the lecture and the code it refers to reflect a slightly older and less baked version. Wherever there are inconsistencies, the following description should take precedence.

1. Create the account and ensure it has enough XLM to cover the minimum balance + required transaction fees (account create operation)
2. Set the account’s trust in BUL to the amount of payment + collateral (change trust operation)
3. Get the sequence number of the account (n)
4. Create the relay payment transaction (txRP) with sequence number n+1, dividing the payment BULs between the old courier and the new courier and returning the collateral BULs to the new courier (payment operations, with BULs that are not in the relay account at this point) and setting the trust in BUL to 0 to prevent anyone from sending extra BULs to the account (change trust operation)
5. Create a sequence-locked merge transaction (txSM) with sequence number n+2, closing the account and moving any remaining XLM to the relay funder
6. Create a time-locked merge transaction (txTM) with a sequence number n+1 and time-locked to the delivery deadline, setting the trust in BUL to 0 and (change trust operation), closing the account and moving any remaining XLM to the relay funder
7. Create and submit a set options transaction (txRO) with sequence number n, which does the following (using the set options operation):

a) Sets the threshold weights for operations to 1 for all operations

b) Add the hash of the relay payment transaction as a signer with a weight of 1

c) Add the hash of the time-locked merge transaction as a signer with a weight of 1

d) Add the hash of the sequence-locked merge transaction as a signer with a weight of 1

e) Set the original pubkey of the relay (the MASTER KEY) to a weight of 0, thus effectively revoking it

Once this transaction is signed and submitted by the relay account, the relay is activated and the new courier can cover the old courier’s collateral (by sending him BULs directly) and take the package from him.

Note that for both parties to trust the relay it is not only required that the relay funder supply both couriers with the full relay payment transaction, but also that the old courier supply the new courier with the full payment transaction of the escrow account.

Using the Relay Account

At first, nothing can be done with the relay account. The relay payment transaction isn’t valid because there are no BULs in the account, the time-locked merge transaction is time-locked and the sequence-locked merge transaction is sequence-locked.

Relaying Payment

If everything goes according to plan and the delivery is completed successfully, txP is submitted and payment + collateral BULs are sent to the relay account. Once this happens, the pre-authorized relay payment transaction becomes valid and can be submitted by anyone.

Closing the Relay

Once the relay payment transaction is submitted, it bumps the accounts sequence number and validates the sequence-locked merge transaction which can then be submitted by anyone.

If the deadline passes and the relay payment transaction was not submitted, anyone can submit the time-locked merge transaction.

Chaining Relays

It is always possible to chain another relay to an existing relay. The process is almost identical, except that instead of using the account that is the beneficiary of the payment transaction of the escrow account (txP), we use the beneficiary of the payment transaction of the previous relay account (txRP).

Note that when adding another relay to the chain, the payment component of the relay payment transaction grows smaller with every leg, while the collateral component remains the same; and that each new courier has to be supplied with all payment transactions and relay payment transactions in the chain before he can trust the relay offered to him.