Skip to main content

Feedback

Loading...

Migration to Token Registry v5

This migration guide helps you transition from Token Registry v4 to TrustVC integrated with Token Registry v5. TrustVC simplifies the signing and verification processes for W3C Verifiable Credentials (VC) and OpenAttestation Verifiable Documents (VD), while offering full integration with Token Registry v5. It also explains how to handle different scenarios depending on your needs.

1. What’s New?​

TrustVC Integration

  • TrustVC is a comprehensive library that combines several TradeTrust libraries, including Token Registry v5, W3C Verifiable Credentials, and OpenAttestation Verifiable Documents. By using TrustVC, you can manage both credential documents and token-based credentials seamlessly in a unified solution.

Token Registry v5

  • Token Registry v5 is the newest version. It allows you to manage token-based credentials and ownership transfers through smart contracts. For more information refer to here.

While TrustVC includes Token Registry v5, you may choose to integrate it separately depending on your needs.

2. How to Migrate to TrustVC and Token Registry v5​

Option 1: Install TrustVC for a unified solution

If you need both Token Registry v5 and W3C Verifiable Credentials or OpenAttestation Documents, you can install TrustVC to access all functionalities in one place.

npm install @trustvc/trustvc

Option 2: Install Token Registry v5 separately

If you only need to integrate Token Registry v5 and don't require the full TrustVC stack, you can install Token Registry v5 directly.

npm install @tradetrust-tt/token-registry@^5.x

3. Code Migration​

Connect to Token Registry​

In Token Registry v5, the way you connect to a registry hasn’t changed much, but it's important to ensure you're using the updated contract and factory from Token Registry v5.

Before (Token Registry v4):

import { TradeTrustToken__factory } from "@tradetrust-tt/token-registry/contracts";

const connectedRegistry = TradeTrustToken__factory.connect(tokenRegistryAddress, signer);

After (Token Registry v5 via TrustVC):

If you are migrating to TrustVC, you will use the token-registry-v5 module to access the Token Registry v5 contracts.

import { TradeTrustToken__factory } from "@trustvc/trustvc/token-registry-v5/contracts";

const connectedRegistry = TradeTrustToken__factory.connect(tokenRegistryAddress, signer);

If you are using Token Registry v5 directly (without TrustVC):

import { TradeTrustToken__factory } from "@tradetrust-tt/token-registry/contracts";

const connectedRegistry = TradeTrustToken__factory.connect(tokenRegistryAddress, signer);

Issuing a Document​

In Token Registry v5, there is a slight change when you mint tokens. You will now need to pass remarks as an optional argument. If no remarks are provided, ensure you pass 0x to avoid errors.

Before (Token Registry v4):

await connectedRegistry.mint(beneficiaryAddress, holderAddress, tokenId);

After (Token Registry v5 with TrustVC):

await connectedRegistry.mint(beneficiaryAddress, holderAddress, tokenId, remarks);

If no remarks are passed, the method expects '0x' as the value for remarks:

await connectedRegistry.mint(beneficiaryAddress, holderAddress, tokenId, '0x');

Restoring a Document​

The restore method remains mostly the same, but you'll now also have the option to include remarks.

Before (Token Registry v4):

await connectedRegistry.restore(tokenId);

After (Token Registry v5 with TrustVC):

await connectedRegistry.restore(tokenId, remarks);

If no remarks are passed, use '0x':

await connectedRegistry.restore(tokenId, '0x');

Accepting/Burning a Document​

You can burn or accept a document in Token Registry v5 by passing remarks as an optional argument.

Before (Token Registry v4):

await connectedRegistry.burn(tokenId);

After (Token Registry v5 with TrustVC):

await connectedRegistry.burn(tokenId, remarks);

If no remarks are passed, use '0x':

await connectedRegistry.burn(tokenId, '0x');

Connecting to Title Escrow​

When connecting to Title Escrow, the process is similar. You will use the updated contract from Token Registry v5 or TrustVC depending on your installation choice.

Before (Token Registry v4):

import { TitleEscrow__factory } from "@tradetrust-tt/token-registry/contracts";

const connectedEscrow = TitleEscrow__factory.connect(existingTitleEscrowAddress, signer);

After (Token Registry v5 with TrustVC):

import { TitleEscrow__factory } from "@trustvc/trustvc/token-registry-v5/contracts";

const connectedEscrow = TitleEscrow__factory.connect(existingTitleEscrowAddress, signer);

If you are still using Token Registry v4 but with TrustVC, you will connect like this:

import { TitleEscrow__factory } from "@trustvc/trustvc/token-registry-v4/contracts";

const connectedEscrow = TitleEscrow__factory.connect(existingTitleEscrowAddress, signer);

Surrender to Return to Issuer​

In Token Registry v4, the method to return the title to the issuer was surrender(). With Token Registry v5, this has been updated to returnToIssuer().

Before (Token Registry v4):

await connectedEscrow.surrender();

After (Token Registry v5 with TrustVC):

await connectedEscrow.returnToIssuer(remarks);

If no remarks are provided, you must pass '0x' as the argument:

await connectedEscrow.returnToIssuer('0x');

Rejecting Transfers of Beneficiary/Holder​

Token Registry v5 introduces additional methods for rejecting transfers, if necessary, for wrongful transactions:

Reject Transfer of Ownership:

Prevents a transfer of ownership to an incorrect or unauthorized party.

function rejectTransferOwner(bytes calldata _remark) external;

Reject Transfer of Holding:

Prevents a transfer of holding to an incorrect or unauthorized party.

function rejectTransferHolder(bytes calldata _remark) external;

Reject Both Roles (Ownership & Holding):

Prevents both ownership and holding transfers, effectively rejecting the entire transfer process.

function rejectTransferOwners(bytes calldata _remark) external;