@rsksmart/rns-sdk
RNS SDK
## Features
- .rsk domains:
- availability and prices
- registrations
- Manage domains:
- availability
- Set subdomain owner
- transfer
- reclaim
- Get/set domain owner
- Get/set domain resolver
- Manage resolution:
- Get/set `addr` resolution
## Usage
The library supports the following modules:
- .rsk domains registrations using `RSKRegistrar`
- .rsk domains registrations using the new partner registrar contracts `PartnerRegistrar`
- RNS domains admin using `RNS`
- Domain address resolution using `AddrResolver`
- Information on a partner configuration using `PartnerConfiguration`
You will need to use this addresses to initialize the library:
| Contract name | RSK Mainnet | RSK Testnet |
| - | - | - |
| RNS Registry (`rsnRegistryAddress`) | [`0xcb868aeabd31e2b66f74e9a55cf064abb31a4ad5`](https://explorer.rsk.co/address/0xcb868aeabd31e2b66f74e9a55cf064abb31a4ad5) | [`0x7d284aaac6e925aad802a53c0c69efe3764597b8`](https://explorer.testnet.rsk.co/address/0x7d284aaac6e925aad802a53c0c69efe3764597b8) |
| RIF Token ERC-677 ERC-20 (`rifTokenAddress`) | [`0x2acc95758f8b5f583470ba265eb685a8f45fc9d5`](https://explorer.rsk.co/address/0x2acc95758f8b5f583470ba265eb685a8f45fc9d5) | [`0x19f64674d8a5b4e652319f5e239efd3bc969a1fe`](https://explorer.testnet.rsk.co/address/0x19f64674d8a5b4e652319f5e239efd3bc969a1fe) |
| ERC-721 .rsk domains token (`rskOwnerAddress`) | [`0x45d3e4fb311982a06ba52359d44cb4f5980e0ef1`](https://explorer.rsk.co/address/0x45d3e4fb311982a06ba52359d44cb4f5980e0ef1) | [`0xca0a477e19bac7e0e172ccfd2e3c28a7200bdb71`](https://explorer.testnet.rsk.co/address/0xca0a477e19bac7e0e172ccfd2e3c28a7200bdb71) |
| .rsk domains registrar (`fifsAddrRegistrarAddress`) | [`0xd9c79ced86ecf49f5e4a973594634c83197c35ab`](https://explorer.rsk.co/address/0xd9c79ced86ecf49f5e4a973594634c83197c35ab) | [`0x90734bd6bf96250a7b262e2bc34284b0d47c1e8d`](https://explorer.testnet.rsk.co/address/0x90734bd6bf96250a7b262e2bc34284b0d47c1e8d) |
| .rsk domains partner registrar (`partnerRegistrarContractAddress`) | - | [`0x8104d97f6d82a7d3afbf45f72118fad51f190c42`](https://explorer.testnet.rsk.co/address/0x8104d97f6d82a7d3afbf45f72118fad51f190c42) |
| .rsk domains partner registrar (`partnerRegistrarContractAddress`) | - | [`0x8104d97f6d82a7d3afbf45f72118fad51f190c42`](https://explorer.testnet.rsk.co/address/0x8104d97f6d82a7d3afbf45f72118fad51f190c42) |
> See also RNS Resolver library [`@rsksmart/rns-resolver.js`](https://github.com/rsksmart/rns-resolver.js) to resolve domains following the standard protocol
### .rsk domain registrations
RNS validates and normalizes names in the following way:
1. **Validation:** RNS validates that a name is a valid domain name by checking that it conforms to the following rules:
- The name contains only letters (a-z), digits (0-9), and hyphens (-).
- The name starts and ends with a letter or digit.
2. **Normalization:** RNS normalizes a name by converting it to its canonical form, which includes:
- Converting all letters to lowercase.
- Expanding Punycode-encoded internationalized domain names (IDNs) to their Unicode representation.
#### 1. Using the RSKRegistrar
You can register .rsk domains paying with RIF Tokens. First, create the instance of `RSKRegistrar`
```typescript
import { Signer } from 'ethers'
import { RSKRegistrar } from '@rsksmart/rns-sdk'
let signer: Signer
const rskRegistrar = new RSKRegistrar(rskOwnerAddress, fifsAddrRegistrarAddress, rifTokenAddress, signer)
```
Query price and availability
```typescript
const label = 'taringa'
const available = await rskRegistrar.available(label)
const duration = BigNumber.from('1')
const price = await rskRegistrar.price(label, duration)
```
Register the domain
```typescript
const { makeCommitmentTransaction, secret, canReveal } = await rskRegistrar.commitToRegister(label, testAccountAddress)
await makeCommitmentTransaction.wait()
// you need to wait at least for one minute, you can build
// your own polling strategy checking canReveal to ensure
// it is the correct time to submit the register tx
const commitmentReady = await canReveal()
if (!commitmentReady) throw
const registerTx = await rskRegistrar.register(
label,
testAccountAddress,
secret,
duration,
price
)
await registerTx.wait()
```
#### 2. Using the PartnerRegistrar
You can use the PartnerRegistrar to register domains using the partner registrar contracts. First, create the instance of `PartnerRegistrar`.
> The PartnerRegistrar supports one click register even where commitment is required.
```typescript
import { Signer } from 'ethers'
import { PartnerRegistrar } from '@rsksmart/rns-sdk'
let signer: Signer
const networkAddresses = {
rskOwnerAddress: '0x0000000000000000000000000000000000000000',
rifTokenAddress: '0x0000000000000000000000000000000000000000',
partnerRegistrarAddress: '0x0000000000000000000000000000000000000000',
partnerRenewerAddress: '0x0000000000000000000000000000000000000000',
partnerAddress: '0x0000000000000000000000000000000000000000'
}
const partnerRegistrar = new PartnerRegistrar(signer, 'localhost', networkAddresses);
```
**Note:**
The `network` param is mandatory value, and it only valid values are `'mainnet'`, `'testnet'` or `'localhost'`.
Param `networkAddresses` is mandatory for `network='localhost'`.
For `'mainnnet'` and `'testnet'` will be optional and can be passed only in case of needing to modify one of the default
addresses for the given network, otherwise, default addresses will be used.
- Query price and availability
```typescript
const label = 'taringa'
const available = await partnerRegistrar.available(label)
const duration = BigNumber.from('1')
const price = await partnerRegistrar.price(label, duration)
```
- Register the domain
```typescript
const label = 'taringa'
const duration = BigNumber.from('1')
const ownerAddress = '0x...' //address of the owner of the domain
const price = await partnerRegistrar.price(label, duration)
const { commitHash, commitSecret, registerTxHash } = await partnerRegistrar.commitAndRegister(label, ownerAddress, duration, price)
```
- Transfer the domain
```typescript
const label = 'taringa'
const toAddress = '0x...' //address to transfer the domain ownership to
const transactionHash = await partnerRegistrar.transfer(label, toAddress)
```
- Renew the domain
```typescript
const label = 'taringa'
const duration = BigNumber.from('1')
const price = await partnerRegistrar.price(label, duration)
const transactionHash = await partnerRegistrar.renew(label, duration, price)
```
### Domain management
Create `RNS` instance
```typescript
import { Signer } from 'ethers'
import { RNS } from '@rsksmart/rns-sdk'
let signer: Signer
const rns = new RNS(registryAddress, signer)
```
#### Owner
Get and set the controller of a domain you own
```typescript
const domain = 'user1.taringa.rsk'
const newController = '0xb774...d771'
const tx = await rns.setOwner(domain, newController)
await tx.wait()
const controller = await rns.owner(domain)
```
#### Resolver
Get and set the resolver of a domain you own
```typescript
const domain = 'user1.taringa.rsk'
const resolverAddr = '0xb774...d771'
const tx = await rns.setResolver(domain, resolverAddr)
await tx.wait()
const controller = await rns.resolver(domain)
```
#### Subdomains
Set the owner of a subdomain of a domain you own
```typescript
const domain = 'taringa.rsk'
const subdomainLabel = 'user1'
const ownerAddress = '0x8c0f...1264'
const subDomainAvailable = await rns.getSubdomainAvailability(domain, subdomainLabel)
const tx = await rns.setSubdmoainOwner(domain, subdomainLabel, ownerAddress)
await tx.wait()
```
### Address resolution
Create `AddrResolver` instance
```typescript
import { Signer } from 'ethers'
import { AddrResolver } from '@rsksmart/rns-sdk'
let signer: Signer
const addrResolver = new AddrResolver(registryAddress, signer)
```
Get and set the address of a domain or subdomain you own
```typescript
const domain = 'user1.taringa.rsk'
const addr = '0xb774...d771'
const tx = await addrResolver.setAddr(domain, ownerAddress)
await tx.wait()
const addr = await addrResolver.addr(domain)
```
## Troubleshooting
1. Browser
> The library uses a dependency that requires Buffer to be available globally. If you are using in a browser environment, you need to the following:
- Install the dependency:
`npm install -D buffer`
- Add the following to your webpack config:
```javascript
const webpackConfig = {
resolve: {
fallback: {
buffer: require.resolve('buffer/'),
},
},
plugins: [
new webpack.ProvidePlugin({
Buffer: ['buffer', 'Buffer'],
}),
],
};
```
OR
```javascript
window.Buffer = window.Buffer || require('buffer/').Buffer;
```
2. React Native
> You can use the `rn-nodeify` package
```
rn-nodeify --install buffer -hack --yarn && patch-package
```
### Partner Configuration
We have also provided a class for interacting with the partner configuration contract
```typescript
import { Signer } from 'ethers'
import { PartnerConfiguration } from '@rsksmart/rns-sdk'
let signer: Signer
const partnerConfigurationAddress = '0x...' //address of the partner configuration contract
const partnerConfiguration = new PartnerConfiguration(partnerConfigurationAddress, signer)
```
Available operations:
- getMinLength
```typescript
const minLength = await partnerConfiguration.getMinLength()
```
- getMaxLength
```typescript
const maxLength = await partnerConfiguration.getMaxLength()
```
- getMinDuration
```typescript
const minDuration = await partnerConfiguration.getMinDuration()
```
- getMaxDuration
```typescript
const maxDuration = await partnerConfiguration.getMaxDuration()
```
- getMinCommitmentAge
> This is the minimum time that needs to pass before a commitment can be revealed
```typescript
const minCommitmentAge = await partnerConfiguration.getMinCommitmentAge()
```
- getFeePercentage
> This is the percentage of the domain price that will be charged as a fee
```typescript
const feePercentage = await partnerConfiguration.getFeePercentage()
```
- getDiscount
> This is the percentage of the domain price that will be discounted for the partner
```typescript
const discount = await partnerConfiguration.getDiscount()
```
- getPrice
```typescript
const price = await partnerConfiguration.getPrice(label, duration)
```
- validateName
> This function will resolve if the name is valid
```typescript
const valid = await partnerConfiguration.validateName(label, duration)
```
### List of Partners and addresses
Coming soon
## Run for development
Install dependencies:
```
npm i
```
### Run unit tests
```
npm test
```
Coverage report with:
```
npm run test:coverage
```
### Run linter
```
npm run lint
```
Auto-fix:
```
npm run lint:fix
```
### Build for production
```
npm run build
```
### Branching model
- `main` has latest release. Merge into `main` will deploy to npm. Do merge commits.
- `develop` has latest approved PR. PRs need to pass `ci` and `scan`. Do squash & merge.
- Use branches pointing to `develop` to add new PRs.
- Do external PRs against latest commit in `develop`.