モチベーション

日本語文献の無い（現時点で）0xのOrderWatcherをコードベースで解説すること。間違い、ご意見あればTwitter経由でご連絡ください。

OrderWatcherとはなにか？

オーダーが「valid」なのか「Invalid」なのかを追跡、管理、確認するツール。
特定のオーダーを追跡し、オーダーのステータスが変更されるとEventを出力され、OrderWatcherで管理できる。
OrderaWatcherはdaemon的な役割を果たすのでユーザーのインターフェースからは意識されることはない。
リレイヤーがオーダーを取り除いたりトレーダーが特定のオーダーを取りに行ったりする時に使われる。例えば、 OrderWatcherが起動し、オーダーが追加されるとorderStateChangeが毎回出力される。

使い方

インストール
yarn add @0x/order-watcher

インストール後、所定のファイル内で
import { OrderWatcher } from '@0x/order-watcher';
をすることでorder-watcherをインポートすることができる。

@0x/order-watcherのメソッド

新しいインスタンスを生成する

constructor

new OrderWatcher(
  provider: Provider, 
  networkId: number, 
  contractAddresses?: ContractAddresses, 
  partialConfig: Partial<OrderWatcherConfig> = DEFAULT_ORDER_WATCHER_CONFIG, 
): OrderWatcher

Provider: JSON RPCを使用するためのWeb3プロバイダー
Network: オーダーが流れるネットワークID
contractAddress：networkIDに従ったコントラクトアドレス（任意で設定）
partialConfig: configuration（任意）

基本的なメソッド

addOrderAsync

orderWatcher.addOrderAsync(signedOrder: SignedOrder): Promise<void>

OrderWatcherにオーダーを追加する。オーダーを追加する前に署名が検証される。
signedOrder: watchingしたいオーダー

getStats

orderWatcher.getStats(): Stats

Orderwatcherのインスタンスを確認する。

removeOrder

orderWatcher.removeOrder(orderHash: string): void

orderWatcherからオーダーを取り除く。
orderHash: watchingをやめたいオーダーのオーダーハッシュ

expirationWatcher.subscribe(callback: (orderHash: string) => void): void

unsubscribe

expirationWatcher.unsubscribe(): void

これ以外のメソッドはこちらから確認。0xプロトコルのOrder Watcherを解説する（応用編）でも書く。

オーダーの検証

オーダーの検証は「valid」「Invalid」の2択ではなく、部分的に正しいということもありうる。つまり、部分的にfillされ、cancelされ、fillableになっているステータスなどもありうる。

例：filled | cancelled | unfunded | fillable

オーダーは、1つでもfillできる0でない値がある場合に、OrderWatcherによって「valid」と評価される。

上記の要項を満たすには以下の条件が必要である。

正当なデータ構造であること
正当な署名がある
有効期限内のものである
完全にfillもしくはcancelされているわけではない
Makerがトレードを行うのに十分な資金とAllowanceがある

validと評価されたオーダーの内、リレイヤーの採択によってどのオーダーを取り、どのオーダーを捨てるなどのロジックを作ることができる。その中でも、リレイヤーは以下の3つのロジックは確実に決めておかないといけないルールになっている。

指定した値以下の部分的にfillすることのできるオーダーを受け付けるかどうか
部分的にfillすることのできる値の最低値
griefingなどの問題を起こしたユーザーに罰則を与えるかどうか

OrderWatcherがデフォルトでもっているコントラクトのイベント

0x Exchange Event	Token Type
Fill
Cancel
CancelUpTo
Transfer	ERC20
Approval	ERC20
Transfer	ERC721
Approval	ERC721
ApprovalForAll	ERC721
Deposit	WETH
Withdraw	WETH

上記のイベントがオーダーの状態を変更すると変更記録が通知される。

検証記録の確認

OrderState

type OrderState = OrderStateValid|OrderStateInvalid`

でオーダーが「Valid」か「Invalid」かを判断できる。

ちなみに、「Valid」の場合

OrderStateValid

{
    isValid: true,
    orderHash: string,
    orderRelevantState: OrderRelevantState,
    transactionHash: undefined|string,
}

「Invalid」の場合

OrderStateInvalid

{
    error: ExchangeContractErrs,
    isValid: false,
    orderHash: string,
    transactionHash: undefined|string,
}

が返ってくる。

Invalidが返ってきた場合、よくある原因は

有効期限切れ
fillされていた
Makerがオーダーをcancelした
Makerのトークン残高が0を下回った

などがある。

その他のエラーはこちらから確認できる。

エラーが出たコントラクトオーダーはすぐにOrderBookより取り除いたほうが良い。

0xプロトコルのOrder Watcherを解説する（基礎編）