Client Functions

// client functions
Users place orders by constructing $\bar O$, proving this was done faithfully, and backing it with the appropriate tokens. Bids are backed with the $d$ token. Asks are backed with the $\chi$ token. 

$place(\phi, \chi, d, p, v)$
1. Sample $\alpha\leftarrow$$ $F$. Construct $O = \{s: (\phi, \chi, d), t: (p, v, \alpha)\}$.
2. Run witness generation for the $back$ circuit, assigning its outputs $\{\bar O, b\}$ to local variables.
6. Let $P$ be the predicate "reveal this order iff it is finalized on-chain AND the requester owns an opposing active order within the limit bounds". Send $O$ and $\bar O$ to Elliptic. We will attach the predicate $P$. Elliptic acknowledges the message and sends back the signature $\sigma = Sign(sk_{ellp}, \bar O)$.
11. Generate ZKP $\pi_{back} = P(pp_{back}.pkey, \bar O, b)$, where $pp_{back}.pkey$ is the proving key for our $back$ circuit.
12. Publish contract call $place(\pi_{back}, \bar O, b, \sigma)$ to the chain, along with the tokens specified in $b$.

After commiting to an order $O_{own}$, the user can request Elliptic for all crosses up to 3x the order volume. For instance, a bid for 1000 `LINK` will return at most 3000 `LINK` worth of crossed asks. The user selects the best $n$ orders that cross $\{O_i\}_{i=0}^n$. Consuming all orders involved settles the trade. Settling will seldom be exact. For that reason, we create $\bar O_{cho}$ for the change order of $O_{own}$ and $\bar O_{chn}$ for the change order of $O_n$. These change orders are analogous to [Bitcoin change addresses](https://support.blockchain.com/hc/en-us/articles/4417082392724-What-are-change-addresses-and-how-do-they-work-#:~:text=Change%20addresses%20are%20an%20aspect,of%20the%20output%20being%20spent.).

$fill(O_{own}, \{O_i\}_{i=0}^n)$
1. Run witness generation for the $fill$ circuit, assigning its outputs $\{\bar O_{own}, \{\bar O_i\}_{i=0}^n, b_{own}, \{b_i\}_{i=0}^n, O_n.p, \bar O_{cho}, \bar O_{chn}, O_{cho}, O_{chn}\}$ to local variables. 
9. Let $P$ be the predicate "reveal this order iff it is finalized on-chain AND the requester owns an opposing order within the limit bounds". Send $\{O_{cho}, O_{chn}, \bar O_{cho}, \bar O_{chn}\}$to Elliptic. We will attach the predicate $P$. Elliptic acknowledges the messages and sends back the signatures $\sigma_{cho} = Sign(sk_{ellp}, \bar O_{cho})$ and $\sigma_{chn} = Sign(sk_{ellp}, \bar O_{chn})$.
11. Optional. Use Elliptic's circom library to encrypt $O_{chn}$ under a key $k$ that's shared with the owner of $O_n$. Add $Enc(k, O_{chn})$ to the ZKP. Unnecessary to do in the first release.
12. Generate ZKP $\pi_{fill} = P(pp_{fill}.pkey, \bar O_{own}, \{\bar O_i\}_{i=0}^n, b_{own}, \{b_i\}_{i=0}^n, O_n.p, \bar O_{cho}, \bar O_{chn})$, where $pp_{fill}.pkey$ is the proving key for our $fill$ circuit. 
13. Publish contract call $fill(\pi_{fill}, \bar O_{own}, \{\bar O_i\}_{i=0}^n, b_{own}, \{b_i\}_{i=0}^n, O_n.p, \bar O_{cho}, \bar O_{chn}, \sigma_{cho}, \sigma_{chn})$ to the chain. 

Users can cancel their open orders and regain the tokens that back them. This is straightforward in our open ownership model. The user only needs to prove the backing amount and sign the transaction using the ETH account of the owner. Logic for cancelling an order has heavy symmetries to placing one, with the below client function even using the same $back$ circuit. 

$cancel(O)$
1. Run witness generation for the $cancel$ circuit, assigning its outputs $\{\bar O, b\}$ to local variables.
2. Generate ZKP $\pi_{back} = P(pp_{back}.pkey, \bar O, b)$, where $pp_{back}.pkey$ is the proving key for our $back$ circuit.
8. Publish contract call $cancel(\pi_{back}, \bar O, b)$, receiving the tokens specified in $b$.