@greyw0rks/vault-escrow

JavaScript SDK for the VaultSTX trustless milestone escrow protocol on Stacks.

Install

npm install @greyw0rks/vault-escrow

Requires @stacks/transactions and @stacks/network as peer dependencies.

Overview

VaultSTX is a trustless milestone-based escrow protocol on Stacks. Clients lock STX, release it per milestone, and disputes are resolved by an on-chain arbitrator — no multisig, no off-chain coordination.

Deployed on Stacks Mainnet:

| Contract | Address | |---|---| | vaultstx-factory | SP1SY1E599GN04XRD2DQBKV7E62HYBJR2CT9S5QKK.vaultstx-factory | | vaultstx-escrow | SP1SY1E599GN04XRD2DQBKV7E62HYBJR2CT9S5QKK.vaultstx-escrow | | vaultstx-dispute | SP1SY1E599GN04XRD2DQBKV7E62HYBJR2CT9S5QKK.vaultstx-dispute |

Usage

Create an escrow

import { buildCreateEscrow } from '@greyw0rks/vault-escrow';
import { makeContractCall, broadcastTransaction } from '@stacks/transactions';

const txOptions = {
  ...buildCreateEscrow({
    provider: 'SP2...provider-address',
    totalAmount: 10_000_000n, // 10 STX in microSTX
    numMilestones: 3,
    description: 'Website redesign project',
  }),
  senderKey: privateKey,
  network,
};
const tx = await makeContractCall(txOptions);
await broadcastTransaction({ transaction: tx, network });

Read an escrow

import { getEscrow, getMilestone, getEscrowBalance, getNextEscrowId } from '@greyw0rks/vault-escrow';

const total = await getNextEscrowId();       // total escrows created
const escrow = await getEscrow(1);           // fetch escrow #1
const milestone = await getMilestone(1, 0);  // first milestone of escrow #1
const balance = await getEscrowBalance(1);   // locked STX in microSTX

Approve and release a milestone

import { buildApproveMilestone, buildReleaseMilestone } from '@greyw0rks/vault-escrow';

// Client approves milestone completion
const approve = buildApproveMilestone(1, 0); // escrowId=1, milestoneIndex=0

// Release payment to provider
const release = buildReleaseMilestone(1, 0);

Open and resolve a dispute

import { buildOpenDispute, buildResolveDispute, hasOpenDispute } from '@greyw0rks/vault-escrow/dispute';

const disputed = await hasOpenDispute(1);

const open = buildOpenDispute({
  escrowId: 1,
  client: 'SP1...client',
  provider: 'SP2...provider',
  disputedAmount: 5_000_000n,
  clientClaim: 3_000_000n,
  providerClaim: 2_000_000n,
  reason: 'Milestone deliverable not met',
});

// Arbitrator resolves
const resolve = buildResolveDispute({
  disputeId: 1,
  clientAward: 3_000_000n,
  providerAward: 2_000_000n,
  notes: 'Partial work completed',
});

API

Factory (@greyw0rks/vault-escrow)

| Function | Description | |---|---| | getEscrow(id, network?) | Fetch an escrow by ID | | getMilestone(escrowId, index, network?) | Fetch a milestone | | getEscrowBalance(id, network?) | Locked STX balance | | getTotalVolume(network?) | Cumulative STX escrowed | | getNextEscrowId(network?) | Total escrows created | | buildCreateEscrow(params) | Create a new escrow | | buildSetMilestone(params) | Define a milestone | | buildApproveMilestone(id, index) | Mark milestone complete | | buildReleaseMilestone(id, index) | Release milestone payment | | buildCancelEscrow(id) | Cancel an escrow |

Dispute (@greyw0rks/vault-escrow/dispute)

| Function | Description | |---|---| | getDispute(id, network?) | Fetch a dispute by ID | | getDisputeByEscrow(escrowId, network?) | Find dispute for an escrow | | hasOpenDispute(escrowId, network?) | Check for open dispute | | getTotalDisputes(network?) | Total disputes filed | | buildOpenDispute(params) | Open a dispute | | buildResolveDispute(params) | Resolve (arbitrator only) | | buildWithdrawDispute(id) | Withdraw an open dispute |

Constants

import { ESCROW_STATES, DISPUTE_STATES, FACTORY_LIMITS, ERROR_CODES } from '@greyw0rks/vault-escrow';

ESCROW_STATES.ACTIVE    // 1
ESCROW_STATES.COMPLETED // 2
ESCROW_STATES.CANCELLED // 3
ESCROW_STATES.DISPUTED  // 4

DISPUTE_STATES.OPEN     // 1
DISPUTE_STATES.RESOLVED // 2

FACTORY_LIMITS.MAX_MILESTONES      // 10
FACTORY_LIMITS.MAX_ESCROWS_PER_USER // 50

Links

• VaultSTX contracts
• npm package
• Stacks blockchain

License

MIT