SteemConnect, escrow operations and documentation

Hello fellow developers, busians and steemians.

Today I'm going to present you a long due feature that might interest some of you. I'm talking about escrow operations that will probably lead to the creation of ... I don't know... may be some marketplace apps :)

I'm going to detail those 4 operations:

escrow_transfer
escrow_approve
escrow_release
escrow_dispute

We've designed SteemConnect hot sign to help you set the correct values for each fields all the operations require but adding a little documentation never hurt anybody.

Escrow transfer

This is the most complicated one. It has a lot of fields with many rules.
If you want to jump right into the code for this one you can look at this file

Let's detail each field and what to set for them

from: the user that will give some STEEM and / or SBD. With this field SteemConnect verifies that the user exists.
to: the user that will receive the money. Here too we verify that the user exists. Better send money to someone no ?
agent: the third party that will serve as an intermediate until the transaction is approved. The same controls applies.
escrow_id: this is a unique ID for your escrow. He doesn't have to be a unique ID in the whole blockchain. It's must be unique for you. It means you can't create two escrows with the number 1 for example. Also it must be an integer.
sbd_amount: how many steem dollars you want to send. It must be what we call an asset (1 SBD for example). We control that you've set SBD and not STEEM for this one. Also the field is normalized with 3 decimals. If you type 1 SBD, we'll format it to 1.000 SBD.
steem_amount: it works the same like the previous field but instead you have to send STEEM
fee: the fees that will be sent to the agent. It can be either STEEM or SBD.
ratification_deadline: the deadline of the escrow. Here we expect a valid date formatted with this pattern: 'YYYY-MM-DDTHH:MM:SS'. The date must not be in the past.
escrow_expiration: the expiration date of the escrow. It works the same than the previous field but escrow_expiration must be after ratification_deadline.
json_meta: some JSON data that you want in your escrow transaction.

And that's it. Now we're are ready to create an escrow.

This is an example of what can be done : Escrow transfer example on SteemConnect

Using this link I'm going to send 0.001 SBD to @ekitcho but no STEEM and ask for @fabien to be the agent and pay him handsomely a 0.001 STEEM.

Look at that, it works, see the transaction proof : Steemd transaction

And how about we set from to @buyer, to to @seller and agent to @awesomemarketplaceapp ?

Talking about the escrow_id, this is what happens if I try to create another escrow with the same id.

Ok so now I have my escrow transfer what next ? Well it needs to be approved by 2 users, the agent and the receiver so here it will be @fabien and @ekitcho

Escrow approve

For this operation you will recognize some fields so I'm not going to explain them again. You can jump right into the validation code here

from: just like before.
to: just like before.
agent: just like before.
who: the user that approves the escrow. It can be the agent or the to users. Any other user will be rejected by SteemConnect and by the blockchain ultimately.
escrow_id: just like before.
approve: a boolean equals to true

Much simpler right ? So for this one @fabien and @ekitcho had to work a little :)
Using this link one user approved the escrow:
Escrow approve example on SteemConnect

Here is the result in the blockchain: Steemd transaction

@fabien did the same.

Imagine if who is our @awesomemarketplaceapp user :D

Now that all the parties have approved the escrow we can release the funds.

Escrow release

Like before I'm going to be quick on some fields. The validation code is here.

Now you already know these fields: from, to, agent, escrow_id, sbd_amount, steem_amount
Let's detail the remaining two.

who: this is the user who will release the funds. This user must be either the one set as the agent or the to user.
receiver: who will get the money ? It can be the user of the from field or the to field

In our example I asked @fabien to release the funds to @ekitcho using this link:
Escrow release example on SteemConnect

You can check it on the blockchain: Steemd transaction

And this is something our @awesomemarketplaceapp user could do right ?

Escrow dispute

Unfortunately, sometimes you have to say no. But since you've read this far you already know everything. This operation needs these fields: from, to, agent, who, escrow_id but you already know them all ! The code.

Here is a quick example.
Escrow dispute example on SteemConnect

So even if other apps have already taken care of the escrow like @esteemapp before us, we hope you'll like this new addition and have some ideas on how to use it!

Don't forget to follow us @busy.org and use our platform https://busy.org if you like our work! You can help us too by voting for our witness here: Busy Witness