[updated] Ōkinoko Escrow – Trust Made Simple on VSC (incl. new Smart Contract Web Interface)

--- **TL;DR:** Via [Ōkinoko Terminal](https://terminal.okinoko.io), you can now **lock HIVE or HBD** in the [Ōkinoko Escrow](https://github.com/tibfox/okinoko_escrow) contract **on VSC**. The funds are only released when **both sides agree** - and if they don't, a **third person can step in** to decide. No more "trust me, I'll send it later" moments 😅! This contract takes care of that! *(There's a real example below if that still sounds a bit too abstract for you.)* --- I've been a bit quiet here lately... Not because I was lazy, but because I got lost in a bunch of fun side quests: Learning Go, digging through the [VSC SDK](https://github.com/vsc-eco/go-contract-template/blob/main/sdk/sdk.go), building a UI for smart contracts (more on that later), organizing [HiveOpenDays in Alicante](https://hiveopendays.com) next year, and juggling everyday life. Garden stuff, fixing the camper (finally running again!), and some other things I do not wanna talk about here (yet). Anyway, today I'm happy to finally show you something real: [**Ōkinoko Escrow**](https://github.com/tibfox/okinoko_escrow) aka [*vsc1BgfucQVHwYBHuK2yMEv4AhYua9rtQ45Uoe* on vsc](https://vsc.techcoderx.com/contract/vsc1BgfucQVHwYBHuK2yMEv4AhYua9rtQ45Uoe), which is the first production-ready contract I've deployed on the VSC blockchain. (And the first production-ready contract overall on VSC :P ) Today I made a big improvement in gas costs and the contract even **got verified** now! So you can be sure which source code the contract is actually running 🥳  If you're wondering about the name *Ōkinoko*: it's the umbrella for all my future VSC/Hive tools and contracts. The name came up in a brainstorming session with (at)minigunner and (at)artakush for another project that we had to cancel, but I kept the name. I just liked how it sounded. Short, fun, and easy to remember. --- ## Why Escrow? Escrow is one of those simple but powerful concepts that actually makes sense in the blockchain world: - It locks funds until both sides agree that things are done. - It cuts out middlemen and avoids "just trust me" moments. - It enables fair peer-to-peer deals, freelance jobs, or services without having to know each other. Many blockchains have something like this built in, including Hive. But Hive's escrow is not something we documented. So, I thought: why not make a version that's clean, simple, and works right on VSC? This isn't just a "cool dev thing." By putting Ōkinoko Escrow on-chain, you get: - **Less trust, more fairness**: no middleman, no manual transfers. - **Built-in dispute resolution**: if there's a problem, your arbitrator is already defined. - **Easy integration**: other apps can plug escrow in (for NFTs, services, micro-gigs, etc.). - **Transparency**: everything is verifiable on-chain. - **Reputation for arbitrators**: decisions are public, so good behavior matters. In short: it makes it easier to trade, collaborate, and get paid safely on VSC. --- ## Quick heads-up If you want to try the contract yourself, make sure you've got enough **HBD** in your VSC wallet(s). On VSC, your HBD balance slowly generates **RC** (resource credits) over 5 days. On the UIs these are shown in thousands by the way so I also keep it this way here. Hive users have 5.00 RC by default. Based on the following estimated costs you can test 1 escrow without any issues with a Hive account. - Creating an escrow costs about **2 RC** - Sending the first decision (without resolution) **0.2 RC** - The final decision including the release of funds costs around **0.4 RC** In v3 I've made it as light as possible and I am very happy with the gas costs now. If your call fails, it's most likely due to missing RC - **your HBD is safe**, only the RC gets consumed. And if the transaction fails no deposite will be made at all! So **don't worry**, feel free to experiment as long as you don't need your RC elsewhere. --- ## How It Works Let's keep it simple. Each escrow is a small instance that stores a few things:

{
  "id": 42, // escrow ID
  "n": "Design Project", // name
  "f": {"a": "hive:client1", "d": "p"}, // from (address, decision)
  "t": {"a": "hive:freelancer2", "d": "r"}, // to (address, decision)
  "arb": {"a": "hive:escrowhub", "d": "r"}, // arbitrator (address, decision)
  "am": 100.0, // amount
  "as": "HBD", // asset
  "cl": true, // closed
  "o": "r" // outcome (r=release / f=refund)
}

|Field|Alias|Meaning| |-|-|-| |`ID`|-|Unique number of the escrow| |`n`|`name`|Short description (up to 100 chars)| |`from`|`f`|The sender (who funds it) and their decision| |`t`|`to`|The receiver and their decision| |`arb`|`arbitrator`|The arbitrator (neutral third party) and their decision| |`am` / `as`|`amount` / `asset`|Funds locked (currently HIVE or HBD)| |`cl`|`closed`|True when finished| |`o`|`outcome`|Either `r` (release) or `r` (refund)| Outcomes (o) and decisions (d) are shortened strings that can include the following values: |Value|Meaning| |-|-| |`p`|pending| |`r`|release funds to receiver| |`f`|refund to sender| ### Core Actions Two main actions, aka "exported contract functions", exist: |Action|Purpose|Result| |-|-|-| |`e_create`|Create a new escrow|Locks funds, returns escrow ID| |`e_decide`|Submit your decision|Stores your vote, closes when 2 agree| You can also query an escrow: `e_get` → returns full details (metadata, decisions, outcome). ### Decision Logic Each party (sender, receiver, arbitrator) can vote and change their vote until the contract closes. - 2x **r** → funds go to receiver. - 2x **f** → funds go back to sender. That's it. Straightforward majority rule. ### Events To make it easy for UIs or explorers to follow what's going on, the contract sends events in the contract logs. An escrow got created:

{
  "t": "cr",
  "att": {
    "id": "42",
    "f": "hive:client1",
    "t": "hive:freelancer2",
    "arb": "hive:escrowhub",
    "am": "100.000",
    "as": "hbd"
  },
  "tx":"txId of creation"
}
````
A decision was made by one of the parties:

```json
{
  "type": "de",
  "att": {
    "id": "42",
    "r": "To",
    "a": "hive:freelancer2",
    "d": "r"
  },
  "tx":"txId of decision"
}

An escrow was closed:

{
  "t": "cl",
  "att": {
    "id": "42",
    "o": "r"
  },
  "tx":"txId of resolving decision"
}

Right now, there is no official VSC indexer, but I know that they have something in the making, so it will be much, much easier for UIs to integrate aggregated data. --- ## Real-Life Example Let's say Alice hires Bob for a design job. Carol is the arbitrator. ### 1. Alice creates the escrow

{
  "action": "e_create",
  "payload": "Website Design|hive:bob|hive:carol",
  "intents": [{
    "type": "transfer.allow",
    "args": { "limit": "100", "token": "HBD" }
  }]
}

This locks 100 HBD and gives an ID (say `123`). ### 2. Bob finishes work and votes "true"

{"action":"e_decide","payload":"123|r"}

He says: "I did my job - release the funds." The `outcome` is still "pending" because there is no majority vote. ### 3. Alice disagrees

{"action":"e_decide","payload":"123|f"}

She says: Nope, make it all purple instead green. The `outcome` keeps being "pending" because there is still no majority vote yet. ### 4. Carol checks and votes "true"

{"action":"e_decide","payload":"123|r"}

She says: Bob fulfilled everything Carol asked for! She asked for green and now wants purple... Now two people agree. The contract releases 100 HBD to Bob. Done. If Carol had chosen false, the refund would have gone to Alice. The `outcome` is now "r" and `closed` is now "true". ### 5. Anyone can check the status at any time

{"action":"e_get","payload":"123"}

Result:

{
  "id": 123,
  "n": "Website Design",
  "f": { "a": "hive:alice", "d": "f"},
  "t": { "a": "hive:bob", "d": "r" },
  "arb": { "a": "hive:carol", "d": "r" },
  "am": 100.000,
  "as": "hbd",
  "cl": true,
  "o": "r"
}

--- ## Don't Want to Mess With JSON? Yeah, same here. Working with SDK calls directly is not fun. That is why I built the [**Ōkinoko Terminal**](https://terminal.okinoko.io). This is a web interface (beta!) that lets you run smart contracts on VSC with proper forms and logs - **no manual JSON typing**. It's built with [Aioha React UI](https://www.npmjs.com/package/@aioha/react-ui) by (at)techcoderx. **Important note:** Right now, I recommend you to **use Keychain Browser** if you are on mobile. It should also work with HiveAuth but I need to make a few more tests with different mobile browsers to be really sure. ### 1. Login & Landing It looks a bit like a 90s cyberpunk console - guilty as charged, I love *Cyberpunk 2077* and I am a 90s kid. You connect your Hive wallet via a Aioha premade popup (needs your active key for running VSC contract functions of course). Once connected, hit **Enter ▶**.  ### 2. Pick a Contract Select one of the supported contracts. (pick the one without (legacy) - the screenshots don't match up 100%) You'll see all functions and details listed:  After reading carefully you can continue to the actual form by hitting **Next ▶** ### 3. Fill in the Function Parameters  You just fill out the fields (like `name`, `to`, `amount` and `arb`) and move on. Note: Hive addresses are prefixed by "hive:" on VSC - the dialog helps you with that tho. ### 4. Send the Transaction Click **Send ▶**, sign it, and wait. Execution on Hive itself is fast, while VSC may take up to a minute right now. The logs update in real time, and a green line means it worked! In the example, `Return: 5` means the escrow with the id 5 was created and now waits for decisions. The same goes for all the other functions and all upcoming contracts.


### 6. Remarks & Future **RC Limits:** Right now all transactions on [Ōkinoko Terminal](https://terminal.okinoko.io) contain a hard coded RC limit of 10'000. I will change that in future so you can overwrite this default value. **Error Output:** If your call did not succeed you can not see the logs right now. This is due to limitations of the graphql endpoint. In that case switch over to the [contract page](https://vsc.techcoderx.com/contract/vsc1BXMmApNdY2nAPNWTVmTm6Ufi88dtx66ESs) and check the tab "Outputs" over there. there you can find the error message related to your transaction. **☑️ Account Balance / RC Display:** Right now you need to go to https://altera.vsc.eco or https://vsc.techcoderx.com to check your balances. I will include that in the terminal as well in future and will add additional checks before you run a contract function. --- ## That's it! **Ōkinoko Escrow** and **Ōkinoko Terminal** are both live, simple to use, and a small but important step for fair deals on-chain. Big thanks to (at)techcoderx for his last-minute help with the contract verifier and for the Aioha package, of course! Also big thanks to (at)vaultec for his valueable input over the past couple of days. Now go try it out (preferably with small amounts first and with a proper HBD balance on vsc 😉) and don't forget to leave me some feedback. I would love to improve the terminal or contract in the near future! --- Oh and if you've built your own contract on VSC, ping me or drop a comment! I'm happy to add it to Ōkinoko Terminal. ---