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,
  sendTransaction(data: string, to: string): Promise<string>;
})

Parameters:

provider:
- https://web3js.readthedocs.io/
rpcUrl
- HTTP Web3 Provider
headers
- 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() - 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: Default referral ID when user register.

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

sendTransaction (required)
- data: encode of contract method
- to: Contract Address
- DAPP needs to build function sendTransaction() on VICTION to excuse on-chain transaction and receive TransactionHash for SDK.
  the parameters “data” & “to” are received while init SDK Configuration

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

Returns:

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

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

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

Get OneID detail Price

price() will return all the price components of an ID Name

Interface:

price(params: IDPriceParams{}): IDRegisterPrice;

IDPriceParams {
  id: string;
  duration: string | number;
  category: ID_CATEGORY;
  isReferrer?: boolean;
  expiredAt?: string | number;
}

Parameters:

category: get from search()
id: the ID Name that user wants to register
duration: the duration that goes to register (in seconds)
expiredAt: The expiration time of the ID, this can also get from search() (in seconds)
isReferrer: true/false when applying ID Referrer, user will receive referral back amount.

Example

let price = await oneid.price({
    category: "COMMON",
    id: "test.c98",
    duration: 157680000,
    expiredAt: 1854499642,
    isReferrer: true
  });

Returns

{
    "specialIDFee":"0",
    "durationFee":"500000000000000000000",
    "premiumPeriod":"0",
    "serviceFee":"1000000000000000000",
    "total":"200000000000000000000",
    "durationDiscount":"300000000000000000000",
    "refback":"20000000000000000000",
    "commitmentFee":"100000000000000000"
}

Parameters:

Total = durationFee + serviceFee + speicalIDFee + premiumPeriod - durationDiscount - refback
commitmentFee: this is pre-order fee when request commit()

Register OneID

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

commit()
- Commit the ID & submit Pre-oder fee to avoid front-running
  - Pre-order fee = 10% Service Fee as configuration
register()
- To submit order and request to register the ID.

Interface:

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

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

Request the function makeCommit() to get expiration time of commitment.

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

register(id: string, duration: string | number, senderAdrress: string, paymentToken: string, 
refID?: string): 
Promise<ResponseExecuteTransaction<string>>;

Parameters

id: The ID name that's going to register
duration: The duration that's going to register (in seconds)
senderAdrress: 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.

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

Returns:

{
    isError: false,
    data: '0x0748af82cdfb...9421c7caebedccfb67a1dfd39'
}

Register Multiple IDs

OneID also offers functions to register multiple IDs. Similar to single register, multiple register also required 2 following steps to avoid front-running:

multiCommit()
and multiRegister()

Interface:

multiCommit(params: MultiIDParams[], senderAdrress: string, paymentToken: string): 
Promise<ResponseExecuteTransaction<string>>;

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

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

Parameter

id: the ID Name that's going to register
duration: the duration that goes to register (in seconds)
senderAddress / owner: (Optional) the address of registrant.
- will get senderAddress if empty

Note:

If user adds more IDs or change duration after committed, then they need to submit commit again.

Returns:

{
    isError: false,
    data: '0x0748af82cdfb...9421c7caebedccfb67a1dfd39'
}

Make Commitment

makeCommit() supports to get the commitment information after commit() of an iD

Interface:

makeCommit(id: string, duration: string | number, senderAddress: string, index ?: number):
Promise<[commitment: string, secret: string, commitAge: number, index: number]>;

Parameters:

id: the ID Name
duration: the duration that's going to register (in seconds)
senderAddress: registrant address
index: optional : Index of the commit

Returns:

[ 
    commitment: "0x4e90e07a8936ba5...81b858debee6614832313", 
    secret: "0x94195786b1c40a7040e3c6...76fa7121155e78cf36", 
    commitAge: 0, 
    index: 3 
]

Parameters:

commitAge: the Expiration of the commitment when commit()

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

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 70+ chains in Multi-chain Wallet.

Interface:

linkedWallet(id: string, wallets: LinkedWallet[], walletName?: string): 
Promise<ResponseExecutTransaction<string>>;›

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: '0x0748af82cdfbcbea0148ff7854f32d57fb7268f9421c7caebedccfb67a1dfd39'
}

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): 
Promise<ResponseExecuteTransaction<string>>;

Parameters:

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

Returns:

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

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<string>>;

Parameters:

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

Returns:

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

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: VICTION Wallet is empty",
  LINKED_NOT_FOUND: "OneID Error: Linked wallet not found",
  INVALID_PERMISSION: "OneID Error: Invalid ID permission",
};

PreviousInspect SDK NextChain Integration

Last updated 1 month ago