# BID-SDK-Nodejs接口文档说明v1.0.0

本节详细说明BID-SDK-NodeJs常用接口文档。星火链提供 nodejs版 SDK供开发者使用。

## 1.1 基本概念介绍

BID开发工具包，主要是为了方便开发者可以快速加入到星火主链的生态建设中，有以下功能：  

- 公私钥工具：生成星火格式的公私钥、使用JWK的私钥生成签名、使用JWK的公钥验签。    
- BID标识工具：创建BID标识、更新BID标识、查询BID标识。 

## 1.2 请求参数与相应数据格式

+ **请求参数**

​    为了保证数字精度，请求参数中的Number类型，全都按照字符串处理，例如：

​    amount = 500， 那么传递参数时候就将其更改为 amount = '500' 字符串形式：

+ **响应数据**

  响应数据为JavaScript对象，数据格式如下：

  ```js
  {
  	errorCode:0,
  	errorDesc:'',
  	result:{}
  }
  ```

  说明：

  1. errorCode: 错误码。0表示无错误，大于0表示有错误
  1. errorDesc: 错误描述。
  1. result: 返回结果

  > 因响应数据结构固定，方便起见，后续接口说明中的`响应数据`均指`result`对象的属性

## 1.3 SDK使用方法

本节介绍SDK的使用流程。

### 1.3.1 生成SDK实例

##### 传入参数：

options 是一个对象，可以包含如下属性

| 参数 | 类型   | 描述        |      |
| ---- | ------ | ----------- | ---- |
| host | String | ip地址:端口 |      |

##### 实例：

```js
const BIDSDK = require('bid-sdk-nodejs')
const options = {
  host: 'http://test.bifcore.bitfactory.cn'
}
const sdk = new BIDSDK(options)
```

### 1.3.2 生成公私钥地址

```json
  const keys = {
    publicKey: {
      kty: 'OKP',
      crv: 'Ed25519',
      x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg'
    },
    privateKey: {
      kty: 'OKP',
      crv: 'Ed25519',
      x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg',
      d: 'CcU76t-Ik55vK75c1TgjzPQc4G84G_101rt0N9H5S5w'
    }
  }
  let generateAccount = sdk.keypair.generate(keys)
  console.log(generateAccount)
  console.log(generateAccount.result.address)
  console.log(generateAccount.result.encPrivateKey)
  console.log(generateAccount.result.encPublicKey)
  console.log(generateAccount.result.privateKeyJWK)
  console.log(generateAccount.result.publicKeyJWK)
```

### 1.3.3 签名

```json
 const privateKey = {
    kty: 'OKP',
    crv: 'Ed25519',
    x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg',
    d: 'CcU76t-Ik55vK75c1TgjzPQc4G84G_101rt0N9H5S5w'
  }
  const message= 'b06566b0f8774961657c7389e8c4b2bba40450b1d5ee858ab6213f283146ce0132a9e3'
  let signature = sdk.singer.sign(message,privateKey)
  console.log(signature)
```

### 1.3.4 验签

```json
  const  publicKey= {
    kty: 'OKP',
    crv: 'Ed25519',
    x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg'

  }
  const signature = 'e06277b97d895f208b92e98013d8a56b55ff2febaca2f3d6e5609f5b7635a16acaff9299b831df21db8d1a8b6c9e863d16575f6ad3f4ef8229e95c2653715e06'
  const message= 'b06566b0f8774961657c7389e8c4b2bba40450b1d5ee858ab6213f283146ce0132a9e34'
  console.log(sdk.singer.verify(message,signature,publicKey))
```

### 1.3.5 BID格式校验

```json
sdk.keypair.isAddress('did:bid:eftzENB3YsWymQnvsLyF4T2ENzjgEg41')
```

### 1.3.6 JWT公钥转星火公钥

```json
const  publicKey= {
    kty: 'OKP',
    crv: 'Ed25519',
    x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg'
  }
  console.log(sdk.keypair.getEncPublicKey(publicKey));
```

### 1.3.7 根据JWT公钥获取星火bid

```json
const  publicKey= {
    kty: 'OKP',
    crv: 'Ed25519',
    x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg'
  }
  console.log(sdk.keypair.publicJWKToAddress(publicKey));
```

### 1.3.8 星火公钥转JWT公钥

```json
  const publicKey = 'b065664a3888c9383494b2fa56bbfa095c68b52bf02c08727ba852a61ecbe5bc8d2878'
  const info = sdk.keypair.parsePublicKey(publicKey)
  console.log(info)
```

## 1.4 BID标识工具

### 1.4.1 BID标识创建

> 请求参数

| 参数          | 类型   | 描述                                                         |
| ------------- | ------ | ------------------------------------------------------------ |
| privateKey    | String | 必填，交易源账户私钥                                         |
| ceilLedgerSeq | Long   | 选填，区块高度限制, 如果大于0，则交易只有在该区块高度之前（包括该高度）才有效 |
| remarks       | String | 选填，用户自定义给交易的备注                                 |
| gasPrice      | Long   | 选填，打包费用 (单位是uXHT)，默认100L                        |
| feeLimit      | Long   | 选填，交易花费的手续费(单位是uXHT)，默认1000000L             |
| bidDocument   | String | 必填，bid文档内容                                            |

> 示例

```json
   const privateKey = {
        kty: 'OKP',
        crv: 'Ed25519',
        x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg',
        d: 'CcU76t-Ik55vK75c1TgjzPQc4G84G_101rt0N9H5S5w'
    }
    let contractInvokeOperation = {
        privateKey: privateKey,
        ceilLedgerSeq: '',
        feeLimit: '',
        gasPrice: '',
        remarks: 'bidCreate',
        bidDocument: '{\"document\":{\"@context\": [\"https://w3.org/ns/did/v1\"],\"id\": \"did:bid:efwkGc1NVsM2tpTEwsjvrcqEkFqQ4Eu5\", \"version\": \"1\",\"authentication\": [\"did:bid:ef22GhuuX3MmCR7LgxyNJS8TT4tvHrCyH#key-1\"]}}'
    }
    let data = await sdk.bidDocument.create(contractInvokeOperation)
    console.log('bidCreate() : ', JSON.stringify(data))
```

### 1.4.2 BID标识更新

> 请求参数

| 参数          | 类型   | 描述                                                         |
| ------------- | ------ | ------------------------------------------------------------ |
| privateKey    | String | 必填，交易源账户私钥                                         |
| ceilLedgerSeq | Long   | 选填，区块高度限制, 如果大于0，则交易只有在该区块高度之前（包括该高度）才有效 |
| remarks       | String | 选填，用户自定义给交易的备注                                 |
| gasPrice      | Long   | 选填，打包费用 (单位是uXHT)，默认100L                        |
| feeLimit      | Long   | 选填，交易花费的手续费(单位是uXHT)，默认1000000L             |
| bidDocument   | String | 必填，bid文档内容                                            |

> 示例

```json
 const privateKey = {
        kty: 'OKP',
        crv: 'Ed25519',
        x: 'SjiIyTg0lLL6Vrv6CVxotSvwLAhye6hSph7L5byNKHg',
        d: 'CcU76t-Ik55vK75c1TgjzPQc4G84G_101rt0N9H5S5w'
    }
    let contractInvokeOperation = {
        privateKey: privateKey,
        ceilLedgerSeq: '',
        feeLimit: '',
        gasPrice: '',
        remarks: 'bidUpdate',
        bidDocument: '{\"document\":{\"@context\": [\"https://w3.org/ns/did/v1\"],\"id\": \"did:bid:efwkGc1NVsM2tpTEwsjvrcqEkFqQ4Eu5\", \"version\": \"2\",\"authentication\": [\"did:bid:ef22GhuuX3MmCR7LgxyNJS8TT4tvHrCyH#key-1\"]}}'
    }
    let data = await sdk.bidDocument.update(contractInvokeOperation)
    console.log('bidUpdate() : ', JSON.stringify(data))
```

### 1.4.3 BID标识查询

> 请求参数

| 参数 | 类型   | 描述          |
| ---- | ------ | ------------- |
| bid  | String | 必填，bid地址 |

> 示例

```json
    const bid='did:bid:eftkDzvf8qAZe7HPk29Z3amfcH3RkfQr'
    let data = await sdk.bidDocument.query(bid)
    console.log('contractQuery() : ', JSON.stringify(data))
```

### 1.4.4 Hash查询

> 请求参数

| 参数 | 类型   | 描述           |
| ---- | ------ | -------------- |
| hash | String | 必填，交易hash |

> 示例

```json
    let hash = 'ff67ffc3fdd7a417b78cb05d188537f18eb24283b5cde5ef652b38137d5defad'
    let data = await sdk.transaction.getTransactionInfo(hash)
    console.log('getTransactionInfo() : ', JSON.stringify(data))
```

## 1.5 错误码

> 错误码

| 异常                          | 错误码 | 描述                                             |
| ----------------------------- | ------ | ------------------------------------------------ |
| INVALID_SOURCEADDRESS_ERROR   | 11002  | Invalid BID Document Address                     |
| CONNECTNETWORK_ERROR          | 11007  | Failed to connect to the network                 |
| INVALID_CONTRACTADDRESS_ERROR | 11037  | Invalid contract address                         |
| INVALID_GASPRICE_ERROR        | 11049  | GasPrice must be between 0 and Long.MAX_VALUE    |
| INVALID_FEELIMIT_ERROR        | 11050  | FeeLimit must be between 0 and Long.MAX_VALUE    |
| INVALID_CEILLEDGERSEQ_ERROR   | 11052  | CeilLedgerSeq must be equal to or greater than 0 |
| INVALID_JWK                   | 11053  | Invalid jwk Object                               |
| INVALID_JWK_PRIVATEKEY        | 11058  | Invalid jwk privateKey                           |
| INVALID_JWK_PUBLICKEY         | 11059  | Invalid jwk publicKey                            |
| REQUEST_NULL_ERROR            | 12001  | Request parameter cannot be null                 |
| QUERY_RESULT_NOT_EXIST        | 12009  | Query result not exist                           |
| INVALID_BIDDOCUMENT_ARGUMENTS | 12011  | Invalid bidDocument arguments                    |