# CNS-Open-Service

## Postman

[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/22322698-cd32951a-a24f-4fd5-a9fb-2e26f057532c?action=collection%2Ffork\&collection-url=entityId%3D22322698-cd32951a-a24f-4fd5-a9fb-2e26f057532c%26entityType%3Dcollection%26workspaceId%3D0df0c5b3-6c0a-47ee-ab26-8ba0139261e4)

## Swagger

[![drawing](https://static1.smartbear.co/swagger/media/assets/images/swagger_logo.svg)](http://101.42.88.184/swagger/cns-backend/)

## 第三方接入交互图

![](https://note.youdao.com/yws/api/personal/file/WEB3b48793e4e39f246359a449cbdecc7eb?method=download\&shareKey=7747d123352bb7fbd4f1273639661bac)

## API相关枚举类型：

| 枚举              | 意义       | 值                                                        |
| --------------- | -------- | -------------------------------------------------------- |
| trade\_provider | 法币支付运营商  | （wechat, alipay, ...）                                    |
| trade\_type     | 法币支付类型   | native/h5                                                |
| order\_state    | 订单状态     | init, made, success; null 表示全部                           |
| trade\_state    | 支付状态     | SUCCESS REFUND NOTPAY CLOSED REVOKED USERPAYING PAYERROR |
| refund\_state   | 支付退款状态   | NIL SUCCESS CLOSED PROCESSING ABNORMAL                   |
| tx\_state       | web3交易状态 | INIT SEND\_FAILED EXECUTE\_FAILED EXECUTED\_SUCCESS      |

### tx\_state

* INIT 未开始
* SEND\_FAILED 发送失败，表示交易未发送，通常是由于Estimate失败，tx\_error表示错误详情
* EXECUTE\_FAILED 执行失败，表示交易发送成功但交易执行失败（概率非常低，这种的失败原因是由于Estimate时的合约状态与交易执行时的合约状态不一致）
* EXECUTED\_SUCCESS 执行成功，表示交易发送成功而且交易执行成功

## 第三方接入

### Cns-backend API

* 测试环境 BaseUrl： <https://app-test.web3verse.space/v0>

### 注册域名

{% hint style="danger" %}
务必在调用 registers 前，对用户所输入的内容进行**敏感词**过滤；

域名注册目前只支持英文字符和 Emoji；
{% endhint %}

1. 调用合约Web3RegisterController的`rentPriceInFiat`方法计算价格，例如要计算 `conflux.web3` 域名一年期的价格，`rentPriceInFiat("conflux", 3600*24*365)`; 得到的结果有两个字段 `base` 和 `premium`; 实际价格为 `(base + premium)/1e6`, 单位为“分”
2. 在注册域名时如果需要（**也可以不设置**）同时设置正向解析，方法为将commit.data设置合约方法`PublicResolver.setAddr(bytes32 node, uint coinType, bytes memory a)`的ABI编码。 参数`node`为域名的`node`，`coinType`为`conflux`的`CoinType`值`503`, `a`为正向解析到的地址

   1. node 计算使用库`@ensdomains/eth-ens-namehash`的`hash`方法。如域名为 `conflux.web3`, 则 `node` 为 `require("@ensdomains/eth-ens-namehash").hash("conflux.web3")`
   2. ABI计算使用[iface.encodeFunctionData](https://docs.ethers.org/v5/api/utils/abi/interface/#Interface--encoding)

   如要生成解析`conflux.web3`到地址`cfxtest:aany9gz5hnpz9a22dkmkpcr276v932wze6cr821wd4`的data； 示例代码如下：

   ```js
      const ethers = require("ethers");
      const sdk = require("js-conflux-sdk");
      const target = "cfxtest:aany9gz5hnpz9a22dkmkpcr276v932wze6cr821wd4"; // 要正向解析到的地址
      const node = require("@ensdomains/eth-ens-namehash").hash("conflux.web3");
      const iface = new ethers.Interface(["function setAddr(bytes32 node, uint coinType, bytes memory a)"]);
      const data = iface.encodeFunctionData("setAddr",[node,503,sdk.format.hexAddress(target)])
   ```
3. 调用合约Web3RegisterController的`makeCommit`方法生成commit hash

   > commit.data设置为第2步生成的值
4. 调用合约Web3RegisterController的`commit`方法提交commit hash
5. 用户支付
6. 调用cns-backend的api [POST /v0/registers](http://101.42.88.184:8090/swagger_ui_dist/#/Registers/MakeRegisterOrder) 注册域名
   1. **注意：注册域名请求需要在commit交易执行完成后的10s\~10m中之内发送，否则容易导致register出现commitTooNew或commitTooOld的错误**
7. 调用cns-backend的api [GET /v0/registers/:commit\_hash](http://101.42.88.184:8090/swagger_ui_dist/#/Registers/Register) 查询注册状态

### 域名续费

1. 域名续费价格计算方式同注册域名相同，如 `conflux.web3` 域名续费一年期的价格为`rentPriceInFiat("conflux", 3600*24*365)`
2. 用户支付
3. 调用cns-backend的api [POST /v0/renews](http://101.42.88.184:8090/swagger_ui_dist/#/Renews/Renew) 续费
4. 调用cns-backend的api [GET /v0/renews/:id](http://101.42.88.184:8090/swagger_ui_dist/#/Renews/GetRenew) 查询续费状态

### 身份认证

"注册域名"及"域名续费" API 都需要身份认证，使用ApiKey方式，ApiKey 由官方人工发放

使用方法：

* 在请求头中增加 `X-Api-Key`

### 开发工具

* javascript: [web3ns](https://github.com/web3-identity/web3ns.js), [js-conflux-sdk](https://github.com/Conflux-Chain/js-conflux-sdk)
* golang: [cfxabigen](https://docs.confluxnetwork.org/go-conflux-sdk/cfxabigen)
* java: [java-conflux-sdk](https://github.com/Conflux-Chain/java-conflux-sdk)

## 其它

### 交易相关信息

交易信息相关字段有

* [tx\_state 交易状态](#tx_state)
* tx\_hash 交易哈希
* tx\_error 交易错误信息

> 当交易成功时 tx\_hash 才有值，交易失败时 tx\_error 才有值