diff --git a/docs/chinese.md b/docs/chinese.md index 46cdca44..984e1545 100644 --- a/docs/chinese.md +++ b/docs/chinese.md @@ -1,9 +1,9 @@ -# Loopring Relay(中继) 中文文档 -Loopring Relay(中文名:中继)是路印技术生态重要组成部分，集中管理线下订单池，广播和撮合路印订单的同时，提供完整的交易所和钱包后端服务。在中心化系统的基础上，我们通过订单广播系统，将订单共享到多个中继，实现全网订单池。本文档主要介绍路印中继内部如何工作;第三方合作伙伴如何接入中继;如何自己部署中继加入路引生态，这三部分内容。 +# Loopring Relay（中继）中文文档 +“中继”是路印协议技术生态的重要组成部分，主要功能包括：管理链外订单池、广播订单、撮合订单，同时向去中心化交易所和上层钱包等入口提供完整的后端服务。其在中心化系统的基础上，通过广播订单的概念，将所有订单广播到其他中继，实现了全网共享订单池。本文档将重点介绍中继如何工作、如何接入、如何部署这三部分内容。 -## 相关文档 -* [部署文档](deploy/deploy_index_cn.md) -* [docker文档](relay_docker_cn.md) +## 部署文档 +* [aws部署文档](deploy/deploy_index_cn.md) +* [docker部署文档](relay_docker_cn.md) *** @@ -20,25 +20,17 @@ Loopring Relay(中文名:中继)是路印技术生态重要组成部分，集中 - [功能介绍](#功能介绍) * [订单管理](#订单管理) * [账户管理](#账户管理) - * [交易&撮合](#交易和撮合) + * [交易&撮合](#交易与撮合) * [交易所行情](#交易所行情) * [元信息](#元信息管理) -- [如何接入官方中继](#如何接入官方中继) +- [如何接入中继](#如何接入中继) * [jsonrpc](#jsonrpc) * [socketio](#socketio) * [sdk](#sdk) * [测试环境](#测试环境) -- [如果部署中继](#如何部署中继) - * [代码编译](#代码编译) - * [配置文件](#配置文件) - * [docker镜像](#docker) -- [分布式中继](#分布式中继) - * [github代码结构](#github) - * [微服务介绍](#微服务介绍) - * [谁更适合部署分布式版本](#谁更适合部署分布式版本) - * [docker镜像](#分布式版本镜像) - * [分布式版本自定义部署](#分布式版本自定义部署) - * [配置文件](#分布式中继配置) +- [如何部署中继](#如何部署中继) +- [github](#github) +- [微服务介绍](#微服务介绍) - [获取帮助](#获取帮助) --- @@ -47,30 +39,30 @@ Loopring Relay(中文名:中继)是路印技术生态重要组成部分，集中 分类 | 名词 | 解释 ------|------|------ -订单 | Order | 符合Loopring protocol格式的订单数据 -订单 | OrderHash | 订单的签名，即由订单部分字段做执行散列算法后生成的摘要 -订单 | Owner | 订单所有者，即用户钱包地址 -订单 | OrderType | 订单类型，Relay支持的两种订单订单类型 : market_order( 市场订单)，是整个交易所订单池共享的订单，可以被任何人成交; p2p_order(点对点订单)，是不包含钱包认证私钥的订单，只能够被授权共享了钱包认证私钥的用户才能撮合。 -订单 | WalletAddress | 提供订单的钱包分润地址，通常是钱包或者交易所产品研发团队的钱包地址，用来参与订单成功撮合后的利润分成，目前方案是，钱包会分取撮合利润的20%，撮合者(Miner)会分取撮合利润的80%。 -订单 | AuthAddr & AuthPrivateKey | 提交订单时，随机生成的公私钥对，AuthAddr用来参与订单的签名，AuthPrivateKey用来参与提交撮合时环路的签名，目的是为了防止订单或者环路被篡改，同时在点对点订单的场景，AuthPrivateKey在通过二维码只分享给特定用户的情况下，可以保护订单只被单独用户吃单。 -订单 | TokenS | 要出售的Token, 请参考支持的Token列表 -订单 | TokenB | 要买入的Token，请参考支持的Token列表 -订单 | AmountS | 要出售的Token数量 -订单 | AmountB | 要买入的Token数量 -订单 | ValidSince | 订单生效开始时间，表示单位为时间戳，如果当前时间小于ValidSince，订单是未生效状态。 -订单 | ValidUntil | 订单有效截止时间，表示单位为时间戳，超过后订单自动失效。 +订单 | Order | 符合Loopring protocol格式的订单数据。 +订单 | OrderHash | 订单的签名，由订单部分字段进行散列算法后生成的摘要。 +订单 | Owner | 订单的所有者，即用户的钱包地址。 +订单 | OrderType | 订单类型，中继支持两种订单类型: market_order( 市场订单)是整个交易所订单池共享的订单，可以被任何人成交；p2p_order(点对点订单)是不包含钱包认证私钥的订单，只能被授权共享了钱包认证私钥的用户才能撮合，且点对点订单不会展示到最新挂单之中。 +订单 | WalletAddress | 分润地址，通常是钱包或交易所等产品研发团队的地址，用来接收订单成功撮合后的利润分成，目前的方案是：钱包或交易所获得整个撮合利润的20%，撮合者(Miner)则获得剩余的80%。 +订单 | AuthAddr & AuthPrivateKey | 用来防止订单或环路被篡改，AuthAddr用来给订单签名，AuthPrivateKey则用来给环路签名，同时在p2p交易的场景下，将订单通过二维码分享给指定用户时，AuthPrivateKey还可以保护订单只被对方成交。 +订单 | TokenS | 欲出售的Token, 参考Token列表（token.json） +订单 | TokenB | 欲买入的Token，参考Token列表（token.json） +订单 | AmountS | 欲出售的Token数量 +订单 | AmountB | 欲买入的Token数量 +订单 | ValidSince | 订单生效开始时间，采用时间戳表示，若当前时间小于ValidSince，则订单处于未生效状态。 +订单 | ValidUntil | 订单有效截止时间，采用时间戳表示，超过该时间后订单将自动失效。 订单 | LrcFee | 设置该笔订单撮合需要的LrcFee -订单 | buyNoMoreThanAmountB | 表示是否允许购买超过amountB数量的tokeB，比如当前市场卖价(LRC-WETH)是0.001，用户下单价格是0.002买入100个（需要0.2个WETH），如果buyNoMoreThanAmountB=true，那最终用户会以0.001的价格（不考虑撮合收益）购买到100个LRC，消耗0.1个WETH；如果buyNoMoreThanAmountB=false，那最终用户会消耗掉所有的WETH（0.2个）以0.001的价格（不考虑撮合收益）购买到200个LRC。 +订单 | buyNoMoreThanAmountB | 是否允许购买超过amountB数量的tokeB，例如：当前市场LRC-WETH的卖价是0.001，某用户以0.002的价格下单买入100个（消耗0.2个WETH），如果buyNoMoreThanAmountB=true，最终用户会以0.001的价格（不考虑撮合收益）购买到100个LRC，仅消耗0.1个WETH；但如果buyNoMoreThanAmountB=false，则会消耗掉该用户所有的WETH（0.2个）以0.001的价格（不考虑撮合收益）购买到200个LRC。 订单 | marginSplitPercentage | 撮合分润中用来支付撮合费的比例，通常默认是50%。 -订单 | v, r, s | 订单签名的结果，是首先采用Keccak256算法对订单部分字段生成OrderHash, 再针对Hash做ECDSA签名，生成的结果。 -订单 | powNonce | 订单提交工作量证明，为了防止订单子系统被spam，我们采用工作量证明的方式来限制过多的订单提交，powNonce参与工作量证明算法计算，订单通过工作量证明校验后，提交到Relay，我们会以相同的工作量证明算法来校验nonce是否通过了工作量证明。 -订单 | 撮合 | 即两个以上订单满足形成Loopring环路的条件，可以形成环形成交，环形成交即Loopring的撮合。 -订单 | 环路 | 相对于传统交易所订单两两互相成交，Loopring可以针对多笔订单串联形成环形成交队列，这个环形头尾相连的订单队列，即环路。 -订单 | 软取消 | 在Loopr2版本的钱包中，用户取消订单只能提交到智能合约，不仅花费油费，而且不能即时取消。所以我们在Relay中增加了软取消功能，在满足软取消情况(比如订单未撮合或者未在撮合流程中)下，可以通过Relay取消订单，不消耗油费并且即时取消订单。 -账户 | Allowance | 代币授权，这里通常指的是用户授权给Loopring protocol，想要Loopring智能合约能够撮合用户订单，只有用户针对合约做授权操作后，Loopring智能合约才能够撮合用户订单。 -账户 | Balance | 用户资产余额，包含ETH余额和所有ERC20 Token余额。 -账户 | WETH | WETH是以太坊上锚定ETH的ERC20 Token，在没有任何额外费(除了一笔transaction油费)用情况下，永远可以和ETH等量交换，Loopring合约只支持ERC20 Token之间资产交换，并不支持ETH和ERC20 Token交换，所以在用户交易前，需要将ETH转换成WETH，同时授权Loopring合约使用WETH Token. -市场 | Fill | 成交信息，环路撮合后，智能合约发出的成交数据Event +订单 | v, r, s | 订单签名的结果，先对订单部分字段采用Keccak256算法生成OrderHash, 再对OrderHash做ECDSA签名的结果。 +订单 | powNonce | 订单提交工作量证明，为了防止订单子系统被spam，我们采用工作量证明的方式来限制过多的订单提交，powNonce会参与工作量证明算法的计算，订单通过算法校验后被提交到中继，中继接收到订单后会以相同的算法来校验nonce是否通过了工作量证明。 +订单 | 撮合 | 两个以上订单满足形成Loopring环路的条件，可形成环形成交，环形成交即Loopring的撮合。 +订单 | 环路 | 相比传统交易所订单两两互相成交的方式，Loopring可针对多笔订单串联，形成环形成交队列，这个头尾相连的环形订单队列就统称为环路。 +订单 | 软取消 | 在初期版本的钱包中，用户取消订单只能提交到智能合约进行处理，不仅花费油费，而且还不能即时取消。后来在Relay中开发了软取消功能，在满足软取消情况(比如订单未撮合或者未在撮合流程中)下，可通过Relay取消订单，不消耗油费，还能即时取消订单。 +账户 | Allowance | 代币授权，用户授权给Loopring protocol，只有对智能合约进行授权后，合约才有权撮合用户的订单。 +账户 | Balance | 用户资产余额，ETH余额和所有ERC20 Token余额的总和。 +账户 | WETH | 以太坊上锚定ETH的ERC20 Token，由于路印智能合约只支持ERC20 Token之间的资产交换，而ETH并非ERC20 Token，所以在交易前需将ETH转换为WETH，同时对WETH进行代币授权，WETH与ETH之间为等量交换（除了一笔油费）。 +市场 | Fill | 成交信息，环路撮合后，由智能合约发出的成交数据Event 市场 | Depth | 市场深度 市场 | Ticker | 24小时市场变化统计数据 市场 | Trend | 市场变化趋势信息，目前支持最小维度1Hr @@ -80,115 +72,115 @@ Loopring Relay(中文名:中继)是路印技术生态重要组成部分，集中 合约 | LoopringProtocolImpl | Loopring入口合约地址，伴随着合约升级，地址会有变化 合约 | DelegateAddress | Delegate合约地址，订单池按照Delegate合约划分，不同Delegate地址的订单之间，不能互相撮合。 通用 | Token | 即以太坊上代币，目前只支持完全符合ERC20标准的Token -通用 | Transaction | 通常是指用户转账/授权/合约调用等以太坊交易操作，在Relay，我们对transaction进行了包装，包含用户订单撮合类型，同时包含所有以太坊交易操作类型，方便用户区分。 -通用 | Gas | 提交以太坊交易，需要指定GasPrice和GasLimit用来支付交易产生的费用，Loopring支持获取当前网络最佳GasPrice +通用 | Transaction | 指用户转账/授权/合约调用等以太坊交易操作，在Relay中，对transaction进行了封装，包含了用户订单撮合类型与所有以太坊交易操作类型，方便用户区分。 +通用 | Gas | 提交一笔交易需要指定GasPrice和GasLimit，用来支付交易产生的费用，Loopring支持获取当前网络最佳GasPrice 通用 | Nonce | 以用户钱包地址为单位，从0开始递增的整数，当前值等于用户提交成功的transaction总数，用户提交transaction需要提供nonce做校验，同一个nonce只能有一个transaction提交成功，由于Relay接入了Loopring众多的钱包版本（web/ios/android）, 同时有多个合作伙伴接入，所以提供了集中维护Nonce的功能，最大程度的提高transaction成功率。 -通用 | Miner | Loopring撮合服务，在订单池中发现环路，并提交到智能合约撮合。 -通用 | Decimal | ERC20 Token 单位精度，一般情况下订单里Token数量除以Decimal, 是实际数量，通常Decimal=1e18。 -通用 | Symbol | ERC20 Token简称，例如Loopring ERC20 Token, 是LRC。 +通用 | Miner | Loopring撮合服务，在订单池中发现环路，并提交到智能合约进行撮合。 +通用 | Decimal | ERC20 Token 单位精度，一般情况下订单的Token数量除以Decimal等于实际数量，通常Decimal=1e18。 +通用 | Symbol | Token简称，例如Loopring ERC20 Token成为“LRC”。 --- ## 中继如何工作 -### 路印生态 -路引协议目前基于以太坊智能合约实现了链上环路撮合，链下订单池由一个个中继单独维护，为了实现全网订单池整合，提供更高代币流动性，我们通过订单广播的方式，连接所有中继，来实现全网订单的互通有无。中继可以通过订单广播，和其他中继交换订单，同时Loopring旷工(Miner), 可以订阅多个中继的订单，订单广播将所有中继和Miner连接起来，形成更大的(相对于单个中继)订单池。 +### 基本原理 +路引协议从基本构造上可拆解为“链上清算”与“链下撮合”两个部分，其中链上清算是基于智能合约来完成，而链下撮合则由后端中继来完成。每一个中继都维护着一个独立的订单池，为了提供更高的代币流动性，中继之间可通过不断广播的方式来进行订单交换和订单共享，最终实现全网订单的互通有无。 --- ### 系统架构 -中继作为中心化的钱包和交易所后台系统，具有合乎常理的中心化系统分层架构： +中继作为钱包与交易所的后端系统，具有合乎常理的中心化系统分层架构，主要分为如下四层： -* 系统接入层，对外提供钱包和交易所服务的接口层，支持jsonrpc 2.0 和socketio。 -* 业务逻辑层，包含各个业务逻辑接口和具体实现。 -* 存储层，包含缓存和持久化存储，缓存接入Redis，持久化存储我们同时选择了kv存储(Redis)和关系型存储系统(Mysql), Redis用来存储适合kv查询并且对查询性能要求比较高的数据，比如用户账户余额，Mysql用来存储查询相对复杂的数据，比如用户的订单/交易信息。 -* 广播层，用来传播订单。 +* 系统接入层：对外提供钱包和交易所服务的接口层，支持jsonrpc 2.0 和socketio。 +* 业务逻辑层：包含各个业务逻辑接口和具体实现。 +* 存储层：包含缓存和持久化存储，缓存接入Redis，持久化存储我们同时选择了kv存储(Redis)和关系型存储系统(Mysql)两种方式, 其中Redis用来存储适合kv查询并且对查询性能要求比较高的数据，如用户余额等，而Mysql则用来存储查询相对复杂的数据，如用户的订单/交易信息等。 +* 广播层：用来传播订单。 --- ### 钱包后台 -钱包后台用来支撑钱包相关的服务，包括用户账户余额&授权额度，交易数据，钱包nonce, cutoff信息等。 +该服务用来支撑钱包相关的功能，包括用户余额、授权额度、交易数据、钱包nonce和cutoff信息等。 --- ### 交易所后台 -交易所后台服务用来支撑交易所相关的功能，包括交易所订单池、成交信息、环路信息、市场趋势图/k线数据、深度/orderbook、 全球/第三方交易所行情等。 +该服务用来支撑交易所相关的功能，包括交易所订单池、成交信息、环路信息、市场趋势图/k线数据、深度/orderbook、 全球/第三方交易所行情等。 --- ### 基础服务 -提供中继和以太坊一些基础配置信息，比如以太坊预估gasPrice, 中继支持的合约列表，中继支持的代币列表，市场对列表等。 +提供中继与以太坊的一些基础配置信息，包括以太坊预估gasPrice、中继支持的合约列表、中继支持的代币列表、交易对列表等。 --- ### 以太坊解析服务 -以太坊解析服务用来将链上数据持久化以及缓存到中继，包括block/transaction/event等原始数据，同时解析交易和事件，形成业务分类，再持久化到中继，根据交易或者事件更新用户的余额，订单，成交信息。解析服务同时要处理频繁发生以太坊分叉。 +监听链上block/transaction/event等原始数据，同时解析交易和事件，形成业务分类，将链上数据持久化并且缓存到中继，并根据交易或事件更新用户的余额、订单、成交信息等。解析服务同时还要处理频繁发生的以太坊分叉。 --- -### 交易和撮合服务 -根据Loopring协议白皮书描述，Loopring订单是在链下撮合，链上清算的撮合系统，链下撮合即Miner在链下发现环路，链上清算即Miner将发现的环路提交到Loopring智能合约，链上完成清算，并将交易所得代币发送给用户和分润地址。中继的撮合服务即发现环路并提交智能合约的服务。 +### 交易与撮合服务 +根据白皮书的描述，每笔交易都需要经过链下撮合与链上清算两个步骤才算完成，链下撮合即Miner在链下发现环路，链上清算即Miner将发现的环路提交到智能合约进行上链结算，并将交易所得代币分发给交易双方及分润地址。撮合服务即发现环路并提交给智能合约的服务。 --- ## 功能介绍 -### 订单管理 -管理订单生命周期，处理用户和以太坊针对订单的更新操作，并提供不同类型的查询接口给用户和其他子系统使用。 +### 管理订单 +管理订单生命周期，处理用户和以太坊针对订单的更新操作，并向用户和其他子系统提供不同类型的查询接口。 #### 提交订单 -提交订单接口处理来自用户和订阅其他中继来源的订单。 +处理来自用户的订单、订阅其他中继来源的订单。 -##### 校验 +##### 校验订单 订单在持久化之前，需要经过一系列的校验，才能成功被持久化： ``` -1. 工作量证明校验(暂时未启用) -2. 基础校验规则，包括amountS最小数量和最小法币数量限制; 最晚生效时间限制(不能晚于某个时间点生效，当前设置为不能晚于订单提交时间10小时); 分润比例必须在0-1之间; 账户地址和Token地址合法性校验等 -3. 验证签名，根据v, r, s获取签名地址是否和钱包地址一致 -4. 是否是支持的token和市场对 -5. 订单是否过期 +1. 工作量证明校验(暂未启用) +2. 基础校验，规则：amountS最小数量和最小法币数量限制;最晚生效时间限制(不能晚于某个时间点生效，当前设置为不能晚于订单提交时间10小时);分润比例必须在0-1之间;账户地址和Token地址合法性校验等 +3. 验证签名，根据v, r, s获取签名地址，验证其是否与钱包地址一致 +4. 校验是否是支持的token和市场对 +5. 校验订单是否过期 ``` -##### 补全订单信息 -在一系列校验通过后，会补全订单的orderHash，price，market等字段，方便后续关系型查询。 +##### 补全订单 +通过一系列校验合格后，将会补全订单的orderHash，price，market等字段，方便后续关系型查询。 -##### 持久化 -最后订单会持久化到数据库，同时如果中继设置了广播策略，订单会按照策略广播出去，至此订单提交流程结束。 +##### 持久化订单 +最后订单会被持久化到数据库，如果中继设置了广播策略，还会按照该策略将订单广播到其他中继，至此订单提交流程结束。 -#### 订单查询 -我们为订单提供了多维度的查询接口，除最基本的订单列表查询(参见API文档)，我们还提供基于订单的市场深度查询接口，orderbook查询接口(市场深度是相同价格聚合数量后的结果，orderbook没有对订单做聚合)。 +#### 查询订单 +提供了多维度的查询接口，即除最基本的订单列表查询(参见API文档)外，还有基于订单的市场深度的查询和orderbook查询。 -#### 订单取消 -我们提供两种不同的订单取消方式，通过智能合约取消和通过中继取消。 -前者直接调用以太坊合约取消订单，需要消耗gas。 -后者是调用链下中继接口取消订单，不消耗gas，但是有一定概率取消失败，因为广播出去的订单有可能已经被其他中继提交环路，我们正在尽力减少这种取消失败的概率，未来建议都采用后者来取消订单，可以大量节省用户成本。 +> 市场深度是相同价格聚合数量后的结果，orderbook没有对订单做聚合 + +#### 取消订单 +提供两种取消方式：通过智能合约取消、通过中继取消。 +前者直接调用以太坊合约取消订单，需消耗gas。 +后者是调用链下中继接口取消订单，不消耗gas，但有一定概率取消失败，因为广播出去的订单有可能已经被其他中继提交环路，我们正在尽力减少这种取消失败的概率，未来建议都采用后者来取消订单，可大量节省用户成本。 --- ### 账户管理 -这里的账户，即用户以太坊钱包地址账户，我们支持钱包地址的一系列写操作：转账/授权/WETH转换等，并且持久化用户账户余额到内存数据库，解析以太坊每一笔用户相关的账户操作，实时更新用户余额变化。 -同时中继集中地维护用户最新nonce并尽可能保证准确，采用中继提供的nonce，可以最大程度降低用户以太坊操作的失败率。 -账户管理同时维护用户所有操作transaction记录，方便用户了解操作细节。 +即管理用户以太坊钱包账户，主要工作包括：支持对账户的一系列写操作（如转账/授权/WETH转换等）；支持解析以太坊上每一笔与用户相关的账户操作，实时更新用户余额变化并持久化到内存数据库中；维护用户所有transaction操作记录，方便用户了解操作细节；集中地准确地维护用户最新nonce，采用中继提供的nonce可以最大程度降低以太坊操作失败的概率。 --- -### 交易和撮合 -Loopring撮合服务(Miner)通过内部RPC接口获取未完结的订单，寻找环路，并提交以太坊智能合约撮合，最终通过以太坊解析服务，获取撮合结果，更新订单状态。 +### 交易与撮合 +Loopring撮合服务(Miner)通过内部RPC接口获取未完结的订单，寻找并发现环路后，提交到以太坊智能合约进行撮合，最终通过以太坊解析服务获取撮合结果，更新订单状态。 --- ### 交易所行情 -中继提供交易所必要的行情信息，包括深度/orderbook/最新成交/ticker/趋势图/kline等， 同时集成了coinmarketcap全球市场行情。最近我们与MyToken合作，接入MyToken开放平台，获取更加全面的全面市场行情数据，展示给用户全面的交易参考信息。 +中继向交易所提供一些必要的行情信息（包括深度/orderbook/最新成交/ticker/趋势图/kline等），同时集成了coinmarketcap全球行情，最近还将接入MyToken开放平台，获取并向用户展示更加全面的行情数据。 --- ### 元信息管理 -这里的元信息管理包括最佳预估gasPrice的信息，中继目前支持的合约信息(Delegate和Protocol对应关系)，中继支持的交易对列表，Token列表等。 +包括最佳预估gasPrice的信息、中继目前支持的合约信息(Delegate和Protocol对应关系)、中继支持的交易对列表、Token列表等。 --- -## 如何接入官方中继 -目前有3种方式可以接入中继：jsonrpc, socketio, sdk +## 如何接入中继 +目前有3种方式可以接入中继：jsonrpc、socketio、 sdk ### jsonrpc JSON-RPC是一种基于JSON的跨语言远程调用协议。JSON-RPC非常简单，在请求时向服务器传输数据格式如下(基于JSON2.0): @@ -205,7 +197,7 @@ JSON-RPC是一种基于JSON的跨语言远程调用协议。JSON-RPC非常简单 --- ### socketio -SocketIO将底层通信封装成事件编程模型，提供基于事件的长连接通信方式。中继为了提高数据实时性，也采用了和传统中心化交易所同样的技术手段，来提升用户体验，具体socketio接入方法，请参考[API文档](relay_api_spec_v2.md)。 +SocketIO将底层通信封装成事件编程模型，提供基于事件的长连接通信方式。中继为了提高数据的实时性，也采用了与传统中心化交易所一样的技术手段来提升用户体验，具体socketio接入方法，请参考[API文档](relay_api_spec_v2.md)。 --- @@ -215,10 +207,21 @@ SocketIO将底层通信封装成事件编程模型，提供基于事件的长连 --- ### 测试环境 -中继目前提供一套完整的测试环境，方便合作伙伴开发和调试Dapp，要使用中继测试环境，需要知晓一下相关信息： -1. 测试环境地址，13.112.62.24, 也就是说jsonrpc入口是：http://13.112.62.24/rpc/v2; socketio入口是：http://13.112.62.24/socket.io;以太坊测试节点入口是：http://13.112.62.24/eth -2. 13.112.62.24:8000 是loopr web钱包的测试环境入口 -3. 钱包要使用中继，需要一些中继和以太坊节点相关配置，这些配置项在主网和我们测试环境中不同，这里介绍各个配置项，并给出测试环境配置： +目前提供一套完整的测试环境，方便合作伙伴开发和调试Dapp，使用测试环境前，请先知晓以下相关信息 + +测试环境地址：13.112.62.24，即： + +* jsonrpc入口：http://13.112.62.24/rpc/v2 + +* socketio入口：http://13.112.62.24/socket.io + +* 以太坊测试节点入口：http://13.112.62.24/eth + +* web钱包测试环境入口：http://13.112.62.24:8000 + +> 中继生产环境只支持https, 测试环境只支持http + +钱包接入中继前，需先配置中继与以太坊节点的相关信息，这些配置项在主网和测试环境中并不相同，这里介绍测试环境中的各个配置项： ``` DelegateAddress - 请参考词汇表，测试环境地址：0xa0af16edd397d9e826295df9e564b10d57e3c457 @@ -228,21 +231,50 @@ chainId - 以太坊EIP155引入，为了防止重放攻击，测试 tokens List - 钱包配置的token列表，包含token详细信息，也可以通过loopring_getLooprSupportedTokens获取中继支持的token列表 ``` -4. 中继线上版本只支持https, 测试环境只支持http --- + +### 生产环境 + +生产环境为官方中继，生产环境地址：https://relay1.loopring.io/ ，即： + +* jsonrpc入口：https://relay1.loopring.io/rpc/v2 + +* socketio入口：https://relay1.loopring.io/socket.io + +* 以太坊节点入口：https://relay1.loopring.io/eth + +> 中继生产环境只支持https, 测试环境只支持http + +--- + ## 如何部署中继 -Loopring基金会实现了两个版本的中继：standalone和cluster， 这里介绍standalone版本的编译和部署方法。这里的中继运行在full模式下。 +目前提供两种部署方式：[aws部署](deploy/deploy_index_cn.md)、[docker部署](relay_docker_cn.md)，请仔细阅读部署文档。 -### 代码编译 -中继使用golang语言开发，开发中继时使用的是版本1.9.2, 编译中继建议使用大版本1.9, go开发和编译环境的搭建，请自行google， -源代码地址：https://github.com/Loopring/relay, 请使用master分支 -代码编译和运行， 请参考README +中继是一个完整的企业级分布式应用，虽然目前系统体量比较小，仅包含3个微服务，但同其他分布式应用一样，具有如下几个特点： + +* 基于aws ALB提供完整的负载均衡策略 +* 部署了高可用的kafka&zookeeper集群 +* 采用了aws redis主备模式缓存集群和mysql存储集群 +* 有多达200+完善的cloudwatch监控配置项 +* 支持aws codedeploy的一键部署脚本 +* 针对每个可能出点单点故障或者系统其他问题的地方，做了相应的灾备和容错处理 + +部署一个高可用的中继，需要非常专业的工程师做大量系统工作并长期维护，建议具有一定研发实力的合作伙伴来部署分布式中继，我们会尽可能提供部署指导。 + +--- + +## github +中继包含以下几个github库, 简单介绍下各个库的作用： +* relay-cluster : 中继cluster版本，提供wallet和DEX后台服务 +* miner : 撮合服务 +* extractor : 以太坊解析服务 +* relay-lib : 基础库，供以各个微服务系统使用 --- -### 配置文件 +## 配置文件 中继包含两个配置文件：relay.toml和tokens.json, 前者是中继全局配置，后者是用来指定中继支持的Token列表和市场。 -中继配置项比较多， 这里针对relay.toml中比较重要的不太容易理解配置项做一下说明： +relay.toml配置项较多，针对relay.toml中比较重要的不太容易理解配置项做如下说明： ``` websocket - 中继对外socketio端口 jsonrpc - 中继对外jsonrpc端口 @@ -255,76 +287,22 @@ gateway filter - 用来配置提交订单各种校验规则 miner - 以miner模式启动时，配置挖矿参数 ``` -我们会进一步更新relay.toml配置文件，添加注释，做到自解释。 - ---- - -### docker -docker镜像地址：https://hub.docker.com/r/loopring/relay， 目前版本比较旧，我们会尽快更新镜像。 +官方会进一步更新relay.toml配置文件，添加注释，做到自解释。 --- -## 分布式中继 -分布式中继，是中继的分布式版本，单节点中继虽然能完整的支持钱包和DEX服务，但是在架构上存在单点故障，升级和扩展困难，在遇到性能瓶颈无法降级等常见系统问题。为了让中继成为了企业级应用，提供高可用高性能的钱包和DEX服务，我们重构了中继，将原来的系统做服务化拆分，形成目前包含中继、撮合，解析器三个微服务的分布式版本。 +## 微服务介绍 ---- - -### github -分布式中继包含以下几个github库：relay-cluster/miner/extractor/relay-lib, 简单介绍下各个库的作用： -* relay-cluster : 中继cluster版本，提供wallet和DEX后台服务 -* miner : 撮合服务 -* extractor : 以太坊解析服务 -* relay-lib : 基础库，供以上上个微服务系统使用 - ---- - -### 微服务介绍 - -#### relay-cluster +* #### relay-cluster relay-cluster和之前单节点版本relay功能基本相同，为钱包和DEX应用提供后台服务，将原来在单节点版本relay中的撮合服务和以太坊解析服务剥离出去，就是目前relay-cluster提供的功能。 -#### miner +* #### miner 撮合服务，接收订单，发现环路，提交环路到以太坊网络，通过rpc服务于relay-cluster通信 -#### extractor +* #### extractor 以太坊解析服务，以太坊上发生的每一笔transaction，每一个event等，都是通过extractor解析，然后包装成事件，通过消息队列(目前是kafka)，提供给relay-cluster和miner使用 --- -### 谁更适合部署分布式版本 -分布式中继是一个完整的企业级分布式应用，虽然目前系统体量比较小，只包含3个微服务，但是同其他分布式应用一样，我们做了以下这些工作： - -* 基于aws ALB提供完整的负载均衡策略 -* 我们部署了高可用的kafka&zookeeper集群 -* 采用了aws redis主备模式缓存集群和mysql存储集群 -* 有多达200+完善的cloudwatch监控配置项 -* 支持aws codedeploy的一键部署脚本 -* 针对每个可能出点单点故障或者系统其他问题的地方，做了相应的灾备和容错处理 - -所以合作伙伴要想部署一个高可用的中继，需要做大量的系统工作，需要非常专业的工程师来长期维护。我们的建议是具有一定研发实力的合作伙伴来部署分布式中继，当然，我们也会尽可能提供部署帮助。 - ---- - -### 分布式版本镜像 -为了方便合作伙伴部署分布式中继，我们会分别提供以下几个镜像(制作中)： - -* relay-cluster镜像 -* miner镜像 -* extractor镜像 -* zookeeper&kafka -* mysql & redis 请自行下载官方镜像 - -### 分布式中继配置 -各个微服务和中间件的配置文件，都需要独立于镜像配置，我们会更新配置文件说明，增加自解释，这部分工作会和docker化一起完成，然后提供给合作伙伴使用，尽请期待。 - ---- - -### 分布式版本自定义部署 -在[docker镜像](#分布式版本镜像)部署方式可用前，该部署方式是目前可用的部署方式。用户可以通过该方式定制部署的组件及相关参数，并可选择部署相关的管理，监控和告警功能 - -[自定义部署](deploy/deploy_index_cn.md) - ---- - ## 获取帮助 -请访问官方网站获取联系方式，获得帮助: https://loopring.org +请访问Loopring官网：https://loopring.org ，获取联系方式并寻求帮助 diff --git a/docs/deploy/deploy_index_cn.md b/docs/deploy/deploy_index_cn.md index 56cf8581..40574cbd 100644 --- a/docs/deploy/deploy_index_cn.md +++ b/docs/deploy/deploy_index_cn.md @@ -1,4 +1,4 @@ -# Loopring部署文档 +# Loopring Relay Aws部署文档 本文档是所有组件部署说明的索引，并按照组件的依赖顺序依次进行了详细的介绍，使用者也应该按照此顺序去阅读和部署。 diff --git a/docs/deploy/deploy_kafka_cn.md b/docs/deploy/deploy_kafka_cn.md index b8c2f06c..4140aa63 100644 --- a/docs/deploy/deploy_kafka_cn.md +++ b/docs/deploy/deploy_kafka_cn.md @@ -49,7 +49,7 @@ log.flush.scheduler.interval.ms=300 log.flush.start.offset.checkpoint.interval.ms=2000 log.retention.hours=168 #修改为3台zookeeper节点的内网ip，多个节点间使用逗号分隔 -zookeeper.connect=xx.xx.xx.xx:2181,xx.xx.xx.xx:2181,xx.xx.xx.xx:2181 +zookeeper.connect=x.x.x.x:2181,x.x.x.x:2181,x.x.x.x:2181 default.replication.factor=3 ``` #### 启停 @@ -159,7 +159,7 @@ zookeeper.connect=x.x.x.x:2181 default.replication.factor=3 ``` -若采用免费aws实例，由于内存不足，启动后会立即exit，并在日志报错“Cannot allocate memory”，进行如下修改即可 +若采用免费aws实例做测试，由于内存不足，启动后会立即exit，并在日志报错“Cannot allocate memory”，进行如下修改即可 `sudo vim /opt/loopring/kafka_2.12-0.11.0.2/bin/kafka-server-start.sh` @@ -174,7 +174,7 @@ nohup /opt/loopring/kafka_2.12-0.11.0.2/bin/kafka-server-start.sh /opt/loopring/ nohup /opt/loopring/kafka_2.12-0.11.0.2/bin/kafka-server-start.sh /opt/loopring/kafka_2.12-0.11.0.2/config/server.properties3 & ``` -###### 确认服务正常启动 +* ###### 确认服务正常启动 ``` tail -f /opt/loopring/kafka_2.12-0.11.0.2/nohup.out telnet 本实列内网ip 9092 @@ -186,5 +186,5 @@ telnet 本实列内网ip 9092 /opt/loopring/kafka_2.12-0.11.0.2/bin/kafka-server-stop.sh /opt/loopring/kafka_2.12-0.11.0.2/config/server.properties2 /opt/loopring/kafka_2.12-0.11.0.2/bin/kafka-server-stop.sh /opt/loopring/kafka_2.12-0.11.0.2/config/server.properties3 ``` -##### 日志 +#### 日志 `/opt/loopring/kafka_2.12-0.11.0.2/logs` diff --git a/docs/deploy/deploy_miner_cn.md b/docs/deploy/deploy_miner_cn.md index 4ef4b13c..2afe2d30 100644 --- a/docs/deploy/deploy_miner_cn.md +++ b/docs/deploy/deploy_miner_cn.md @@ -30,7 +30,7 @@ error_output_paths = ["/var/log/miner/err.log"] port = "6379" #ethnode实例内网ip，多个实例之间用逗号进行分割 [accessor] - raw_urls = ["http://xx.xx.xx.xx:8545", "http://xx.xx.xx.xx:8545"] + raw_urls = ["http://x.x.x.x:8545", "http://x.x.x.x:8545"] #eth主网合约配置，如果非主网，要联系开源人员获取最新的测试配置 [loopring_accessor.address] "v1.5" = "0x8d8812b72d1e4ffCeC158D25f56748b7d67c1e78" @@ -60,12 +60,12 @@ error_output_paths = ["/var/log/miner/err.log"] #zookeeper内网ip [zk_lock] - zk_servers = "xx.xx.xx.xx:2181,xx.xx.xx.xx:2181,xx.xx.xx.xx:2181" + zk_servers = "x.x.x.x:2181,x.x.x.x:2181,x.x.x.x:2181" #测试场景下修改为：zk_servers = "x.x.x.x:2181" ... #kafka内网ip [kafka] - brokers = ["xx.xx.xx.xx:9092","xx.xx.xx.xx:9092","xx.xx.xx.xx:9092"] + brokers = ["x.x.x.x:9092","x.x.x.x:9092","x.x.x.x:9092"] #测试场景下修改为：brokers = ["x.x.x.x:9092"] [cloud_watch] enabled = false @@ -109,7 +109,7 @@ scp -i xx.pem tokens.json ubuntu@x.x.x.x:/opt/loopring/miner/config ``` * 部署keystore -通过私钥生成keystore并自动导入到miner中，其中--private-key填私钥，--passphrase填keystore的密码 +通过私钥生成keystore文件并自动导入到miner中，其中--private-key填私钥，--passphrase填该keystore的密码 ``` cd /opt/loopring/miner bin/miner account import --datadir config/keystore --private-key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --passphrase xxxxxx diff --git a/docs/deploy/deploy_zookeeper_cn.md b/docs/deploy/deploy_zookeeper_cn.md index 6a9a1e15..fddc3dfa 100644 --- a/docs/deploy/deploy_zookeeper_cn.md +++ b/docs/deploy/deploy_zookeeper_cn.md @@ -42,12 +42,12 @@ cp zoo_sample.cfg zoo.cfg ``` dataDir=/opt/loopring/data/zookeeper -server.1=xx.xx.xx.xx:2888:3888 -server.2=xx.xx.xx.xx:2888:3888 -server.3=xx.xx.xx.xx:2888:3888 +server.1=x.x.x.x:2888:3888 +server.2=x.x.x.x:2888:3888 +server.3=x.x.x.x:2888:3888 ``` -初始化myid，这里"n"在3台服务器的取值依次为1，2，3，和上面zoo.conf一致，每台服务器仅执行一次自身对应取值的命令 +初始化myid，这里"n"在三台服务器的取值依次为1，2，3与上面zoo.cfg对应，每台服务器仅执行一次自身对应取值的命令 `echo "n" > /opt/loopring/data/zookeeper/myid` @@ -147,7 +147,7 @@ echo "3" > /opt/loopring/data/zookeeper3/myid /opt/loopring/zookeeper-3.4.10/bin/zkServer.sh start /opt/loopring/zookeeper-3.4.10/conf/zoo2.cfg /opt/loopring/zookeeper-3.4.10/bin/zkServer.sh start /opt/loopring/zookeeper-3.4.10/conf/zoo3.cfg ``` -###### 确认服务正常启动 +* ###### 确认服务正常启动 ``` tail -f /opt/loopring/zookeeper-3.4.10/zookeeper.out telnet localhost 2181 @@ -159,6 +159,6 @@ telnet localhost 2181 /opt/loopring/zookeeper-3.4.10/bin/zkServer.sh stop /opt/loopring/zookeeper-3.4.10/conf/zoo2.cfg /opt/loopring/zookeeper-3.4.10/bin/zkServer.sh stop /opt/loopring/zookeeper-3.4.10/conf/zoo3.cfg ``` -##### 日志 +#### 日志 `/opt/loopring/zookeeper-3.4.10/zookeeper.out` diff --git a/docs/relay_docker_cn.md b/docs/relay_docker_cn.md index 90407bc9..3d0884e8 100644 --- a/docs/relay_docker_cn.md +++ b/docs/relay_docker_cn.md @@ -1,8 +1,18 @@ -# Loopring relay-cluster Docker 中文文档 +# Loopring Relay Docker部署文档 -loopring开发团队提供loopring/relay-cluster,最新版本是v1.5.0。
+为方便合作伙伴部署分布式中继，我们将提供以下几个镜像(除relay-cluster外，其余镜像正在制作中)： -## 部署 +* relay-cluster镜像 +* miner镜像 +* extractor镜像 +* zookeeper&kafka +* mysql & redis 请自行下载官方镜像 + +各个微服务和中间件的配置文件，都需要独立于镜像配置，官方会及时更新配置文件说明，增加自解释，这部分工作会和docker化一起完成，然后提供给合作伙伴使用，尽请期待！ + +目前官方提供relay-cluster镜像，最新版本：v1.5.0 + +## 部署relay-cluster * 获取docker镜像 ```bash docker pull loopring/relay-cluster