Core SDK

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

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

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

Parameters:

• provider: (optional)

  • https://web3js.readthedocs.io/

• rpcUrl(optional)

  • HTTP Web3 Provider

• headers(optional)

  • onchainSignature - If DAPP needs to re-initiate SDK in every time using, then use this signature

    • This signature is signed message by end-user (MSG_SIGNED)

    • When init SDK -> put MSG_SIGNED into this onchainSignature

    • Each action related to the SDK, DAPP will take the onchainSignature and attach it to API requests.

• authority

  • getPerSign() (required) If DAPP initiates SDK Global, then use this signature

    • Initialize the global SDK with getPerSign which is a function that requires the user to sign or cache anywhere.

    • Each action related to the SDK, DAPP will get the onchainSignature by the SDK itself calling getPerSign() with the string MSG_SIGNED to attach to API requests.

• refId(optional): Default referral ID when user register.

You should set your ID in the refID to receive the refback amount.

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.

Sequence Diagrams

Basic Register Flow

Basic Register Flow

• Step 1: Use function search() to search the ID Name, this function will return detail information of IDs.

• Step 2: If DAPP use payment on VICTION, then it will need to go through 2 steps

  • Step 1: preOrders() in order to secure the ID to avoid front-run

  • Step 2: postOrders() to submit the final register.

  If DAPP use payment on Other Chains, then it will need to use the postOrders() function only

1. 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”)

Returns:

[
  {
      "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.

2. 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”)

Returns:

{
  name: "test.c98",
  node: "0x6191afdf8a7ad87cd...d2a200dcc6",
  category: "COMMON",
  tokenId: "7062263968927...3189029713682937432",
  contractAddress: "0x07EE95...AC6aBF90828D",
  expiredAt: "1726201843",
  isAvailable: false,
  price: '1000000000000000000'
  paymentToken: "0x0Fd0288AAAE91eaF935e2eC14b23486f86516c8C"
}

3. Get OneID detail Price

price() 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;
}

Parameters:

• 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'
}

4. 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 get 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"
    }
}

5. Extend OneID

extend() a name, extending the name's expiration by duration seconds.

OneID also offers extend multiple IDs through function multiExtend()

Interface:

extend(id: string, duration: string | number, senderAddress: string, paymentToken: string): 
Promise<ResponseExecuteTransaction<string>>;

multiExtend(params: MultiIDParams[], senderAddress: string, paymentToken: string): 
Promise<ResponseExecuteTransaction<string>>;

interface MultiIDParams {
    id: string;
    duration: string | number;
    owner?: string;
}

Returns:

{
    isError: false,
    data: '0x0748af82cdfbcbea0148ff7854f32d57fb7268f9421c7caebedccfb67a1dfd39'
 }

6. 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.

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

Else, use another wallet will apply EVM Only

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 VICTION Wallet in LinkedWallet[] list

Returns:

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

7. 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,
}

8. 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'
    }
}

9. 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'
};