CIP - Dispenser Reservation

Here’s a possible way to make dispensers safer.

Overview
Reservation is an optional feature. Buyer sends 1% of a regular dispense amount to the dispenser. This triggers a reservation. He will get the tokens provided he sends the full BTC dispenser amount within 20 blocks.

How It Works
A protocol update is necessary to add reservation logic.

The reservation price is 1% of the normal dispense rate. A reservation is made in the same way as a dispense - by simply sending BTC to the dispenser address. Once a reservation is triggered the contract reduces the ‘Give Remaining’ accordingly and puts the reserved token(s) on a ‘Reserved’ escrow. If the buyer (the same address which made the reservation) sends a full dispense amount within 20 blocks, he is guaranteed to receive the reserved token(s).

If he fails to send, the reserved amount goes back to ‘Give Remaining’.

To reserve a larger amount, simply send multiples of the basic reservation amount.

Example
image

I want to buy XCP. The price is 0.00050000. To reserve one XCP I would need to send 1% * 0.00050000 = 0.00000500 BTC to the dispenser.

I want 25 XCP, so I transfer 25 x 0.00000500 = 0.00012500 BTC to the dispenser.

After the transfer is included in a block, and Counterparty confirms the reservation, I send a full 25 x 0.0005 = 0.0125 BTC to receive my 25 XCP.

Further Conditions
The reserve price is floor(satoshi_rate/100), i.e. rounded down.

The reserve price for one unit can never be more than 0.0001 BTC. This to ensure a reasonable fee for reserving high value tokens.

There’s an implicit limit of 99 reservations at once. This because a dispense is triggered if the ‘Satoshi Rate’ (100x reserve price) is sent to the contract, hence a dispense request is assumed.

If the amount sent to a dispenser does not strictly match a multiple of the reserve price, the amount is rounded down to reserve as many as possible - similar to how dispensed quantity is calculated.

The seller can cancel the dispenser but not a reservation. The buyer is guaranteed to get the tokens if he makes the transfer within the 20 block limit.

Second Example
image

To reserve JPJA you don’t need to send a full 1% because the upper reserve price is 0.0001 BTC. Therefore you simply send 0.0001 BTC, wait for Counterparty to reserve the token, and then you are guaranteed to get JPJA for 0.135 BTC.

User Impact
There are no changes to opening a dispenser. A buyer does not need to make a reservation either. This is just an extra safety buyers can utilize if they wish to do so.