Example
For this particular document, we will go through the many actions that various parties will be allowed to do in a typical title transfer flow. In order to demonstrate it properly, we will be setting up some prerequisites before we begin. Note that this is not intended to be a tutorial, but just a demonstration of the various capabilities of each state change of the transferable record.
For this demonstration we will have 3 players.
- Alice
- Bob
- Charlie
We will assume that the transferable record has already been issued by a token registry, and the present state of the transferable record is as follows: (holder: Alice, owner: Alice), in words, this means that the transferable record is held and owned by Alice
With all the prerequisites ready, we will then proceed on with the actions of the title transfer.
Note that we will be using token/transferable record interchangeably at times.
Order of actions to be done for this demonstration:
- endorse change of ownership
- reject change of ownership (v5)
- change holder
- reject change holder (v5)
- nominate change of ownership
- endorse transfer of ownership
- reject transfer of ownership (v5)
At each action done, we will state the present state of the token, and the respective actions the players can do with the given present state.
Endorse Change of Ownership
Present state:
The token belongs to Alice (both owner and holder are the address of Alice)
Actions
- Alice:
- change holder
- endorse
- return document to issuer
- Bob:
- no access
- Charlie:
- no access
We will do endorse change of ownership first.
What this command does is it sets the states (holder and owner) of the token to a given address, in this case we will endorse the change of ownership to Charlie.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow transfer-owner-holder
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Enter the new owner address: <CHARLIE_ADDRESS>
? Enter the new holder address: <CHARLIE_ADDRESS>
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to endorse the change of owner...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's holder has been successfully endorsed to new owner and holder
If this transaction is mined and successful, the state of the transferable record will be different.
Reject Change of Ownership and Holdership
Present state:
The token belongs to Charlie (both owner and holder are the address of Charlie)
Actions
- Alice:
- no access
- Bob:
- no access
- Charlie:
- change holder
- endorse
- return document to issuer
- reject ownership and holdership
We will do reject change of ownership now.
What this command does is it sets the states (holder and owner) of the token to it's previous holder and owner address, in this case we will reject the change of ownership back to Alice.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow reject-transfer-owner-holder
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to reject the change of owner and holder...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's owner and holder has been successfully rejected to previous owner and holder
If this transaction is mined and successful, the state of the transferable record will be different.
Change Holder
The next action we will demonstrate is change holder, but first, the present states and actions.
Present state:
NOTE - Considering Charlie actually not made the reject change of owner transaction.
The token belongs to Charlie (both owner and holder are the address of Charlie)
Actions:
- Alice:
- no access
- Bob:
- no access
- Charlie:
- change holder
- endorse change of ownership
- return document to issuer
Now we will do the change holder command.
What this command does is it just sets the holder state to a new address.
In this case we will set the holder state to Bob, owner state remains as Charlie address
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow transfer-holder
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Enter the new holder address: <BOB_ADDRESS>
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to change the holder...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's holder has been successfully changed to holder with address: <BOB_ADDRESS>
Do take note that the wallet supplied should be that of Charlie instead of Alice since Charlie currently holds and owns the token.
If this command is successful, we will yet again advance the state of the token.
Reject Change of Holder
The next action we will demonstrate is reject change of holder, but first, the present states and actions.
Present state:
The token is held by Bob, token is owned by Charlie
Actions:
- Alice:
- no access
- Bob:
- change holder
- reject change of holder
- Charlie:
- nominate change of ownership
Now we will do the reject change of holder command.
What this command does is it just sets the holder state to it's previous holder address.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow reject-transfer-holder
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to reject the change of holder...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's holder has been successfully rejected to previous holder
Do take note that the wallet supplied should be that of Bob instead of Charlie since Bob currently holds the token and Charlie owns the token.
If this command is successful, we will yet again advance the state of the token.
Nominate Change of Ownership
Present state:
NOTE - Considering Bob actually not made the reject change of holder transaction.
The token is still held by Bob, token is owned by Charlie
Actions:
- Alice:
- no access
- Bob:
- change holder
- Charlie:
- nominate change of ownership
Next, we will do nominate change of ownership as we have already demonstrated change holder.
What this command does is to allow Charlie, the current owner, to suggest a new owner of the token.
In this case we will suggest Alice to be the new owner.
Does this lead to any change in state (holder, owner)? The answer is no, not yet.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow nominate-transfer-owner
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Enter the beneficiary address: <ALICE_ADDRESS>
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to nominate the change of owner...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's owner has been successfully nominated to new owner with address <ALICE_ADDRESS>
If this action is successful, then an additional action should be present on Bob.
Endorse Transfer of Ownership
Present state:
The token is held by Bob, token is owned by Charlie, no change in state from previous action.
Actions:
- Alice:
- no access
- Bob:
- change holder
- endorse transfer of ownership
- Charlie:
- nominate change of ownership
Notice that Bob actions have increased, it can now endorse the suggested owner from the previous action.
That is what we will do, and we will now perform endorse transfer of ownership.
What the command does is that it allows Bob to allow and complete the nominated change of ownership from Charlie to Alice.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow endorse-transfer-owner
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Enter the new beneficiary address: <ALICE_ADDRESS>
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to endorse the change of owner...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's owner has been successfully endorsed to approved beneficiary at <ALICE_ADDRESS>
Reject transfer of ownership
Present state:
The token is held by Bob, token is owned by Alice
Actions:
- Alice:
- nominate change of ownership
- reject transfer of ownership
- Bob:
- change holder
- Charlie:
- no access
Now we will do the reject change of owner command.
What this command does is it just sets the owner state to it's previous owner address.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow reject-transfer-owner
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to reject the change of owner...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's owner has been successfully rejected to previous owner
Final Action of Demonstration
Present state:
NOTE - Considering Alice actually not made the reject change of owner transaction.
The token is held by Bob, token is owned by Alice
Actions:
- Alice:
- nominate change of ownership
- Bob:
- change holder
- Charlie:
- no access
If the prev command worked as intended, then the new owner state of the token will be Alice.
we will wrap up this demonstration by changing the holder to Alice so we will come full circle.
The TrustVC CLI uses an interactive prompt system:
trustvc title-escrow transfer-holder
? Enter the path to the wrapped document: ./wrapped-documents/document-1.json
ℹ info Document signature verified successfully
? Enter the new holder address: <ALICE_ADDRESS>
? Select wallet type: Encrypted Wallet JSON
? Enter the path to your encrypted wallet JSON file: ./wallet.json
? Enter your wallet password: [hidden]
? Enter a remark (optional): <REMARK_STRING>
ℹ info Connecting to the registry and attempting to change the holder...
⠋ awaiting Waiting for transaction 0x... to be mined
✔ success Transferable record's holder has been successfully changed to holder with address: <ALICE_ADDRESS>
Final State:
The token is still held by Alice, the token is owned by Alice.
Conclusion:
In this demonstration, we have simulated a Title Transfer between 3 parties, going through each state change and the actions that could happen with each different state of the token.
This demonstration does not cover any return to issuer actions that could happen and it should be covered in an upcoming document.