1.0.3 • Published 25 days ago

@oneid-xyz/core v1.0.3

Weekly downloads
-
License
ISC
Repository
-
Last release
25 days ago

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 (TomoChain)

Published on npm

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

Parameter

  • provider (optional)
  • 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 (required)

    • 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.
  • sendTransaction(data: string, to: string): Promise<string> (required)
    • data: encode of contract method
    • to: Contract Address
    • DAPP needs to build function sendTransaction() on TomoChain to excuse onchain 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”)

Result:

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

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

Results:

{
  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"
}

Parameter:

  • 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:

1. commit()

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

2. 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, senderAddress: 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)
  • 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.

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()
multiCommit(params: MultiIDParams[], paymentToken: string): 
Promise<ResponseExecuteTransaction<string>>;
multiRegister(params: MultiIDParams[], 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)
  • owner: (optional) the address of registrant

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

Returns:

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

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(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 TomoChain 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: 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",
};
dayjslodash@oneid-xyz/basetypescript
@everything-registry/sub-chunk-681
1.0.3

25 days ago

1.0.2

5 months ago

1.0.1

6 months ago

1.0.0

7 months ago