Merge branch 'development'

README.md

@@ -1,10 +1,10 @@
 [![Integration Tests](https://github.com/BitEscrow/escrow-core/actions/workflows/integration.yml/badge.svg?branch=master)](https://github.com/BitEscrow/escrow-core/actions/workflows/integration.yml)
 
+> If you are looking to use the BitEscrow API, check out our [Developer Documentation](https://bitescrow.dev) resources and [Replit Container](https://replit.com/@cscottdev/escrow-core).
+
 # escrow-core
 
-A secure, private protocol for locking Bitcoin into a smart contract, with non-custodial escrow of funds.
-
-> If you are looking to use the BitEscrow API, check out our [Developer Documentation](https://bitescrow.dev) resources and [Replit Container](https://replit.com/@cscottdev/escrow-core).
+A secure, private protocol for locking Bitcoin to a smart contract, with non-custodial escrow of funds.
 
 Key Features:
 
@@ -18,6 +18,8 @@ Key Features:
 
   * __Designed to be robust.__ Deposits can be reused whenever a contract cancels or expires. Refund transactions are secured upfront and broadcast automatically on expiration.
 
+  * __Designed to scale.__ Deposits can be locked/released from a contract without being spent. Contracts have the option to settle or expire without an on-chain transaction.
+
 Package Features:
 
   * Full suite of methods and tools for every part of the protocol.

demo/07_deposit_funds.ts

@@ -54,7 +54,7 @@ await sleep(2000)
 const [ ival, retries ] = config.poll
 
 let tries  = 1,
-    txdata = await client.oracle.get_latest_utxo(address)
+    txdata = await client.oracle.get_first_utxo(address)
 
 // While there are no utxos (and we still have tries):
 while (txdata === null && tries < retries) {
@@ -63,7 +63,7 @@ while (txdata === null && tries < retries) {
   // Sleep for interval number of secords.
   await sleep(ival * 1000)
   // Check again for utxos at address.
-  txdata = await client.oracle.get_latest_utxo(address)
+  txdata = await client.oracle.get_first_utxo(address)
   // Increment our tries counter
   tries += 1
 }
@@ -79,7 +79,7 @@ if (DEMO_MODE) {
  * Request to register a utxo with the escrow server, plus a covenant
  * that locks the utxo to the specified contract.
  */
-const req = funder.account.commit(new_account, new_contract, ret_rate, txdata.txout)
+const req = funder.account.commit(new_account, new_contract, ret_rate, txdata.utxo)
 // Deliver our registration request to the server.
 const res = await client.account.commit(req)
 // Check the response is valid.

demo/09_submit_statements.ts

@@ -61,18 +61,18 @@ if (!res.ok) throw new Error(res.error)
  * The server will respond with a signed receipt. This receipt 
  * commits to our statement being evaluated by the machine.
  */
-const { commit, vmdata } = res.data
+const { receipt, vmdata } = res.data
 
 /**
  * We can use our local copy of the vmstate to verify that our
  * witness statement was handled correctly by the escrow server.
  */
 vmstate = engine.eval(vmstate, witness)
-client.witness.verify(commit, vmstate, witness)
+client.witness.verify(receipt, witness, vmstate)
 
 if (DEMO_MODE) {
   print_banner('witness receipt')
-  console.dir(commit, { depth : null })
+  console.dir(receipt, { depth : null })
 }
 
-export { commit, vmdata, witness }
+export { receipt, vmdata, witness }

demo/10_settle_contract.ts

@@ -44,7 +44,7 @@ if (DEMO_MODE) {
   await sleep(5000)
 
   // Fetch the settlement tx from the oracle.
-  const txdata = await client.oracle.get_tx_data(txid)
+  const txdata = await client.oracle.get_tx(txid)
   // Print the transaction data to console.
   console.dir(txdata, { depth : null })
 

demo/api/account/commit.ts

@@ -56,8 +56,8 @@ await sleep(2000)
 // Define our polling interval and retries.
 const [ ival, retries ] = config.poll
 // Poll for utxos from the account address.
-const data = await client.oracle.poll_address(deposit_addr, ival, retries, true)
-const utxo = data.txout
+const data = await client.oracle.poll_address(deposit_addr, ival, retries)
+const utxo = data.utxo
 
 print_banner('address utxo')
 console.log('utxo:', utxo)

demo/api/account/register.ts

@@ -60,8 +60,8 @@ await sleep(2000)
 // Define our polling interval and retries.
 const [ ival, retries ] = config.poll
 // Poll for utxos from the account address.
-const data = await client.oracle.poll_address(address, ival, retries, true)
-const utxo = data.txout
+const data = await client.oracle.poll_address(address, ival, retries)
+const utxo = data.utxo
 
 print_banner('address utxo')
 console.log('utxo:', utxo)

demo/api/machine/commits.ts

@@ -18,7 +18,7 @@ const res = await client.machine.commits(vmid)
 // Check the response is valid.
 if (!res.ok) throw new Error(res.error)
 // Unpack the data object.
-const { commits } = res.data
+const { receipt: commits } = res.data
 
 print_banner('machine statements')
 console.dir(commits, { depth : null })

demo/api/machine/submit.ts

@@ -46,10 +46,10 @@ const res = await client.machine.submit(witness)
 // Check the response is valid.
 if (!res.ok) throw new Error(res.error)
 // Unpack the data from the response.
-const { commit, vmdata } = res.data
+const { receipt, vmdata } = res.data
 
-print_banner('signed statement')
-console.dir(commit, { depth : null })
+print_banner('signed receipt')
+console.dir(receipt, { depth : null })
 console.log('\n')
 
 print_banner('updated machine')

demo/api/witness/list.ts

@@ -19,8 +19,8 @@ const res = await client.witness.list(req)
 // Check the response is valid.
 if (!res.ok) throw new Error(res.error)
 // Unpack our data payload.
-const { commits } = res.data
+const { receipts } = res.data
 
 print_banner('statement list')
-console.dir(commits, { depth : null })
+console.dir(receipts, { depth : null })
 console.log('\n')

demo/api/witness/read.ts

@@ -19,8 +19,8 @@ const res = await client.witness.read(wid)
 // Check the response is valid.
 if (!res.ok) throw new Error(res.error)
 // Unpack the data object.
-const { commit } = res.data
+const { receipt } = res.data
 
 print_banner('witness statement')
-console.dir(commit, { depth : null })
+console.dir(receipt, { depth : null })
 console.log('\n')

docs/api/account.md

@@ -5,8 +5,8 @@ Reference guide for the Escrow Account API.
 | Endpoint | Description |
 |----------|-------------|
 | [/api/account/request](#request-a-deposit-account) | Request a new deposit account. |
-| [/api/account/register](#register-a-deposit-utxo)  | Register a deposit of funds.   |
-| [/api/account/commit](#commit-a-deposit-utxo)      | Register funds for a contract. |
+| [/api/account/register](#register-a-deposit)       | Register a deposit of funds.   |
+| [/api/account/commit](#commit-a-deposit)           | Register funds for a contract. |
 
 ---
 > Notice any mistakes, or something missing? Please let us know!  
@@ -65,7 +65,7 @@ const { account } = res.data
 
 **Example Response**
 
-- [AccountData](../examples/accountdata.md)
+- [AccountData](../examples/AccountData.md)
 
 **Related Interfaces:**
 
@@ -128,12 +128,12 @@ const { deposit } = res.data
 
 **Example Response**
 
-- [DepositData](../examples/depositdata.md)
+- [DepositData](../examples/DepositData.md)
 
 **Related Interfaces:**
 
 - [DepositData](../data/deposit.md#deposit-data)
-- [TxOutput](../data/deposit.md#tx-output)
+- [TxOutput](../data/oracle.md#tx-output)
 
 ---
 
@@ -187,12 +187,12 @@ const { contract, deposit } = res.data
 
 **Example Response**
 
-- [ContractData](../examples/contractdata.md)
-- [DepositData](../examples/depositdata.md)
+- [ContractData](../examples/ContractData.md)
+- [DepositData](../examples/DepositData.md)
 
 **Related Interfaces:**
 
 - [ContractData](../data/contract.md#contract-data)
 - [CovenantData](../data/deposit.md#covenant-data)
 - [DepositData](../data/deposit.md#deposit-data)
-- [TxOutput](../data/deposit.md#tx-output)
+- [TxOutput](../data/oracle.md#tx-output)

docs/api/contract.md

@@ -67,7 +67,7 @@ const { contract } = res.data
 
 **Example Response**
 
-- [ContractData](../examples/contractdata.md)
+- [ContractData](../examples/ContractData.md)
 
 **Related Interfaces**
 
@@ -156,7 +156,7 @@ const { contract } = res.data
 
 **Example Response**
 
-- [ContractData](../examples/contractdata.md)
+- [ContractData](../examples/ContractData.md)
 
 **Related Interfaces**
 
@@ -203,7 +203,7 @@ const { contract } = res.data
 
 **Example Response**
 
-- [ContractData](../examples/contractdata.md)
+- [ContractData](../examples/ContractData.md)
 
 **Related Interfaces:**
 

docs/api/deposit.md

@@ -95,7 +95,7 @@ const { deposit } = res.data
 
 **Example Response**
 
-- [DepositData](../examples/depositdata.md)
+- [DepositData](../examples/DepositData.md)
 
 **Related Interfaces:**
 
@@ -209,7 +209,7 @@ const { deposit } = res.data
 
 **Example Response**
 
-- [DepositData](../examples/depositdata.md)
+- [DepositData](../examples/DepositData.md)
 
 **Related Interfaces:**
 
@@ -256,7 +256,7 @@ const { deposit } = res.data
 
 **Example Response**
 
-- [DepositData](../examples/deposit-data.md)
+- [DepositData](../examples/DepositData.md)
 
 **Related Interfaces:**
 

docs/api/machine.md

@@ -4,10 +4,10 @@ Reference guide for the virtual machine API.
 
 | Endpoint | Description |
 |----------|-------------|
-| [/api/machine/list](#list-machines-by-pubkey)          | List machines by pubkey.    |
-| [/api/machine/submit](#submit-a-witness-statement)     | Submit a new statement.     |
-| [/api/machine/:vmid](#read-a-machine-by-id)            | Fetch a machine by ID.      |
-| [/api/machine/:vmid/commits](#list-machine-statements) | List statements by machine. |
+| [/api/machine/list](#list-machines-by-pubkey)         | List machines by pubkey.  |
+| [/api/machine/submit](#submit-a-witness-statement)    | Submit a new statement.   |
+| [/api/machine/:vmid](#read-a-machine-by-id)           | Fetch a machine by ID.    |
+| [/api/machine/:vmid/receipts](#list-machine-receipts) | List receipts by machine. |
 
 ---
 > Notice any mistakes, or something missing? Please let us know!  
@@ -84,8 +84,8 @@ interface VMSubmitRequest {
 ```ts
 export interface VMSubmitResponse {
   data : {
-    commit : WitnessCommit
-    vmdata : MachineData
+    receipt : WitnessReceipt
+    vmdata  : MachineData
   }
 }
 
@@ -111,15 +111,15 @@ const res = await client.machine.submit(vmid, witness)
 // Check the response is valid.
 if (!res.ok) throw new Error(res.error)
 // Unpack the data from the response.
-const { commit, vmdata } = res.data
+const { receipt, vmdata } = res.data
 ```
 
 > See the full code example [here](https://github.com/BitEscrow/escrow-core/tree/master/demo/api/machine/submit.ts).
 
 **Related Interfaces:**
 
 - [MachineData](../data/machine.md#machine-data)
-- [WitnessCommit](../data/witness.md#witness-data)
+- [WitnessReceipt](../data/witness.md#witness-receipt)
 
 ---
 
@@ -159,31 +159,31 @@ const { vmdata } = res.data
 
 **Example Response**
 
-- [MachineData](../examples/vmdata.md)
+- [MachineData](../examples/MachineData.md)
 
 **Related Interfaces**
 
 - [MachineData](../data/machine.md#machine-data)
 
 ---
 
-## List Machine Statements
+## List Machine Receipts
 
-Request all witness statements for a virtual machine.
+Request all witness receipts for a virtual machine.
 
 **Request Format**
 
 ```ts
 method   : 'GET'
-endpoint : '/api/machine/:vmid/commits'
+endpoint : '/api/machine/:vmid/receipts'
 ```
 
 **Response Interface**
 
 ```ts
 interface WitnessListResponse {
   data : {
-    commits : WitnessCommit[]
+    receipts : WitnessCommit[]
   }
 }
 ```
@@ -196,11 +196,11 @@ const res = await client.machine.commits(vmid)
 // Check the response is valid.
 if (!res.ok) throw new Error(res.error)
 // Unpack the data object.
-const { commits } = res.data
+const { receipts } = res.data
 ```
 
 > See the full code example [here](https://github.com/BitEscrow/escrow-core/tree/master/demo/api/machine/commits.ts).
 
 **Related Interfaces:**
 
-- [WitnessCommit](../data/witness.md#witness-commit)
+- [WitnessReceipt](../data/witness.md#witness-receipt)