Project TXA allows for cross-chain trading via an off-chain orderbook and on-chain settlement.

We refer to the orderbook operator as the "participating interface or PI". Its role is akin to a centralized sequencer and transaction executor in an optimistic rollup. It detects on-chain contract events created by traders interacting with the `Portal` contract and off-chain orders submitted to the PI directly. It uses both to generate its own sequence of events that are broadcast to the validator.

Messages sequenced by the PI are validated, packaged into state roots, and proposed to the `Rollup` contract on the processing chain by the validator. The validator also

For the current version of the contracts, there is only one validator. It should be assumed that the validator is behaving properly and not committing fraud.

## Trader Interaction
- Traders deposit a token or native asset into a `Portal` contract deployed on the same chain as the asset. Every chain supported by the protocol is called an asset chain. We will initially support Ethereum, Polygon, and Arbitrum One as asset chains.
- An event containing the deposit info is emitted and detected by the PI. The PI updates the trader's available balance of the asset in its orderbook. It signs and broadcasts a sequenced message that includes the balance update and record of deposit to the validator.
- The validator detects both the contract event and the broadcasted message and checks that the balance update is correct.
- Trader uses the same address that deposited to sign an off-chain message representing a limit order and sends it to the PI.
- When the PI matches two trader-signed orders, it generates a trade and broadcasts it to the validator.
- The validator checks that the balance update in the trade is correct.
- Note that the PI can choose to reject a deposit. Rejected deposits should be returned to the depositor without any fees taken out. They are processed similar to how settlements are processed.
- The trader can then use that same address to request settlement of an asset by sending a transaction to the `Portal` contract. e.g. If the trader deposited ETH on Ethereum and traded it for MATIC on Polygon, the trader would call `requestSettlement` on the `Portal` contract deployed to Polygon.
- The PI detects the contract event and generates a sequenced message that includes the trader's last balance of MATIC. This message is broadcast to the validator.
- The validator compares the broadcasted message with the contract event, and checks that the balance is correct based on the history of deposits and trades that have been broadcast so far.

## Validator Interaction
- Validators report state roots to the `Rollup` contract deployed on the processing chain. We intend to use Arbitrum Nova as the processing chain.
- The validator constructs merkle trees containing messages broadcast by the PI. The order of the leaves should match the sequence number of the messages. It then submits a transaction of the merkle root to propose the state root for that epoch.
- The submitted state root is subject to a fraud period during which other validators can submit a fraud proof showing that either the PI or the proposing validator committed fraud. (This is not implemented or in scope for the beta version of the protocol).
- After the fraud period passes, the state root is confirmed and can be used to process settlements or claim trading fees.
- To process settlements, the validator submits merkle proofs of `Settlement` messages included in the state root. Based on the data in the message, the `Rollup` contract performs some validation and then an obligation is generated. The obligation allows a trader to withdraw funds on that chain. e.g. If Alice deposits 1 ETH, submits orders to sell all of the ETH for a total of 2,500 MATIC, and then requests settlement for MATIC, the obligation should be for 2,500 MATIC (minus a settlement fee). The obligation is then relayed from Arbitrum Nova to MATIC via LayerZero. The `ProcessingChainLz` contract on Arbitrum Nova sends the request to LayerZero, which relays it to the `AssetChainLz` contract on Polygon.
- After settling, the trader should be able to withdraw the funds from the `Portal` contract on the asset chain.
- To process trade fees, the participating interface submits merkle proofs of `Trade` messages included in the state root. Every `Trade` message includes a maker and taker fee, and that data is used to generate and relay obligations, similar to above.

## Staking
- Anyone can stake USDT (stablecoin) and TXA (protocol token) on Arbitrum Nova for the validator to use as collateral. The collateral is used when processing settlements for a state root which has not yet passed the fraud period. e.g. if processing a settlement for 1 ETH requires locking an equivalent value of USDT (based on oracle price) and an additional 15% of that in TXA. A portion of the settlement fee is split amongst the stakers with funds in the contract when the settlement was processed.
- Rewards are earned in the asset being settled. e.g. a settlement for ETH results in a portion of that ETH going to stakers. Stakers can then submit a transaction to the `Staking` contract to claim rewards earned from settlements. These are relayed from Arbitrum Nova to the asset chain of the reward as obligations. After claiming rewards, the staker should be able to withdraw the funds on the asset chain.
- When collateral is locked for a settlement, an identifier is generated to associate it with the state root which includes the settlement. Once the state root passes the fraud period, the collateral becomes unlocked and can be used for another settlement.
- When staking, stakers choose a tranche, which determines when the staked asset becomes unlocked, using a block number.
- Validators must also lock some TXA as collateral when proposing a state root.

## Threat Models

### ProcessingChainManager
- only participating interface can propose and activate new trading fees
- all other write functions are restricted to the admin address

### AssetChainManager
- all write functions are restricted to the admin address

### Portal
- No address should be able to withdraw funds meant for another address.
- No address besides the `AssetChainLz` contract is allowed to write obligations or reject deposits.
- generating a deposit record must mean that the same amount of the asset was actually sent to the contract
- Must not allow depositing an asset which was not approved in the AssetChainManager contract
- Must not allow deposits if the contract is paused by the admin
- Only admin can pause deposits

### Rollup
- Only validators can propose state roots, confirm state roots, process settlements, or process deposit rejections
- Only participating interface can process trading fees
- Validator cannot process a settlement if it was not included in a state root
- settlement can only be processed once
- if a state root has not passed fraud period, processing a settlement must lock collateral in the Staking contract

### AssetChainLz
- Must not accept messages from any chain other than the processing chain
- Must not accept messages from any contract other than the `ProcessingChainLz` contract deployed on the processing chain

### ProcessingChainLz
- Must not allow any address other than the Staking contract or Rollup contract to submit relays

### Staking
- Must not allow any address other than the original depositor to withdraw staked asset
- Rewards must be split amongst

### Oracle
- only reporters are allowed to report prices
- cannot report price if the asset was not approved in ProcessingChainManager contract