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.
| Role | What they need | What they do |
|---|---|---|
| Sender (a person or an agent) | A NEAR wallet with funds | Deposits NEAR, receives a 16-character code, sends it to anyone |
| Receiver | Only the code | Chooses where the money goes and collects. Signs nothing with a wallet, pays nothing |
| Courier (relayer) | A funded account | Submits the signed claim and pays the gas. Never sees the code |
| Anyone | Any account | After 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 cheque | Yoru | |
|---|---|---|
| What you hand over | A signed slip of paper | A 16-character claim code, link or QR code |
| Who can cash it | The named payee, checked by a bank | Whoever holds the code; the receiving account is fixed when they sign |
| Receiver needs | A bank account | Nothing: a new account is created by the payment |
| Where the money waits | The sender's bank | An escrow contract nobody controls |
| If it's never cashed | It goes stale | After 7 days it walks home to the sender |
| Who it's for | People | People and autonomous AI agents |
A traditional payment concept, executed onchain, ready for agents.
流How it works
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
- Scroll to the counter, or press Leave a cheque.
- Enter an amount and, if you like, a note. The note never goes on chain; it is copied with the code.
- Press the green 封 seal and approve in Meteor or MyNearWallet (testnet).
- Copy the code, the claim link, or show the QR code. It is shown once.
受 Collect a cheque
- Open the claim link, or paste the code into Collect.
- 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 a0x…MetaMask address.
- 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
| Method | Kind | Who can call | What it does |
|---|---|---|---|
create_cheque(public_key) | Payable | Anyone (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) | Change | Anyone (usually a courier) | Verifies the signature over the claim message, then transfers the amount to receiver. |
refund(cheque_id) | Change | Anyone, after 7 days | Sends an unclaimed cheque back to its sender. Pays only the sender. |
get_cheque(cheque_id) | View | Anyone | Amount, status, sender, receiver, created and expiry times. |
get_cheque_by_key(public_key) | View | Anyone | Finds a cheque from the key a code derives, so a receiver only needs the code. |
on_claim_transfer, on_refund_transfer | Private callback | The contract itself | Marks a cheque collected or returned, or reopens it if the transfer failed. |
A cheque's life
| Status | Meaning | Next |
|---|---|---|
Open | Waiting in the box | Claimed with a valid signature, or refunded after 7 days |
Claiming | A transfer to the receiver is in flight | Claimed, or back to Open if it failed |
Claimed | Delivered | Final |
Refunding | Going back to the sender | Refunded, or back to Open if it failed |
Refunded | Returned to the sender | Final |
Errors you may see
| Message | Why |
|---|---|
signature does not match this cheque and receiver | Wrong code, or the receiver was changed after signing |
cheque is not open | Already collected or returned |
cheque has expired | The 7 days are over; it can only go home now |
cheque has not expired | A refund was tried too early |
public_key already used | Each code makes exactly one cheque |
deposit must exceed storage cost | The deposit doesn't cover the cheque's storage |
守Security
| Threat | What stops it |
|---|---|
| Someone copies a claim from the mempool and redirects it | The receiver is inside the signed bytes; changing it breaks the signature |
| Someone front-runs a claim unchanged | It still pays the original receiver; the front-runner only pays their gas |
| A claim is replayed | A cheque pays out once; the second attempt is cheque is not open |
| A signature is reused on another deployment | The contract id is inside the signed bytes |
| Codes are guessed offline from the public key | 80 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 forever | After 7 days anyone can trigger a refund, which pays only the sender |
| The courier learns the code | It 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.
| Script | Role |
|---|---|
agents/agent-a.mjs | Payer: funds a cheque and writes only the code to Agent B's inbox |
agents/agent-b.mjs | Receiver: has only the code; claims to a brand-new account; sends no transaction |
agents/relayer.mjs | Courier: accepts signed claims over HTTP, submits them, pays gas |
agents/attacker.mjs | Copies a published claim and tries to redirect and replay it |
agents/refund.mjs | Sends 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.