Core library for BitEscrow API.
npm install @scrow/core
A private, non-custodial protocol for using Bitcoin in a smart contract.
> If you are looking to use the BitEscrow API, check out our Developer Documentation resources and Replit Container.
Key Features:
* __100% private.__ All on-chain transactions appear as single-key spends. Participation is done through randomly generated credentials. Only requires a signing key (hot), and wallet xpub (cold) to participate.
* __100% non-custodial.__ Money is secured in a collaborative 2-of-2 contract. All payouts are pre-signed before deposit. Addresses are generated from a cold-stored xpub of your choice.
* __100% auditable.__ All contract terms, inputs, and operations are signed and recorded in a commit chain. Each settlement transaction is backed by an auditable commit history.
* __Designed for trustless environments.__ Signing keys are disposable and have no capacity to sweep funds. Terms are signed up-front and verified before deposit.
* __Designed to be robust.__ Deposits are reusable when a contract cancels or expires. Credentials are recoverable via your xpub. Refunds are secured upfront and broadcast automatically on expiration.
Package Features:
* Method libraries for every part of the protocol.
* Multi-platform client with minimal dependencies.
* Run-time schema validation (using zod).
* E2E demo and test suite for signet, testnet, and mutiny.
Comimg Soon:
* Full nostr integration for the API.
* Return receipts on all submissions.
* Add raw tx templates to a proposal.
* New programs for virtual machine.
---
1. Protocol Overview
a. Negotiation
b. Funding
c. Settlement
d. Protocol Flow
e. Security Model
2. How to Use
a. Create a Client
b. Create a Signer
c. Build a Proposal
d. Create a Contract
e. Deposit Funds
f. Using the CVM
g. Settle a Contract
3. Development & Testing
a. Running the Main Demo
b. Running in Replit
c. Using the Client API Demos
d. Using the CVM Eval Tool
e. Using the Test Suite
f. OpenAPI Specification
4. Questions & Issues
5. Contribution
6. Resources
7. Footnote
---
The complete protocol involves three rounds of communication, split between three parties:
Members : Those participating within the contract.Funders : Those depositing funds into the contract.Provider : The server hosting the contract (BitEscrow API).
The three rounds of communication are _negotiation_, _funding_, and _settlement_.
---
The first step is to negotiate and agree on a proposal document. This is a human-readable document which contains all of the initial terms of the contract.
It is written in JSON format, and designed for collaboration (much like a PSBT):
``ts`
{
title : 'Basic two-party contract with third-party dispute resolution.',
content : '{}',
duration : 14400, // 4 hours.
network : 'regtest',
paths: [
[ 'payout', 90000, 'bcrt1qhlm6uva0q2m5dq4kjd9uzsankkxe9pza5uylcs' ],
[ 'return', 90000, 'bcrt1qemwtdfh9uncvw7jlq4ux7p7stl9lgvfxa8t05g' ]
],
payments : [[ 10000, 'bcrt1qxemag7t72rlrhl2ezsnsprmunmnzc35nmaph6v' ]],
programs : [
[ 'endorse', 'dispute', '*', 1, '9997a497d964fc1a62885b05a51166a65a90df00492c8d7cf61d6accf54803be' ],
[ 'endorse', 'resolve', '*', 1, '9094567ba7245794198952f68e5723ac5866ad2f67dd97223db40e14c15b092e' ],
[ 'endorse', 'close|resolve', '*', 2,
'9997a497d964fc1a62885b05a51166a65a90df00492c8d7cf61d6accf54803be',
'4edfcf9dfe6c0b5c83d1ab3f78d1b39a46ebac6798e08e19761f5ed89ec83c10'
]
],
schedule : [[ 7200, 'close', 'payout|return' ]],
value : 100000,
version : 1
}
You can share this document peer-to-peer, or use a third-party for collaboration. The protocol is designed for third-party platforms to assist with negotiation and offer their own services (such as arbitration).
Once the terms have been decided, any member can deliver the final proposal to the escrow server. The server will validate all terms, then publish an open contract for funding.
> Note: The escrow server does not take part in negotiations. While BitEscrow may offer these services, the protocol is designed so that members can negotiate freely, without the server being involved.
---
To deposit funds into a contract, each funder requests a Deposit Account from the server. This account uses a 2-of-2 multi-signature address with a time-locked refund path.
`ts`
interface DepositAccount {
acct_id : string // Hash identifer for the account record.
acct_sig : string // Signature for the account record.
address : string // On-chain address for receiving funds.
agent_id : string // Identifier of the deposit agent.
agent_pk : string // Public key of the deposit agent.
created_at : number // Account creation timestamp (in seconds).
deposit_pk : string // Public key of the funder making the deposit.
sequence : number // Locktime converted into a sequence value.
spend_xpub : string // The extended key used for returning funds.
}
The funder independently verifies the account information, then sends their funds into the account address. Once the transaction is available in the mempool, the funder can register their deposit with the server.
To lock funds to a contract, the funder produces a batch of signatures, one for each spending path in the contract. These signatures authorize the contract to spend the deposit based on the contract terms. The combination of these signatures form a Covenant with the contract.
`ts`
interface CovenantData {
cid : string // Id of the contract you are signing for.
pnonce : string // Public nonce of the signer.
// List of labeled partial signatures for the covenant.
psigs : [ label : string, psig : string ][]
}
Once a covenant is made, the funds are locked to the contract. When enough funds have been confirmed, the contract becomes active.
---
The final round of the protocol is the settlement. This is the most exciting round, as members get to decide how the money shall be spent.
Each contract comes with a tiny virtual machine called a CVM. When the contract activates, this machine is initialized with the terms of the proposal:
`ts`
vm_state: {
commits : [],
error : null,
head : 'b70704c41e27d5f35a11ae7c6e5976501aa1380195714007197d7f47934dcf69',
output : null,
paths : [ [ 'payout', 0 ], [ 'return', 0 ] ],
start : 1706511301,
steps : 0,
store : [
[ '054fef5ba39416260ea4b48e9c557ee7e45d780d04b28e094d110459b971b78b', '[]' ],
[ 'cf236c4e91678bddaaa482d41720f277bb7d2e4540a0fc47736b999a54d29e39', '[]' ],
[ 'e7862cbeb981d295639af3e91661fc96e0f97b429e9ff2985d20a654667d167a', '[]' ]
],
status : 'init',
tasks : [ [ 7200, 'close', 'payout|return' ] ],
updated : 1706511301
}
A git-style hash chain is also created, starting with the contract's identifier (cid).
Members of the contract can interact with the CVM by submitting a signed statement, called a witness. Members use these statements to instruct the CVM to perform a basic set of operations.
Each operation targets a spending path in the contract. Operations include lock, release, close and dispute:
`ts`
// An example witness statement, endorsed with two signatures.
{
action : 'close',
args : [],
method : 'endorse',
path : 'tails',
prog_id : '054fef5ba39416260ea4b48e9c557ee7e45d780d04b28e094d110459b971b78b',
sigs : [
'effe19ba82f5451739b1d3471dae675c476147bab74e6654f1aaba82e2d96d9f...',
'f1b1d3a097db6acb76e9296e1e41db169a781813301b4853207ee3b6e39c72b9...'
],
stamp : 1706511302,
wid : '8859eb66bf8fd0d2868d74fefbbaf5f73408c9072c99b4d8df3348f1479bf5f5'
}
Every statement that updates the CVM is recorded into the hash-chain. This chain validates the full execution history of the machine, from activation to settlement:
`ts`
vm_state: {
commits: [[
// Position of the commit in the chain,
step : 0,
// UTC timestamp of the commit.
stamp : 1706511302,
// Previous head, before the commit.
head : 'b70704c41e27d5f35a11ae7c6e5976501aa1380195714007197d7f47934dcf69',
// The witness id of the statement being committed.
wid : '8859eb66bf8fd0d2868d74fefbbaf5f73408c9072c99b4d8df3348f1479bf5f5',
// The action that was performed.
action : 'close',
// The path that was evaluated.
path : 'tails'
]],
// The (now updated) head of the chain.
head: '41cf5e1a716067f9255580c96a808d5999c602fb2092b1789fb1ffb574c93597',
}
Once the CVM has evaluated a spending path, the server will complete the signatutes for the selected path, then settle the contract with a final transaction. Each member runs their own execution of the CVM and verifies that the contract settled correctly.
---
To demonstrate the flow of the protocol through various paths and outcomes, we'll walk through a sales agreement between three parties: Alice (the buyer), Bob (the seller), and Carol (third-party arbitrator).
Negotiation and Funding
1. Alice and Bob prepare a proposal, and agree on terms / arbitration.
2. Alice submits the proposal to the agent and receives a contract.
3. Alice deposits her funds with the contract agent, along with a covenant.
4. Once the deposit is confirmed on-chain, the contract becomes active.
Settle on Payout (happy path)
5. Alice receives her widget and forgets about Bob.
6. The contract schedule closes automatically on 'payout'.
7. Bob gets the funds, Alice can verify the CVM execution.
Settle on Refund (neutral path)
5. Alice doesn't like her widget.
6. Alice and Bob both agree to sign the 'refund' path.
7. Alice gets a partial refund, Bob still keeps his fees.
Settle a Dispute (unhappy path)
5. Alice didn't get the right widget, and disputes the payout.
6. Carol steps in, and decides on the 'refund' path.
7. Alice gets a partial refund, Bob still keeps his fees.
Contract Expires (ugly path)
5. Alice claims she didn't get a widget, and disputes the payout.
6. Carol is on a two-week cruise in the bahamas. No auto-settlement terms were set.
7. The contract expires, all deposits are released.
Deposits Expire (ugliest path)
5. Everything above happens, except the last part.
6. The entire escrow platform goes down in flames.
7. The timelock on deposits expire, Alice can spend via the refund path.
Even in a worst-case scenario, deposits are recoverable by the time-locked refund path.
---
A brief description of the security model:
* Each member participates using an anonymous credential. Credentials can be verified and claimed without revealing the owner to the escrow server.
* Members decide the terms of the proposal and all spending paths. The escrow server is not involved until the terms have already been finalized.
* Anyone can choose to endorse a proposal to publicize their support. Members do not reveal their credential by making an endorsement.
* Funders decide what transactions to sign and deliver to the escrow server. If there's a disagreement, funders can refund a deposit collaboratively or wait out the timelock.
* The escrow server cannot link funders to a member of the contract.
* The escrow server can only settle using transactions provided by funders.
* All parites independently verify the progression of the contract and final settlement. If the server settles a contract without a valid proof, their reputation is burned.
Some challenges with the current model:
* The escrow server has an ability to censor members of a contract by ignoring their statements. In the short term, we plan to mitigate this using time-stamped delivery receipts. In the long-term, we plan to support open platforms (such as nostr) where delivery can be independently verified.
* Even with the covenant restrictions, the burning of reputation may not be considered strong enough incentive. We are exploring additional options, such as the server staking some collateral.
In terms of security, speed, and simplicity, we believe this is the best non-custodial solution for providing programmable escrow contracts on Bitcoin.
---
Below is a step-by-step guide on how to negotiate, fund, and settle a contract in an example scenario. This guide includes a live demo that you can run on your own machine, with no special software required.
To run the demo, simply clone this repository, then run the following commands:
`sh`
npm install # Install all package dependencies.
npm run demo {chain} # Run the demo using the provided chain.
The current chains available are mutiny, signet, and testnet. The default chain is mutiny.
You can read more info about the demo here.
The EscrowClient is a basic client for consuming our API. It is designed for tasks which do not require providing an identity or signature.
Configuring a client requires specifying a network, a provider hostname, plus an oracle server for checking the blockchain.
`ts
import { EscrowClient } from '@scrow/core'
const client_config = {
// The URL to our escrow server.
hostname : 'https://bitescrow-signet.vercel.app',
// The URL to an electrum-based indexer of your choice.
oracle : 'https://mempool.space/signet',
// The network you are using.
network : 'signet'
}
// Create an EscrowClient using the above config.
const client = new EscrowClient(client_config)
`
For more detailed information on the EscrowClient class, check out the EscrowClient Wiki.
The EscrowSigner represents a member or depositor of a contract. It's used for negotiating a proposal, managing deposits and interacting with a contract's CVM.
For development, the fastest way to setup a new signer is to generate one randomly:
`ts
import { EscrowSigner } from '@scrow/core/client'
// Generate a new EscrowSigner from scratch.
const signer = EscrowSigner.generate(client_config, xpub)
`
For production, you may wish to import a key-pair using a raw seed or BIP39 seed words:
`ts
// Create an EscrowSigner using a raw seed.
const signer = EscrowSigner.create(client_config, seed, xpub)
// Import an EscrowSigner using a word list.
const signer = EscrowSigner
.import(client_config, xpub)
.from_words(seed_words, optional_password)
`
The EscrowSigner is built for insecure environments. All addresses are derived from the xpub, and all signed transactions are verified before deposit. The signing key has no direct access to funds, and can be tossed from memory once the contract and covenant are in place. All credentials generated by the signer can be independently recovered by the xpub.
However, the recovery process does require taking the xpub out of cold-storage, which may be inconvenient to the user.
For a better user experience, the EscrowScigner includes a password-protected backup and restore option for secure storage in a browser environment. There is also a more basic SignerAPI and WalletAPI which can be hosted outside the browser (in an extension or external app).
For more info on the EscrowSigner class, check out the EscrowSigner Wiki.
The proposal is a simple JSON document, and it can be built any number of ways.
`ts`
const proposal = {
title : 'Basic two-party contract with third-party arbitration.',
duration : 14400,
network : 'mutiny',
schedule : [[ 7200, 'close', '*' ]],
value : 10000,
}
To make the negotiation process easier, you can define intended roles within a proposal:
`ts`
const roles = [
{
title : 'buyer',
paths : [
[ 'heads', 10000 ],
[ 'draw', 5000 ]
],
programs : [
[ 'endorse', 'close', '*', 2 ],
[ 'endorse', 'dispute', 'heads|tails', 1 ]
]
},
{
title : 'seller',
paths : [
[ 'tails', 10000 ],
[ 'draw', 5000 ]
],
programs : [
[ 'endorse', 'close', '*', 2 ],
[ 'endorse', 'dispute', 'heads|tails', 1 ]
]
},
{
title : 'agent',
programs : [
[ 'endorse', 'resolve', '*', 1 ]
]
}
]
In order to handle negotiation between parties, we have developed a DraftData document which users can use to share and collaborate.
`ts`
interface DraftData {
// Signed approvals from each member, to signal readiness.
approvals : string[]
// A list of active members of the proposal, and their credentials.
members : MemberData[]
// The main proposal document being negotiated.
proposal : ProposalData
// List of roles defined for the proposal, and their requirements.
roles : RolePolicy[]
// Non-member endorsements of the proposal, used for indexing.
signatures : string[]
// A list of terms in the proposal which are negotiable.
terms : string[]
}
This document defines members and roles within the proposal, which terms are negotiable, and collects approvals from each member.
`ts
import { create_draft } from '@scrow/core/proposal'
import { signers } from './02_create_signer.js'
import { proposal, roles } from './03_create_draft.js'
// Unpack our list of signers.
const [ a_signer, b_signer, c_signer ] = signers
// Define our negotiation session.
export let draft = create_draft({ proposal, roles })
// For each member, add their info to the proposal.
draft = a_signer.draft.join(draft.roles[0], draft)
draft = b_signer.draft.join(draft.roles[1], draft)
draft = c_signer.draft.join(draft.roles[2], draft)
// For each member, collect an approval and (optional) endorsement.
signers.map(mbr => {
const approve = mbr.draft.approve(draft)
const endorse = mbr.draft.endorse(draft)
draft.approvals.push(approve)
draft.signatures.push(endorse)
})
`
Each endorsement provided to the server will tag the proposal with the signer's pubkey. This allows an to search for contracts via their main pubkey. Endorsing a proposal does not reveal which credential belongs to you.
For more information on building a proposal, click here.
Once you have a complete proposal, the next step is to create a contract:
`ts`
// Request to create a contract from the proposal (and optional signatures).
const res = await client.contract.create(proposal, signatures)
// Check that the response is valid.
if (!res.ok) throw new Error(res.error)
// Unpack and return the contract data.
const { contract } = res.data
The contract begins in a published state, and is ready for funding. You can share the contract with others by advertising its unique identifier, the cid.
For more info on how to use a contract, click here.
To make a deposit, we start by requesting a deposit account from the escrow server:
`ts`
// Define our deposit locktime.
const locktime = 60 * 60 // 1 hour locktime
// Get an account request from the signing device.
const acct_req = signer.account.request(locktime)
// Submit the request to the server
const acct_res = await client.deposit.request(acct_req)
// Check the response is valid.
if (!res.ok) throw new Error(res.error)
// Unpack the account data.
const { account } = res.data
Each account is a time-locked 2-of-2 multi-signature address between the funder's signing device, and a random signing agent from the server.
It is important that funders verify the account information is correct:
`ts`
// Verify the account.
const is_valid = signer.account.verify(account)
if (!is_valid) throw new Error('account is invalid!')
After verifying the account, funders can safely send funds to the account address. Once the transaction is visible in the mempool, we can grab the transaction's utxo data using an oracle:
`ts`
// Unpack the address from the account.
const { address } = account
// Fetch all utxos from the address.
const utxos = await client.oracle.get_address_utxos(address)
// There should be a utxo present.
if (utxos.length === 0) throw new Error('utxo not found')
// Get the output data from the utxo.
const utxo_data = utxos[0].txspend
The final step is to register the utxo with the escrow server, and provide a covenant that locks it to the contract. We can perform both actions using the commit method:
`ts`
// Create a commit request.
const commit_req = signer.account.commit(account, contract, utxo)
// Deliver the request to the server.
const res = await client.deposit.commit(commit_req)
// Check the response is valid.
if (!res.ok) throw new Error('failed')
// Unpack the response data, which should be the deposit and updated contract.
const { contract, deposit } = res.data
> For more info on managing a deposit, click here.
Once all required funds are deposited and confirmed, the contract virtual machine (CVM) will activate.
Members of the contract can interact with the CVM by providing signed statements, called a witness:
`ts`
// Start with a witness template.
const template : WitnessTemplate = {
action : 'close', // We want to close the contract.
method : 'endorse', // Using the 'endorse' (signature) method.
path : 'payout' // Settling on the 'payout' path.
}
Members can use their signing device to create a new statement, or endorse an existing statement from another member:
`ts`
// Example list of signers.
const [ a_signer, b_signer ] : EscrowSigner[] = signers
// Initialize a variable for our witness data.
let witness : WitnessData
// Alice signs the initial statement.
witness = a_signer.witness.sign(contract, template)
// Bob endoreses the statement from Alice.
witness = b_signer.witness.endorse(contract, witness)
These statements are submitted to the contract, and evaluated by the CVM. If the statement is valid, then the CVM will update its state, and the server will deliver an updated contract:
`ts`
// Submit the completed statement to the contract.
const res = await client.contract.submit(contract.cid, witness)
// Check the response is valid.
if (!res.ok) throw new Error(res.error)
// The returned contract should be settled.
const updated_contract = res.data.contract
If a spending condition is met within the CVM, the contract will be closed by the escrow server, and a settlement transaction will be broadcast.
The updated contract will record this information under spent_txid. We can view the settlement transaction using an oracle:
`ts`
// Get the transaction id from the contract.
const txid = settled_contract.spent_txid
// Fetch the settlement tx from the oracle.
const txdata = await client.oracle.get_txdata(txid)
// Print the transaction data to console.
console.dir(txdata, { depth : null })
And that is it! The on-chain transaction will look like an anonymous coin-join of single-key spends, and it can be fee-bumped by any recipient of the contract funds using CPFP.
For more information on contracts, the CVM, and settlement process, click here.
To get started, make sure you are running v19+ of node, then install the project dependencies using your node manager of choice:
`sh`
node --version # should be v19+
npm install # install dependencies
This project uses the following scripts:
`mdsrc
build : Compiles the contents of folder to dist.
demo
load