Quick Start

This walks the two arcs the program supports: a two-party escrow (deposit → claim) and a three-party mediated escrow (deposit → release).

Install

Add the gem to your Gemfile (it pulls in solace):

gem 'solace-zar-trustless-escrow'

bundle install

require 'solace/zar_trustless_escrow'

Set up the client

connection = Solace::Connection.new

# Defaults to the mainnet program id; pass program_id: for another cluster
# (see Reference › Clusters & Program IDs).
program = Solace::Programs::ZarTrustlessEscrow.new(connection:)

Two-party escrow

A depositor locks tokens that a claim authority can release to any claimant, or that the depositor can reclaim. All deposits for a mint share one program vault, which the deposit creates on demand if it doesn't exist yet (see The Program Vault).

# 1. Optional: pre-create the per-mint vault (otherwise the first deposit creates it).
tx = program.token_account_init(payer: fee_payer, mint: mint_address)
connection.wait_for_confirmed_signature { tx.signature }

# 2. Depositor locks 1 token (6-decimal mint).
tx = program.deposit(
  payer:           depositor,            # Keypair — the fee payer
  mint:            mint_address,
  depositor:       depositor,            # Keypair — signs
  claim_authority: claim_authority.address,
  amount:          1_000_000
)
connection.wait_for_confirmed_signature { tx.signature }

# 3. The claim authority releases the funds to a claimant.
tx = program.claim(
  payer:           claim_authority,      # Keypair — the fee payer
  mint:            mint_address,
  claim_authority: claim_authority,      # Keypair — signs
  claimant:        claimant.address
)
connection.wait_for_confirmed_signature { tx.signature }

If the funds are never claimed, the depositor (or sponsor) calls reclaim to get them back.

Mediated escrow

A depositor locks tokens naming a mediator and a beneficiary. The mediator releases the funds to either the depositor or the beneficiary — never taking custody. mediated_deposit initializes the vault if needed, so there's no separate setup step.

id = Solace::Keypair.generate.address    # unique id for this escrow

# 1. Depositor locks funds naming a mediator + beneficiary.
tx = program.mediated_deposit(
  payer:       depositor,                # Keypair — the fee payer
  mint:        mint_address,
  depositor:   depositor,                # Keypair — signs
  id:,
  mediator:    mediator.address,
  beneficiary: beneficiary.address,
  amount:      1_000_000
)
connection.wait_for_confirmed_signature { tx.signature }

# 2. The mediator releases to the beneficiary (or back to the depositor).
tx = program.mediated_release(
  payer:          mediator,              # Keypair — the fee payer
  mint:           mint_address,
  mediator:       mediator,              # Keypair — signs
  recipient:      beneficiary.address,
  rent_collector: mediator.address,
  id:
)
connection.wait_for_confirmed_signature { tx.signature }

With an expires_at: set at deposit time, the depositor can mediated_reclaim after expiry if the mediator never acts (see Expiry & Reclaim).

Where to next

• Conventions — the rules every method follows (get_ vs fetch_, the payer/sign/execute trio, pubkey vs keypair arguments).
• Concepts — the mental model behind the two escrow types, the shared vault, sponsors, and expiry.
• Operations — a page per instruction, documented at the program-method, composer, and instruction level.