夜YoruDocs Back to the tea house

Documentation

Yoru 夜

Private claimable escrow on NEAR. Short code, bound receiver, gasless claim.

Leave NEAR behind a 16-character claim code. Anyone holding the code can collect it to any address, without a wallet, an account or gas. Yoru is built for agent-to-agent payments, and for every moment when the other side simply isn't ready.

NEAR testneted25519Argon2idRust · near-sdk 5three.js

夜Overview

Sending crypto assumes the receiver already has an account, tokens for gas, and an address they've shared. Yoru removes all three.

RoleWhat they needWhat they do
Sender (a person or an agent)A NEAR wallet with fundsDeposits NEAR, receives a 16-character code, sends it to anyone
ReceiverOnly the codeChooses where the money goes and collects. Signs nothing with a wallet, pays nothing
Courier (relayer)A funded accountSubmits the signed claim and pays the gas. Never sees the code
AnyoneAny accountAfter 7 days, can send an unclaimed cheque home to its sender

古From cheques to chain

For generations, people have paid each other with things the receiver claims later: cheques, money orders, red envelopes. You didn't need the other person's bank details to write one. Yoru brings that idea to NEAR.

A paper chequeYoru
What you hand overA signed slip of paperA 16-character claim code, link or QR code
Who can cash itThe named payee, checked by a bankWhoever holds the code; the receiving account is fixed when they sign
Receiver needsA bank accountNothing: a new account is created by the payment
Where the money waitsThe sender's bankAn escrow contract nobody controls
If it's never cashedIt goes staleAfter 7 days it walks home to the sender
Who it's forPeoplePeople and autonomous AI agents

A traditional payment concept, executed onchain, ready for agents.

流How it works

封SealThe browser makes a random code and stretches it into an ed25519 key.
箱DepositThe contract stores the NEAR and only the public half of the key.
宛SignThe code holder signs a message that names the receiving account.
灯DeliverA courier submits it and pays the gas; the contract verifies and pays.

The signed message

"yoru:claim:v1" || contract_id || cheque_id (u64, little-endian) || receiver

The contract rebuilds these bytes and checks the signature with NEAR's built-in env::ed25519_verify. Because the receiver is inside the signature, nobody can change it.

Code to key

seed = Argon2id(code, salt = "yoru:v1:" + contract_id, 64 MiB, 3 passes, 32 bytes)
key  = ed25519 key pair from seed      // the contract stores only the public key

手Using the site

置 Leave a cheque

  1. Scroll to the counter, or press Leave a cheque.
  2. Enter an amount and, if you like, a note. The note never goes on chain; it is copied with the code.
  3. Press the green 封 seal and approve in Meteor or MyNearWallet (testnet).
  4. Copy the code, the claim link, or show the QR code. It is shown once.

受 Collect a cheque

  1. Open the claim link, or paste the code into Collect.
  2. Choose where it goes:
    • My wallet: connect Meteor or MyNearWallet.
    • New account: no wallet at all. We make a key; download it before closing.
    • An address: a name.testnet, a 64-character address, an exchange's NEAR deposit address or a 0x… MetaMask address.
  3. Press the green 受 seal. The courier pays the gas.

読 Read a cheque

Look up any cheque by code or number without touching it: amount, status, sender, receiver and time left. After 7 days, send an unclaimed cheque home from here.

Whoever holds the code or the claim link can collect. Send it only to the person you mean.

箱The contract

Live on testnet at yoru-183ae9.testnet (7-day window) and yoru-demo-183ae9.testnet (3-minute window, for demos).

Methods

MethodKindWho can callWhat it does
create_cheque(public_key)PayableAnyone (the sender)Stores a cheque under the code's public key. The deposit, less storage, is the amount. Returns the cheque id.
claim(cheque_id, receiver, signature)ChangeAnyone (usually a courier)Verifies the signature over the claim message, then transfers the amount to receiver.
refund(cheque_id)ChangeAnyone, after 7 daysSends an unclaimed cheque back to its sender. Pays only the sender.
get_cheque(cheque_id)ViewAnyoneAmount, status, sender, receiver, created and expiry times.
get_cheque_by_key(public_key)ViewAnyoneFinds a cheque from the key a code derives, so a receiver only needs the code.
on_claim_transfer, on_refund_transferPrivate callbackThe contract itselfMarks a cheque collected or returned, or reopens it if the transfer failed.

A cheque's life

StatusMeaningNext
OpenWaiting in the boxClaimed with a valid signature, or refunded after 7 days
ClaimingA transfer to the receiver is in flightClaimed, or back to Open if it failed
ClaimedDeliveredFinal
RefundingGoing back to the senderRefunded, or back to Open if it failed
RefundedReturned to the senderFinal

Errors you may see

MessageWhy
signature does not match this cheque and receiverWrong code, or the receiver was changed after signing
cheque is not openAlready collected or returned
cheque has expiredThe 7 days are over; it can only go home now
cheque has not expiredA refund was tried too early
public_key already usedEach code makes exactly one cheque
deposit must exceed storage costThe deposit doesn't cover the cheque's storage

守Security

ThreatWhat stops it
Someone copies a claim from the mempool and redirects itThe receiver is inside the signed bytes; changing it breaks the signature
Someone front-runs a claim unchangedIt still pays the original receiver; the front-runner only pays their gas
A claim is replayedA cheque pays out once; the second attempt is cheque is not open
A signature is reused on another deploymentThe contract id is inside the signed bytes
Codes are guessed offline from the public key80 random bits plus a memory-hard Argon2id stretch make guessing impractical
A transfer fails (for example, a missing account)The cheque reopens, so the code still works
Money gets stuck foreverAfter 7 days anyone can trigger a refund, which pays only the sender
The courier learns the codeIt only ever receives the cheque id, the receiver and a signature

Private-ish, honestly. The code never touches the chain or the courier, and receivers don't publish an address in advance. The chain still shows which account funded a cheque and which account it paid.

機For agents

Agents can earn, but they can't get paid without a funded wallet. With Yoru, an agent created a second ago can be paid, and any agent can act as the courier.

ScriptRole
agents/agent-a.mjsPayer: funds a cheque and writes only the code to Agent B's inbox
agents/agent-b.mjsReceiver: has only the code; claims to a brand-new account; sends no transaction
agents/relayer.mjsCourier: accepts signed claims over HTTP, submits them, pays gas
agents/attacker.mjsCopies a published claim and tries to redirect and replay it
agents/refund.mjsSends an expired cheque home, from a stranger's account
npm install
node agents/relayer.mjs              # leave running
node agents/agent-a.mjs pay 0.5      # Agent A funds a cheque
node agents/agent-b.mjs claim        # Agent B collects with no account

問Questions

Do I need a wallet to receive?

No. Choose "New account": the page makes a key, the payment creates the account, and you download the key file to use the money later.

Can I claim to MetaMask?

Yes, paste your 0x… address. You receive NEAR on NEAR, at an account that your MetaMask key controls, opened through a NEAR wallet that supports Ethereum wallets. It is not ETH on Ethereum.

Can I claim to an exchange?

Any NEAR deposit address works on the same network. Exchanges exist only on mainnet, and some require a memo, which a plain transfer can't carry.

What if I lose the code?

Nobody can recover it, not even Yoru. After 7 days the cheque returns to the sender.

Is the note private?

The note is never stored on chain. It travels only with the code when you copy or share it.

Is this on mainnet?

Not yet. Yoru runs on NEAR testnet, where the coins have no value.