npm package: @rentero/rangers-sdk
Description: Rentero Protocol SDK For Rangers Chain
Latest version: 0.1.1

# Rangers-SDK

Rentero Protocol SDK For Rangers Chain, allowing application developers easily query renter's NFTs info and use Rentero Protocol.

## Installation

```bash
yarn add @rentero/rangers-sdk
```

## Usage

SDK supports both Rangers Mainnet and Testnet: `NETWORKS.testnet`, `NETWORKS.mainnet`

```ts
import { RangersNFT, NETWORKS } from '@rentero/rangers-sdk'

const renterAddress = '0x2595c561b52b95ae4bacb5bc4ad28c810607f88f'
const lenderAddress = '0x576687d59d191a9b20110fb3e126dbf27d8e42e0'
const contractAddress = '0x6f71dd919192eedc50cd40177b5f7de51aa30d3c'
const tokenId =
  '485281096889408167811558965277831548813758404452706290381094039604503'

const rangersNFT = new RangersNFT(NETWORKS.testnet)

const result1 = await rangersNFT.getRentInfoById(contractAddress, tokenId)

const result2 = await rangersNFT.getRentNFTsByAddress(renterAddress, {
  pageSize: 10,
  pageNumber: 3,
})

const result3 = await rangersNFT.getLendNFTsByAddress(lenderAddress, {
  sortBy: 'leaseDay',
  sortWay: 'desc',
})

const result4 = await rangersNFT.getAllNFTsInMarket()

const result5 = await rangersNFT.getOperateRecord(contractAddress, tokenId)
```

## APIs

Rangers SDK mainly divide into two part: `RangersNFT` and `Rangers`.

- `RangersNFT` class contains query rental NFT info from thegraph data, such as expires time, renting NFTs, lending NFTs, etc.

- `Rangers` class contains Rentero Protocol core functions, such as lending、rending、redemption.

---

### 1. **RangersNFT**

Pass in the blockchain network and NFT contracts (Optional), instantiate the object.

- network: mainnet | testnet
- targetContracts: query the renting and lending info of specific contracts, otherwise return all info of all contracts in market

```TypeScript
new RangersNFT(network: NETWORKS, targetContracts?: string[])
```

### 1.1 `getRentNFTsByAddress`

Query all lease NFTs under the renter address

```TypeScript
interface RentListParams {
  pageSize?: number,
  pageNumber?: number,
  sortBy?: 'rentPerDay' | 'leaseDay',
  sortWay?: 'asc' | "desc"
}
const getRentNFTsByAddress: ( renterAddress: string, pageParams?: RentListParams) => Promise<any>
```

### 1.2 `getRentInfoById`

Query the rent NFT info of the specified NFT

```TypeScript
const getRentInfoById: (contractAddress: string, nftId: string) => Promise<any>
```

Example result:

```json
{
  "lease": {
    "daysPerPeriod": "1",
    "deposit": "330000000000000000",
    "erc20Address": "0x55b4c4ee5e4c2db29177cb919572e5127a302963",
    "expires": "1670403336",
    "id": "0x6f71dd919192eedc50cd40177b5f7de51aa30d3c-485281096889408167811558965277831548813758404452706290381094039604503",
    "lender": "0x431b4ca18e269fc7e1f5af49b9f4e2af683f6207",
    "maxRentalDays": "365",
    "minRentalDays": "1",
    "nftAddress": "0x6f71dd919192eedc50cd40177b5f7de51aa30d3c",
    "paidExpires": "1670057736",
    "rentPerDay": "330000000000000000",
    "renter": "0x2595c561b52b95ae4bacb5bc4ad28c810607f88f",
    "start": "1667811336",
    "tokenId": "485281096889408167811558965277831548813758404452706290381094039604503",
    "whitelist": "0x0000000000000000000000000000000000000000"
  }
}
```

_TIP:_ **If the expires time is greater than the current time, it is in the rental state, otherwise it is in the market listing state.**

### 1.3 `getLendNFTsByAddress`

Query lend NFTs list by lender address

```TypeScript
interface LendListParams {
  pageSize?: number,
  pageNumber?: number,
  sortBy?: 'rentPerDay' | 'leaseDay',
  sortWay?: 'asc' | "desc"
}
const getLendNFTsByAddress: (lendAddress: string, pageParams?: LendListParams) => Promise<any>
```

### 1.4 `getAllNFTsInMarket`

Query all NFTs in Market by the passed NFT Collections

```TypeScript
interface AllMarketNFTParams {
  pageSize?: number,
  pageNumber?: number,
  sortBy?: 'rentPerDay' | 'leaseDay',
  sortWay?: 'asc' | "desc"
}
const getAllNFTsInMarket(pageParams?: AllMarketNFTParams) => Promise<any>
```

### 1.5 `getOperateRecord`

Query NFT operation records for specific tokenId

```TypeScript
const getOperateRecord(contractAddress: string, tokenId: string) => Promise<any>
```

---

### 2 **_Rangers_**

Rangers class contains Rentero protocol core functions, user could lend、rent、redeem、return, etc by Rangers instance.

`new Rangers(signer: Signer, config: RangersConfig)`

**Params**

- signer: `ethers.Signer`
  - sign messages and transactions and send signed transactions to network to execute state changing operations. [more details](https://docs.ethers.io/v5/api/signer/)
- config: `{targetChain: NETWORKS, marketMode: 'installment', marketAddress?: string}`
  - targetChain: current support chain `'mainnet' | 'testnet'`
  - marketMode _(optional)_: current only support `installment`
  - marketAddress _(optional)_: specify market contract address to override the above configuration

```typescript
// example used in dapp
const { data: signer } = useSigner()

const rangers = useMemo(() => {
  if (!signer) return

  return new Rangers(signer, {
    targetChain: NETWORKS.testnet,
    marketMode: 'installment',
  })
}, [signer])
```

full usage example see [demo](./example)

### 2.1 `lendNFT`

lend user NFT to market

```typescript
Rangers.lendNFT(nftAddress: string, tokenId: string, erc20Address: string, whitelist: string, deposit: BigNumber, dailyPrice: BigNumber, paymentCycle: number, minRentalDays: number, maxRentalDays: number) => Promise<any>
```

**Params**

- nftAddress: `string`
  - lend NFT Collection address
- tokenId: `string`
  - NFT token id
- erc20Address: `string`
  - payment token contract address
- whitelist: `string`
  - whitelist address, only whitelist user could rent this NFT, only support one whitelist address, if don't need whitelist, please pass zero address: `0x0000000000000000000000000000000000000000`
- deposit: `ethers.BigNumber`
  - the deposit amount of lend NFT
- dailyPrice: `ethers.BigNumber`
  - the daily price of renting NFT
- paymentCycle: `number`
  - payment cycle for renting NFT
- minRentalDays: `number`
  - min rental days of current NFT (Min suuport value: 1)
- maxRentalDays: `number`
  - max rental days of current NFT (Max support value: 65535)

```typescript
const result = await rangers?.lendNFT(
  NFT_ADDRESS,
  '573',
  '0x304af20ef7a8497aeed4a4a6ba4601988d5b11f6',
  '0x0000000000000000000000000000000000000000',
  ethers.utils.parseUnits('1.2', 18),
  ethers.utils.parseUnits('1.2', 18),
  3,
  1,
  365
)
console.log(result)
```

### 2.2 `reLendNFT`

update lend NFT order info in market. (Can only be called when listing not rented)

```typescript
Rangers.reLendNFT(nftAddress: string, tokenId: string, erc20Address: string, whitelist: string, deposit: BigNumber, dailyPrice: BigNumber, paymentCycle: number, minRentalDays: number, maxRentalDays: number) => Promise<any>
```

**Params**

Same to `lendNFT` params

```typescript
const result = await rangers?.reLendNFT(
  NFT_ADDRESS,
  '573',
  '0x304af20ef7a8497aeed4a4a6ba4601988d5b11f6',
  '0x0000000000000000000000000000000000000000',
  ethers.utils.parseUnits('2.4', 18),
  ethers.utils.parseUnits('2.4', 18),
  5,
  1,
  365
)
console.log(result)
```

### 2.3 `rentNFT`

rent specific NFT in market

```typescript
Rangers.rentNFT(contractAddress: string, tokenId: string, rentDays: number) => Promise<any>
```

**Params**

- contractAddress: `string`
  - NFT contract address
- tokenId: `string`
  - NFT token ID
- rentDays: `number`
  - rent days (Min:1 ~ Max:65535)

```typescript
const NFT_ADDRESS = '0x317caEc5AFd5d43B205683318eC35ed8B063d131'
const TOKEN_ID = '574'
const result = await rangers?.rentNFT(NFT_ADDRESS, TOKEN_ID, 10)
console.log(result)
```

_Tips: before rent NFT successfully, renter should approve pay token to the market contract._

### 2.4 `earlyReturn`

renter early return rented NFT

```typescript
Rangers.earlyReturn(contractAddress: string, tokenId: string) => Promise<any>
```

**Params**

- contractAddress: `string`
  - NFT contract address
- tokenId: `string`
  - NFT token ID

```typescript
const NFT_ADDRESS = '0x317caEc5AFd5d43B205683318eC35ed8B063d131'
const TOKEN_ID = '575'
const result = await rangers?.earlyReturn(NFT_ADDRESS, TOKEN_ID)
console.log(result)
```

### 2.5 `redeemNFT`

lender early redeem NFT

```typescript
Rangers.redeemNFT(contractAddress: string, tokenId: string) => Promise<any>
```

**Params**

- contractAddress: `string`
  - NFT contract address
- tokenId: `string`
  - NFT token ID

```typescript
const NFT_ADDRESS = '0x317caEc5AFd5d43B205683318eC35ed8B063d131'
const TOKEN_ID = '573'
const result = await rangers?.redeemNFT(NFT_ADDRESS, TOKEN_ID)
console.log(result)
```