Core SDK

OneID SDK supports our partners to integrate OneID Service easily, which will solve all the complicated cross-chain issues, and help the blockchain products easier to use. Currently, OneID Service supports 70+ chains with only 1 step setup and the OneID NFT is using TRC-721 (Viction)

Published on npm

• Installation
• Getting Started
• Functions

Installation

We recommend switching to Node.js Version 16 to make sure common crypto dependencies works.

Then run:

npm install @oneid-xyz/core

yarn add @oneid-xyz/core

Getting Started

To get started, your must accept with the terms of use for using @oneid-xyz/core.

import { OneIDCore } from '@oneid-xyz/core';

const oneId = new OneIDCore({
  provider: provider,
  rpcUrl: string,
  headers: {
    onchainSignature?: string,
  },
  authority: {
    getPerSign?: () => string,
  },
  refId?: string,
})

Parameter

• provider (optional)

  • Web3 provider.

• rpcUrl (optional)

  • HTTP Web3 Provider.

• headers (optional)

  • Set in Request Header. In each API request, this shall need to be added to override request header

  headers: {
      onchainSignature?: string,
  }

• authority (optional)

  • getPerSign() (required) in order to define user who are using OneID service.
    • Firstly, user will need to sign message from HASH_MESSAGE, then put the signed message into this getPerSign() to send to OneID server to authenticate.

  authority: {
      getPerSign: () => string,
  }

• refId (optional)

  • Default referral ID when user register.

Functions

Init Configuration

initConfig() allows to init base configuration from OneID SDK

Interface

await oneid.systemConfig.initConfig()

Note: Inspect & Core SDK are using same system config, developer shall only need to init once.

Search OneID

search() allows users to find the IDs that they want to register.

Search Rule:

• Text and not including special characters
  • or search exactly ID (for example: "test.c98")
• search length must be >= 3 characters

Search result:

• search + all supported Top Level IDs (TLIDs)

Interface

search(search: string): Promise<IDInfo[]>;

Parameter

• search: The ID Name that user wants to register (ex: "test")

Example:

const search = await oneid.search(“test”)

Result:

[
  {
      "name": "test.c98",
      "node": "0x6191afdf8a7ad87cd5e474c91f390cfdc0bb4236c5b3f428433144d2a200dcc6",
      "category": "PROTECTED",
      "tokenId": "70622639689279718371527342103894932928233838121221666359043189029713682937432",
      "contractAddress": "0x090baF1B96702FB73AF0AbBE826388117779D08f",
      "expiredAt": "0",
      "isAvailable": false,
      "price": "35372778101234409918270048885999957117893135449783156737593107166509846491550",
      "paymentToken": "0x0Fd0288AAAE91eaF935e2eC14b23486f86516c8C"
  }
]

Parameter

• category: OneIDs supports 4 category as following:
  • COMMON
    • This is Regular IDs that allows user to register normally.
  • PROTECTED
    • IDs contain sensitive, inappropriate language and violate the OneID’s policies. You can not register these Governance IDs.
  • BANNED
    • IDs contain sensitive, inappropriate language and violate the OneID’s policies. You can not register these Governance IDs
  • PREMIUM
    • Premium IDs are special and popular IDs. Register fee for these IDs may be higher than normal.
• tokenID: the On-chain NFT Token ID of the ID Name
• contractAddress: the On-chain contract address of corresponding TLID
• expireAt: Expiration time in TimeStamp when the ID is registered
• isAvailable: True/False
  • If True: The ID Name not yet registered
  • If False: The ID name is already registered
• price: the Price number is in $ with decimal 18
• paymentToken: the token address pay with price.

Get OneID Info

getInfo() supports to get all information of an ID Name.

Interface

getInfo(id: string): Promise<IDInfo>;

Parameter:

• id: The ID Name that needs to get information (ex: "test.c98")

Example:

const oneIDInfo = await oneid.getInfo(“test.c98”)

Results:

{
  "name": "test.c98",
  "node": "0x6191afdf8a7ad87cd5e474c91f390cfdc0bb4236c5b3f428433144d2a200dcc6",
  "category": "PROTECTED",
  "tokenId": "70622639689279718371527342103894932928233838121221666359043189029713682937432",
  "contractAddress": "0x090baF1B96702FB73AF0AbBE826388117779D08f",
  "expiredAt": "0",
  "isAvailable": false,
  "price": "35372778101234409918270048885999957117893135449783156737593107166509846491550",
  "paymentToken": "0x0Fd0288AAAE91eaF935e2eC14b23486f86516c8C"
}

Get OneID detail Price

idPrice will return all the price components of an ID Name

Interface:

idPrice.useChainId('1').getPreOrderPrice(params: MultiIDParam[]): Promise<string>;

MultiIDParam {
  id: string;
  duration: string | number;
  controller: string;
  owner?: string;
  extra?: string;
}

Parameter

• id: the ID Name that user wants to register
• duration: the duration that goes to register (in seconds)
• controller: get from top level config in systemConfig
• owner: custom owner.
• extra: tbu

Example:

const tldConfig = OneIDCore.systemConfig.getTLDConfig('c98');
const { controller } = tldConfig;

const params = [
    {
        id: 'test.c98',
        duration: 31536000,
        controller: controller,
    }
]

const price = const price = await OneIDCore.idPrice
      .useChainId('88')
      .getPreOrderPrice(list);

Returns

{
    price: '564135110358930963'
}

Register OneID

In order to request OneID Registration, developers need to request 2 steps:

1. preOrders()

• Commit the ID & submit Pre-oder fee to avoid front-running
  • Pre-order fee = 10% Service Fee as configuration

2. postOrders()

• To submit order and request to register the ID.

Interface:

OneIDSDK.useChainId('88').preOrders(
    params: MultiIDParam[],
    senderAddress: string,
    paymentToken?: string
): Promise<ResponseExecuteTransaction<TransactionWithApprove>>;

After requested preOrders(), the commitment shall be generated & stored in contracts. In order to avoid front-running, the postOrders() must be in period time between 30 seconds and 1 hour (minCommitmentAge & maxCommitmentAge) since the previous committed time.

Request the function preOrdersCheck() to check expiration time of commitment.

After requested preOrders(), and wait for 30 seconds (minCommitmentAge) to avoid front-running, the user requests postOrders() to register the ID

OneIDSDK.useChainId('88').postOrders(
    params: MultiIDParam[],
    senderAddress: string,
    refId?: string,
    paymentToken?: string
): Promise<ResponseExecuteTransaction<TransactionWithApprove>>;

Parameters:

• params:

{
    id: the ID Name that user wants to register;
    duration: the duration that goes to register (in seconds)
    controller: get from top level config in systemConfig
    owner?: custom owner.
    extra?: TBU
}

• senderAddress: the address of registrant
• paymentToken: Contract address of Payment token
• refID: Optional - by default it will get refId from init, input another ID if you need to change the refID to another.

Note: You should set your ID in the refID to receive the refback amount. useChainId using with other chain (Ethereum - 1, BinanceSmart - 56, Polygon - 137)

Returns:

{
    "isError": false,
    "data": {
        "isApproved": true,
        "transaction": {
            "from": "0x123...123",
            "to": "0x123...123",
            "data": "0x309e8757...245",
            "chainId": "0x58",
            "value": "0x0"
        },
        "totalPayment": "564135110358930963",
        "paymentToken": "0x0Fd0288AAAE91eaF935e2eC14b23486f86516c8C"
    }
}

Link Wallet to OneID

linkedWallet() uses to write record of 70+ Multi-chain Wallet to the ID.

After linking multi-chain wallet to ID, the ID can be used to receive Tokens from any network.

Warning: Use C98 Extension to easily get addresses of 70+ chains in Multi-chain Wallet.

Interface:

linkedWallet(
    senderAddress: string,
    id: string,
    wallets: LinkedWallet[],
    signMessage: (message: string) => Promise<string>
): Promise<ResponseExecuteTransaction<TransactionConfig>>

interface LinkedWallet {
  chain: ChainKey;
  address: string;
}

Parameters:

• chain: the chain key (for example: CHAIN_KEY.BINANCE_SMART = 'binanceSmart')
• address: the corresponding address of that Chain.

Validation:

• must have TomoChain Wallet in LinkedWallet[] list

Returns:

{
    isError: false,
    data: {
      from: '0x0b6...ea7',
      to: '0x438...122',
      data: '0xac96....000',
      chainId: '0x58',
      value: '0x0'
    }
  }

UnLink Multi-chain Wallet

unlinkWallet() uses to remove the Multi-chain Wallet records of the ID from that Wallet. Moreover, users can use the Linked Wallet to unlink even if it's not an owner.

Interface:

unlinkWallet(
    id: string,
    senderAddress: string,
    signMessage: (message: string) => Promise<string>
): Promise<ResponseExecuteTransaction<TransactionConfig>>;

Parameters:

• id: the ID Name
• senderAddress: the Address of unlink requester

Returns:

{
    isError: false,
}

Re-claim Permission

Users need to re-claim permission when the Controller address different from Owner address in the contract of an ID Name. This is always happened when the ID NFT is sent to another address (or trading in NFT Marketplace).

Interface:

reclaimPermission(
    id: string, 
    senderAddress: string
): Promise<ResponseExecuteTransaction<TransactionConfig>>;

Parameters:

• id: the ID name
• senderAddress: the requester address (this should be owner address)

Returns:

{
    isError: false,
    data: {
      from: '0x0b6...ea7',
      to: '0x438...122',
      data: '0xac96....000',
      chainId: '0x58',
      value: '0x0'
    }
}

Set Primary Name

setPrimaryName() will assign one of Linked IDs as a representative account and serve as a cross-platform Web3 username and profile. Users can only designate one primary name per account.

Linked IDs means the ID that currently has records "Linked Wallet" of the current wallet of users, it also means the ID can't be set Primary Name when have no record "Linked Wallet"

Interface:

setPrimaryName(id: string): Promise<boolean>;

Parameters:

• id: The ID Name

Returns:

{ "isError": false }

Errors Code

{
  DEFAULT: "OneID Error: Unknown error occurs. Please try again!",
  INVALID_ID: "OneID Error: Invalid ID",
  API_TIMEOUT: "OneID Error: Endpoint timeout",
  INVALID_TOKEN_ADDRESS: "OneID Error: Token address is not support payment",
  INVALID_TOKEN_OWNER: "OneID Error: Invalid token owner",
  WALLET_EMPTY: "OneID Error: TomoChain Wallet is empty",
  LINKED_NOT_FOUND: "OneID Error: Linked wallet not found",
  INVALID_PERMISSION: "OneID Error: Invalid ID permission",
  INVALID_ADDRESS: "OneID Error: Invalid Address",
  INVALID_PARAMS: 'OneID Error: Params invalid',
  INVALID_ID_IN_GRACE: 'OneID Error: ID in grace time. please renew id to continue.',
  INVALID_CHAINID: 'OneID Error: ChainId is no longer support',
  SYSTEM_MAINTENANCE: 'OneID Error: System is currently under maintenance. please try again later',
  TLD_NO_SUPPORT: "OneID Error: TLD is no longer supported features"
};