Escrow

Escrow Smart Contract

Code: https://github.com/socious-io/midnight-escrow/

Purpose: Facilitates secure transactions by holding funds in a contract-controlled treasury until specific conditions are met.

Technical Specifications

• State Machine:

  • active: Funds are locked and ready for release.

  • released: Funds have been sent to the beneficiary.

  • refunded: Funds returned to the depositor (lifecycle state defined, logic implementation pending in snippet).

• Data Structure:

  struct Escrow {
      contributor: ZswapCoinPublicKey, // The party involved
      state: ESCROW_STATE,             // Current status
      amount: Uint<128>,               // Value locked
  }
  

Functions

• create(contributor, coin)

  • Action: Ingests a user's coin (receive), locks it in the contract's treasury (writeCoin), and generates a unique Escrow ID.

  • Privacy Note: The amount is disclosed publicly (disclose(coin.value)), but the transaction graph remains shielded via Z-swap.

export circuit create(
    contributor: ZswapCoinPublicKey,
    coin: CoinInfo
): Uint<32> {
    // Receive the coin into the contract
    receive(disclose(coin));

    // Store the coin in the treasury using writeCoin
    const contractAddress = right<ZswapCoinPublicKey, ContractAddress>(kernel.self());
    treasury.writeCoin(disclose(coin), contractAddress);

    // Increment escrow ID
    last_escrow_id = (last_escrow_id + 1) as Uint<32>;

    // Store escrow metadata
    const newEscrow = Escrow {
        contributor: disclose(contributor),
        state: ESCROW_STATE.active,
        amount: disclose(coin.value),
    };
    escrows.insert(disclose(last_escrow_id), newEscrow);

    return last_escrow_id;
}

• release(id)

  • Action: Checks if the escrow is active. If yes, transfers funds to the contributor address.

  • Change Management: Automatically calculates UTXO change. If the treasury coin is larger than the escrow amount, the remainder is written back to the treasury.

export circuit release(id: Uint<32>): [] {
    // Lookup escrow
    const e = escrows.lookup(disclose(id));
    assert(e.state == ESCROW_STATE.active, "Escrow not active");

    // Send funds to contributor
    const recipient = left<ZswapCoinPublicKey, ContractAddress>(e.contributor);
    const sendResult = send(treasury, recipient, e.amount);
    assert(sendResult.sent.value == e.amount, "Failed to send release payment");
// Handle change using writeCoin
    if (sendResult.change.is_some) {
        const contractAddress = right<ZswapCoinPublicKey, ContractAddress>(kernel.self());
        treasury.writeCoin(sendResult.change.value, contractAddress);  // Changed to writeCoin
    } else {
        treasury.resetToDefault();
    }

    // Update escrow state
    const updated = Escrow {
        contributor: e.contributor,
        state: ESCROW_STATE.released,
        amount: e.amount,
    };
    escrows.insert(disclose(id), updated);

    return [];
}

Developer Tutorials

Tutorial 1: Deploying the Escrow Contract

Prerequisite: A Midnight wallet (e.g., Lace) with tDUST for fees.

Step-by-Step Guide:

1. Setup Environment: Ensure you are running the Compact compiler version 0.16–0.18.

2. Deploy Contract: Run the deployment script. The contract constructor will initialize last_escrow_id to 0.

3. Witness Functions:

   • Warning: The current implementation requires careful handling of the release witness function. You must ensure queryContext.insertCommitment(commitment, index) is called to allow the runtime to locate the coin in the Merkle tree.

Tutorial 2: Creating an Escrow (Deposit)

Code Reference: export circuit create(...)

1. Prepare Coin Info: Select a coin from your wallet. You must pass the CoinInfo struct, including the nonce and value.

2. Call Circuit:

   // Pseudo-code example
   contract.create(
      beneficiaryPublicKey,
      myCoinData
   );
   

3. Verify: The contract will return a Uint<32> ID. Store this ID; you will need it to release funds.

Tutorial 3: Releasing Funds

Code Reference: export circuit release(...)

1. Input: Provide the Escrow ID.

2. Execution: The contract verifies the state is active.

3. Output: The recipient receives the funds. Any "change" from the input coin is securely returned to the contract treasury.