CustomEscrow

Time-locked Escrow with Multi-signature Release

A Solana program built with the Steel framework that allows users to lock tokens for a specific time period, with options for early release through multi-signature approval.

Overview

This escrow program enables a secure way to lock tokens for a specified time period with the following features:

• Time-based Release: Tokens are automatically releasable after a predefined lock period
• Multi-signature Early Release: Tokens can be released early if both the initializer and a third-party arbitrator approve
• Early Cancellation Window: The initializer can cancel the escrow within 24 hours of creation
• Secure Token Custody: Tokens are held in a program-controlled vault until conditions are met

Key Parts

The program maintains several accounts to manage the escrow process:

1. EscrowAccount: Stores the core escrow details (initializer, recipient, amount, timelock)
2. SignatureTracker: Tracks approval status for early release
3. EscrowVault: Holds the tokens during the escrow period
4. VaultAuthority: A PDA that controls the vault

User Stories

As an Initializer (Alice)

Alice wants to lock tokens for Bob with a 30-day timelock

1. Alice initializes the escrow, specifying:
   • Bob as the recipient
   • A trusted third party as the arbitrator
   • The amount of tokens to lock
   • A 30-day timelock period
2. Alice transfers tokens to the escrow vault
3. Alice can cancel the escrow and retrieve tokens within 24 hours if needed
4. After 24 hours, Alice can only approve early release alongside the arbitrator

Alice needs to approve early release

1. If circumstances require early release before 30 days
2. Alice submits an approval transaction
3. If the arbitrator also approves, Bob can claim tokens early

As a Recipient (Bob)

Bob wants to claim tokens after the timelock expires

1. After 30 days, Bob submits a claim transaction
2. The program verifies the timelock has expired
3. Tokens are transferred to Bob's account automatically

Bob needs tokens before the timelock expires

1. Bob requests approval from Alice and the arbitrator
2. Once both approve, Bob can claim tokens early
3. Without both approvals, Bob must wait for the timelock to expire

As an Arbitrator (Charlie)

Charlie needs to approve early release

1. Charlie reviews the situation requiring early release
2. If appropriate, Charlie submits an approval transaction
3. If Alice has also approved, this enables Bob to claim tokens early

Example Scenarios

Standard Timelock

1. Alice creates an escrow for Bob with a 30-day timelock
2. After 30 days, Bob claims the tokens
3. The escrow completes successfully

Early Release

1. Alice creates an escrow for Bob with a 30-day timelock
2. After 15 days, circumstances require early release
3. Alice submits an approval
4. The arbitrator (Charlie) submits an approval
5. Bob claims tokens early
6. The escrow completes successfully

Cancellation

1. Alice creates an escrow for Bob with a 30-day timelock
2. Within 24 hours, Alice decides to cancel
3. Alice cancels the escrow
4. Tokens return to Alice's account

API

• Consts – Program constants.
• Error – Custom program errors.
• Event – Custom program events.
• Instruction – Declared instructions.

Instructions

• Add – Add ...
• Initialize – Initialize ...

State

• Counter – Counter ...

Get started

Compile your program:

steel build

Run unit and integration tests:

steel test