U<-UTN conversion

This service is intended to simplify obtaining U for UTN. Second generation of the service will also allow the backward conversion from U to UTN. The service is fast and fully automatic. To simplify, speed up and make more robust this procedure uses some tricks that Universa platform provides.

Compound contract

graph LR subgraph parent A[UTN] end subgraph compound A --> R(rest) R -.->B(payment) R -.->U(U block) end

Where:

Parent: buyer-owned UTN

compound: "compound" contract including payment token, owner rest token and U block altogether.

The idea: URS creates "compound transaction" from buyer's coin, which does the payment and includes the purchased contract, U block, altogether, registered in a single atomic transaction. It is therefore impossible to pay without providing the U block and vice versa. Moreover, both parties are guaranteed to receive their stuff before the registration could be done.

How it works

sequenceDiagram participant b as buyer participant u as URS b->>u: UTN coin, amount u-->>b:compund contract including U note over b: checks and signs b->>+u: signed compund note over u: checks signatures u-->>b: OK note over u: starts registration loop until ready b->>u: get status u-->>-b: registration status end

In details:

Step 1. Buyer sends its UTN to URS to create compound contract which sells U pack for some part of this coin. The rate could be obtained first.

URS can do nothing with the coin — as it has no owner key to sign the payment.

URS returns the compound which includes valid but not yet signed U block and payment token in favour of the URS self. It also signs it with some other key just to be sure the buyer will not be able to alter the contract.

As a result, the buyer get a contract that needed its owner signature to allow payment (well, it has the key) and also URS signature to register U contract included in the compound. It has no URS key so it can not register the compound contract even by mistake, as the network will decline it, as U block requires URS signature to present.

Step 2. Buyer signs the compound with his/hers owner key and returns it to the URS.

URS checks that its auxiliary signature is still valid. If it is, the contend block was not altered and could be trusted. Then it checks the owner signature and place and signs it with its U key. At this point the compound could be registered and URS does it immediately.

Interesting part there is: the URS can not "extract" owners payment from the compound and register the payment separately, as it will ruin owner signature. The same it can not remove U block from it. Therefore URS can only register payment together with U block it sells.

Now:

Buyer already have a copy of the U contract: it is inside the compound and can easily be extracted. Even if URS will not return the registration state, buyer can get the U from the compound and check its state against the netwrork. If URS will receive the payment, the contract become approved automatically!

In the case URS will not register the payment, the owner is free to use the parent token in any way. As soon as the parent token will be used by owner in some other transaction, the compound will become invalid and not able to register anymore, so the URS will just drop it.

API

Get rates and limits

GET /api/v1/uutn/Info

Returns common response with, among others rates.U_UTN decimal string field. It specifies how many U URS gives for 1 UTN at this time. Sample response:

{
  "rates" : {
    "U_UTN" : "100"
  },
  "limits" : {
    "U" : {
      "min" : 10,
      "max" : 10000
    }
  },
  "status" : "OK"
}

limits section shows minimum and maximum amount in U that could be converted with a single operation.

Create compound

POST /api/v1/uutn/create_purchase

parameters:

utn_base64: the source coin part of which buyer is going to spend.
owner_address: the address of the new U contract owner. Could be different from the paying contract owner.
amount: amount in U to purchase. The price to purchase (see rate above) should be less than utn.amount.

returns:

On success, the common response having compound_base64: encoded compound contract signed by URS.

On error, typical error codes can be:

amount_too_small:
amount_too_big
invalid_utn: if something is wrong with the source UTN (say, it is too small or not an UTN contract)

Post signed compound

POST /api/v1/uutn/purchase

parameters:

compound_base64: compound contract with added buyer signature. Buyer should only add the signature, without repacking or changing it.

returns:

on success, common response with purchase record:

purchase: {
  id: long,
  state: string,
  state_note: string
  purchased_contract_base64: base64_string, // only if state == 'ready'
}

state	description
`in_progress`	the contract is being registered
`ready`	the contract is registered, purchased contract is ready
`cancel`	the purchase is cancelled and the source coin can be reused

Conulst purchase record's state_note field for details on the state.

Buyer then can just monitor its U block state or call status check.

Check purchase status

GET /api/v1/uutn/<uutn_puchase_id>

On success returns common response with purchase_record: <purchase record>, see purchase record` and purchase states above.