diff --git a/packages/docs/src/spec/index.rst b/packages/docs/src/spec/index.rst index 21852271..235e4a81 100644 --- a/packages/docs/src/spec/index.rst +++ b/packages/docs/src/spec/index.rst @@ -64,6 +64,8 @@ This website documents the entirety of the Plasma Group design, from the inner w src/04-client-architecture/history-manager src/04-client-architecture/state-db src/04-client-architecture/state-manager + src/04-client-architecutre/sync-db + src/04-client-architecture/sync-manager src/04-client-architecture/rpc-client src/04-client-architecture/rpc-server diff --git a/packages/docs/src/spec/src/03-client/transaction-generation.rst b/packages/docs/src/spec/src/03-client/transaction-generation.rst index b8a26def..b011a3ad 100644 --- a/packages/docs/src/spec/src/03-client/transaction-generation.rst +++ b/packages/docs/src/spec/src/03-client/transaction-generation.rst @@ -49,6 +49,8 @@ Plasma transactions **must** be `ABI encoded or decoded`_ according to the follo ******************** Sending Transactions ******************** +The client **SHOULD** verify the `history`_ of the range being transacted before sending the transaction to the operator. Doing so will confirm that no `invalid transactions`_ have been maliciously inserted into the blockchain by the operator between the block in which the user received a state update and the latest block. Otherwise the client may have to start `limbo exit`_, which is more costly than a standard exit. + Transactions can be submitted to a node via the `sendTransaction RPC method`_. If the node that receives this request is not the operator, then it will forward the transaction to the operator on the requester's behalf. ********************************** diff --git a/packages/docs/src/spec/src/03-client/plugin-manager.rst b/packages/docs/src/spec/src/04-client-architecture/plugin-manager.rst similarity index 100% rename from packages/docs/src/spec/src/03-client/plugin-manager.rst rename to packages/docs/src/spec/src/04-client-architecture/plugin-manager.rst diff --git a/packages/docs/src/spec/src/04-client-architecture/predicate-plugin.rst b/packages/docs/src/spec/src/04-client-architecture/predicate-plugin.rst index c30e5a59..2f8a5a95 100644 --- a/packages/docs/src/spec/src/04-client-architecture/predicate-plugin.rst +++ b/packages/docs/src/spec/src/04-client-architecture/predicate-plugin.rst @@ -20,6 +20,9 @@ Plasma State Queries ==================== Predicate contracts on Ethereum can be fed information about the state of the plasma chain. Predicate plugins are therefore given a reference to `StateManager`_ and `HistoryManager`_ that permit the plugin to make queries about the existence (or non-existence) of a given `StateUpdate`_ in the plasma chain. +Plasma State Updates +==================== +Predicates **MUST** be able to insert state updates into the local plasma chain. Most predicates **SHOULD NOT** use this behavior, but certain predicates may require to function correctly. ------------------------------------------------------------------------------- diff --git a/packages/docs/src/spec/src/04-client-architecture/sync-db.rst b/packages/docs/src/spec/src/04-client-architecture/sync-db.rst new file mode 100644 index 00000000..806e5cd3 --- /dev/null +++ b/packages/docs/src/spec/src/04-client-architecture/sync-db.rst @@ -0,0 +1,127 @@ +###### +SyncDB +###### + +*********** +Description +*********** +``SyncDB`` is used by the `SyncManager`_ to store information about current synchronization statuses. + +------------------------------------------------------------------------------- + +*** +API +*** + +Methods +======= + +putLastSyncedBlock +------------------ + +.. code-block:: typescript + + async function putLastSyncedBlock( + plasmaContract: string, + block: number + ): Promise + +Description +^^^^^^^^^^^ +Sets the last block up to which the client has synchronized with a given plasma contract. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: ID of the plasma chain to set last block for. +2. ``block`` - ``number``: Last block up to which the client has synchronized. + +Returns +^^^^^^^ +``Promise``: Promise that resolves once the block has been set. + +getLastSyncedBlock +------------------ + +.. code-block:: typescript + + async function getLastSyncedBlock(plasmaContract: string): Promise + +Description +^^^^^^^^^^^ +Gets the last block up to which the client has synchronized with a given plasma contract. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: Contract to query the last synced block for. + +Returns +^^^^^^^ +``Promise``: Block up to which the client has synchronized. + +addSyncQuery +------------ + +.. code-block:: typescript + + async function addSyncQuery( + plasmaContract: string, + stateQuery: StateQuery + ): Promise + +Description +^^^^^^^^^^^ +Adds a `StateQuery`_ to the list of queries to execute for a given plasma contract. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: Contract to add a query for. +2. ``stateQuery`` - ``StateQuery``: Query to add for the contract. + +Returns +^^^^^^^ +``Promise``: Promise that resolves once the query has been added. + +removeSyncQuery +--------------- + +.. code-block:: typescript + + async function removeSyncQuery( + plasmaContract: string, + stateQuery: StateQuery + ): Promise + +Description +^^^^^^^^^^^ +Removes a `StateQuery`_ from the list of queries to execute for a given plasma contract. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: Contract to remove a query for. +2. ``stateQuery`` - ``StateQuery``: Query to remove for the contract. + +Returns +^^^^^^^ +``Promise``: Promise that resolves once the query has been removed. + +getSyncQueries +-------------- + +.. code-block:: typescript + + async function getSyncQueries( + plasmaContract: string + ): Promise + +Description +^^^^^^^^^^^ +Returns the `StateQuery`_ objects to execute for a given plasma contract. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: Contract to get sync queries for. + +Returns +^^^^^^^ +``Promise``: List of queries to execute for a given contract. + diff --git a/packages/docs/src/spec/src/04-client-architecture/sync-manager.rst b/packages/docs/src/spec/src/04-client-architecture/sync-manager.rst new file mode 100644 index 00000000..7bac3e78 --- /dev/null +++ b/packages/docs/src/spec/src/04-client-architecture/sync-manager.rst @@ -0,0 +1,105 @@ +########### +SyncManager +########### + +*********** +Description +*********** +``SyncManager`` runs in the background and automatically synchronizes the client's state with the operator's state. It watches for new block submissions and queries the operator for any relevant state updates. + +------------------------------------------------------------------------------- + +*** +API +*** + +Methods +======= + +getLastSyncedBlock +------------------ + +.. code-block:: typescript + + async function getLastSyncedBlock(plasmaContract: string): Promise + +Description +^^^^^^^^^^^ +Gets the last block up to which the manager has synchronized for a given plasma chain. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: ID of the plasma chain to get the last synced block for. + +Returns +^^^^^^^ +``Promise``: Block up to which the manager has synchronized. + +addSyncQuery +------------ + +.. code-block:: typescript + + async function addSyncQuery( + plasmaContract: string, + stateQuery: StateQuery + ): Promise + +Description +^^^^^^^^^^^ +Adds a `StateQuery`_ to the list of queries to call on a specific plasma chain when the synchronization loop triggers. Necessary because different predicates can be parsed in different ways and the manager needs to know what to look for. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: ID of the plasma contract to add a query for. +2. ``stateQuery`` - ``StateQuery``: `StateQuery`_ to add for that contract. + +Returns +^^^^^^^ +``Promise``: Promise that resolves once the query has been added. + +removeSyncQuery +--------------- + +.. code-block:: typescript + + async function removeSyncQuery( + plasmaContract: string, + stateQuery: StateQuery, + ): Promise + +Description +^^^^^^^^^^^ +Removes a `StateQuery`_ to the list of queries to call on a specific plasma chain when the synchronization loop triggers. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: ID of the plasma contract to remove a query for. +2. ``stateQuery`` - ``StateQuery``: `StateQuery`_ to remove for that contract. + +Returns +^^^^^^^ +``Promise``: Promise that resolves once the query has been added. + +.. _`StateQuery`: TODO + +getSyncQueries +-------------- + +.. code-block:: typescript + + async function getSyncQueries(plasmaContract: string): Promise + +Description +^^^^^^^^^^^ +Returns the list of active `StateQuery`_ objects the manager is using when the synchronization loop triggers. + +Parameters +^^^^^^^^^^ +1. ``plasmaContract`` - ``string``: Contract to get active queries for. + +Returns +^^^^^^^ +``Promise``: A list of `StateQuery`_ objects the manager is using. + +