This command line interface tool in the [OpenAttestation CLI](https://github.com/Open-Attestation/open-attestation-cli) repository turns `.json` documents into OpenAttestation verifiable documents. It applies the OpenAttestation algorithm to produce a has
npm install @govtechsg/open-attestation-cliThis command line interface tool in the OpenAttestation CLI repository turns .json documents into OpenAttestation verifiable documents. It applies the OpenAttestation algorithm to produce a hash of the .json document, and then creates a file with the data and proof of integrity.
There are two ways to install the CLI, including binary and NPM. Additionally, you can use NPX to execute the code in the package directly.
To install the binary on your operating system, download the corresponding file from the CLI release page.
>Note: There is an existing issue that the size of the binaries must be reduced, which is tracked in GitHub. If you want to contribute your feedback to resolve it, see this issue here.
If you are a Linux or MacOS user with npm installed on your machine, you can also install the CLI using the following command:
``bash`
npm install -g @govtechsg/open-attestation-cli
The above command will install the open-attestation CLI to your machine. Be sure to have node.js installed, so that you can run the command.
If you only want to execute a few commands, you can also opt to use npx:
`bash`
npx -p @govtechsg/open-attestation-cli open-attestation
Upon installation, a configuration folder will be created at ~/.config/open-attestation/.
>Important: The CLI is referred to as open-attestation when you run a command. The assumption is the CLI is available in your execution path. If not, you must change open-attestation to reflect the full path to the executable.
---
| Network ID | Name | Network | Type |
| ---------- | ------------------------ | ------------ | ---------- |
| 1 | Ethereum Mainnet | mainnet | Production |11155111
| | Ethereum Testnet Sepolia | sepolia | Test |137
| | Polygon Mainnet | polygon | Production |80002
| | Polygon Testnet Amoy | Amoy | Test |50
| | XDC Network | xdc | Production |51
| | XDC Apothem Network | xdcapothem | Test |
---
For more information on network fees, see the Ethereum documentation.
#### Adjusting preset gas price
To adjust transaction gas price, use the priority variable to scale against the market price.
>Calculation: Priority \* Previous block priority fee = Priority fee to use
The table below shows some examples:
| Priority | Previous block priority fee | Priority fee to use |
| -------- | --------------------------- | ------------------- |
| 1 | 1 | 1 \* 1 = 1 |
| 1.2 | 1 | 1.2 \* 1 = 1.2 |
| 2 | 1 | 2 \* 1 = 2 |
| 1 | 10 | 1 \* 10 = 10 |
| 1.2 | 10 | 1.2 \* 10 = 12 |
| 2 | 10 | 2 \* 10 = 20 |
#### Fee information
To display an estimated price of a transaction, use the --dry-run option in your command.
The following shows a command example:
`bash`
open-attestation deploy document-store "My Name" --network sepolia --dry-run
The response looks like:
`bash
/!\ Welcome to the fee table. Please read the information below to understand the transaction fee
The table below displays information about the cost of the transaction on the Mainnet network, depending on the gas price selected. Multiple modes are displayed to help you choose a gas price depending on your needs:
Information about the network:
Costs based on block number: 4275264
┌─────────┬──────────────┬──────────────────┬─────────────────────────────────┬────────────────────────┐
│ (index) │ block number │ gas price (gwei) │ max priority fee per gas (gwei) │ max fee per gas (gwei) │
├─────────┼──────────────┼──────────────────┼─────────────────────────────────┼────────────────────────┤
│ current │ 4275264 │ '0.629067134' │ '2.5' │ '3.758131382' │
└─────────┴──────────────┴──────────────────┴─────────────────────────────────┴────────────────────────┘
Information about the transaction:
Estimated gas required: 869810 gas, which will cost approximately US$0.86837 based on prevailing gas price.
┌──────────┬───────────────────────┬────────────────────┬───────────────────────┐
│ (index) │ gas cost │ priority fee price │ max fee price │
├──────────┼───────────────────────┼────────────────────┼───────────────────────┤
│ GWEI │ '547168.88382454' │ '2174525.0' │ '3268860.25737742' │
│ ETH │ '0.00054716888382454' │ '0.002174525' │ '0.00326886025737742' │
│ ETHUSD │ 0.86837 │ 3.45105 │ 5.18781 │
│ ETHSGD │ 1.18247 │ 4.69931 │ 7.06426 │
│ MATICUSD │ 0.00027 │ 0.00109 │ 0.00165 │
│ MATICSGD │ 0.00037 │ 0.00149 │ 0.00225 │
└──────────┴───────────────────────┴────────────────────┴───────────────────────┘
Please read the information above to understand the table
`
#### List of features with the required options
The following is a feature list and the options each feature requires.
| Feature | Private Key | Wallet | Aws Kms |
| -------------------------------------------------------------------------- | ----------- | ------ | ------- |
| Create config | ❎ | ✔️ | ❎ |
| Deploy document store | ✔ | ✔ | ✔ |
| Deploy token registry | ✔ | ✔ | ✔ |
| Dns txt create | ❎ | ❎ | ❎ |
| Dns txt get | ❎ | ❎ | ❎ |
| Document store issue | ✔ | ✔ | ✔ |
| Document store revoke | ✔ | ✔ | ✔ |
| Document store grant ownership | ✔ | ✔ | ✔ |
| Document store revoke ownership | ✔ | ✔ | ✔ |
| Document store transfer ownership | ✔ | ✔ | ✔ |
| Token registry issue | ✔ | ✔ | ✔ |
| Token registry mint | ✔ | ✔ | ✔ |
| Transaction cancel | ✔ | ✔ | ✔ |
| Wallet create | ❎ | ❎ | ❎ |
| Wallet decrypt | ❎ | ❎ | ❎ |
| Wallet encrypt | ✔ | ❎ | ❎ |
| Filter (obfuscate) document | ❎ | ❎ | ❎ |
| Sign document | ✔ | ❎ | ❎ |
| Encrypt document | ❎ | ❎ | ❎ |
| Decrypt document | ❎ | ❎ | ❎ |
| Wrap document | ❎ | ❎ | ❎ |
| Unwrap document | ❎ | ❎ | ❎ |
| Verify document | ❎ | ❎ | ❎ |
| Change holder (Title Escrow) | ✔ | ✔ | ✔ |
| Nominate change of owner (Title Escrow) | ✔ | ✔ | ✔ |
| Endorse transfer to owner (Title Escrow) | ✔ | ✔ | ✔ |
| Endorse change of owner (Title Escrow) | ✔ | ✔ | ✔ |
| Surrender document (Title Escrow) | ✔ | ✔ | ✔ |
| Reject surrendered document (Title Escrow) | ✔ | ✔ | ✔ |
| Accept surrendered document (Title Escrow) | ✔ | ✔ | ✔ |
The wrap command processes all documents in the input directory. It will add the issuance proofs to the individual documents. Additionally, you'll get the Batch Document Root (merkleRoot) value. Thereafter, you can issue all the documents in a single batch with the merkleRoot later.
The following shows a command example:
`bash`
open-attestation wrap ./examples/raw-documents/example.0.json
The response looks like:
`
✔ success Batch Document Root: 0xf51030c5751a646284c898cff0f9d833c64a50d6f307b61f2c96c3c838b13bfc
#### Specifying the output file while wrapping documents
The wrap command will display the result in the console. If you need to save the file, use the --output-file option in your command.
The following shows a command example with the --output-file option:
`bash`
open-attestation wrap ./examples/raw-documents/example.0.json --output-file ./examples/wrapped-documents/example.0.json
The response looks like:
`
✔ success Batch Document Root: 0x5d318c8083aac18f8075ca2a2eac74b06f2cc37d6ccad680c7c80c9bb36f7be1
#### Specifying the output directory while wrapping documents
If you need to wrap a folder, use the --output-dir option to specify in which folder all the documents will be wrapped.
The following shows a command example with the --output-dir option:
`bash`
open-attestation wrap ./examples/raw-documents --output-dir ./examples/wrapped-documents
The response looks like:
`
✔ success Batch Document Root: 0x5d318c8083aac18f8075ca2a2eac74b06f2cc37d6ccad680c7c80c9bb36f7be1
#### Providing an optional JSON schema while wrapping documents
You can also provide an optional JSON schema document using the --schema option to perform an extra check on the documents.
The following shows a command example with the --schema option:
`bash`
open-attestation wrap ./examples/raw-documents/ --output-dir ./examples/wrapped-documents/ --schema ./examples/schema.json
The response looks like:
`
✔ success Batch Document Root: 0xf51030c5751a646284c898cff0f9d833c64a50d6f307b61f2c96c3c838b13bfc
##### Short form of the --schema option
Alternatively, you can use -s in the command, which is the short form of --schema.
`bash`
open-attestation wrap ./examples/raw-documents/ ./examples/wrapped-documents/ -s ./examples/schema.json
The response looks like:
`
✔ success Batch Document Root: 0xf51030c5751a646284c898cff0f9d833c64a50d6f307b61f2c96c3c838b13bfc
##### HTTP endpoint in the --schema option
The schema parameter also accepts a remote JSON schema.
The following shows a command example containing an HTTP endpoint:
`bash`
open-attestation wrap ./examples/raw-documents/ --output-dir ./examples/wrapped-documents/ --schema https://gist.githubusercontent.com/Nebulis/dd8198ab76443489e14121dad225d351/raw/693b50a1694942fb3cc6a8dcf5187cc7c75adb58/schema.json
The response looks like:
`
✔ success Batch Document Root: 0xf51030c5751a646284c898cff0f9d833c64a50d6f307b61f2c96c3c838b13bfc
##### HTTP endpoint in the short form
Similarly, you can also use the short form -s to replace the --schema option in the command:
`bash`
open-attestation wrap ./examples/raw-documents/ --output-dir ./examples/wrapped-documents/ -s https://gist.githubusercontent.com/Nebulis/dd8198ab76443489e14121dad225d351/raw/693b50a1694942fb3cc6a8dcf5187cc7c75adb58/schema.json
The response looks like:
`
✔ success Batch Document Root: 0xf51030c5751a646284c898cff0f9d833c64a50d6f307b61f2c96c3c838b13bfc
#### Editing a wrapped document
You can also re-wrap a document through editing the wrapped document content and using the --unwrap option.
1. Run the command below to wrap a raw document:
`bash`
open-attestation wrap ./examples/raw-documents/example.0.json --output-file ./examples/wrapped-documents/example.0.json
2. After the first round of wrapping, edit the content in the wrapped document. For example, change your name to another name in .
3. To re-wrap the document after editing, run the command below with the --unwrap option:
`bash`
open-attestation wrap ./examples/wrapped-documents/example.0.json --of ./examples/wrapped-documents/example.1.json --unwrap
#### Wrapping documents individually
You can disable the --batched option to wrap multiple documents individually. Consequently, these documents will not have the same merkle root.
The following shows a command example with the --batched option disabled:
`bash`
open-attestation wrap ./examples/raw-documents/ --output-dir ./examples/wrapped-documents/ --batched false
The response looks like:
`
✔ success All documents have been individually wrapped
#### Changing the OpenAttestation CLI version
By default, the CLI will use OpenAttestation schema V2, but you can opt in for OpenAttestation schema V3 using the --open-attestation-v3 option:
`bash`
open-attestation wrap ./examples/raw-documents/ ./examples/wrapped-documents/ --open-attestation-v3
Alternatively, you can use the short form to replace --open-attestation-v3 in the command:
`bash`
open-attestation wrap ./examples/raw-documents/ ./examples/wrapped-documents/ --oav3
>Note: Transferable Records must be wrapped individually as each of them will be minted to a unique title escrow that represents the document's beneficiary and holder entities. For more information about title escrow, see here.
The unwrap command processes a wrapped document in the input directory. It will unwrap it to its raw document form, and display it in the console.
The following shows a command example of unwrap:
`bash`
open-attestation unwrap ./examples/v2/wrapped-documents/example.0.json
The response looks like:
`
✔ success The document has been unwrapped
#### Specifying the output file while unwrapping documents
The unwrap command will display the result in the console. If you need to save the file, use the --output-file option.
The following shows a command example with the --output-file option:
`bash`
open-attestation unwrap ./examples/v2/wrapped-documents/example.0.json --output-file ./examples/v2/raw-documents/example.0.json
The response looks like:
`
✔ success The document has been unwrapped
#### Specifying the output directory while unwrapping documents
If you need to unwrap a folder, use the --output-dir option to specify in which folder all the documents will be unwrapped.
The following shows a command example with the --output-dir option:
`bash`
open-attestation unwrap ./examples/v2/wrapped-documents --output-dir ./examples/v2/raw-documents
The response looks like:
`
✔ success The documents have been individually unwrapped into folder ./examples/v2/raw-documents
Using the filter command, the document holders can generate valid documents and obfuscate certain fields, such as those fields containing sensitive information that they prefer not to disclose.
The following shows the syntax of the filter command:
`bash`
open-attestation filter
The following is a command example:
`bash`
open-attestation filter examples/wrapped-documents/example.0.json tmp/example.0.out.json key1
The response looks like:
`
✔ success Obfuscated document saved to: tmp/example.0.out.json
With the encrypt command, you can encrypt the documents to share and store them safely.
The following shows the syntax of the encrypt command:
`bash`
open-attestation encrypt
The following is a command example:
`bash`
open-attestation encrypt ./examples/wrapped-documents/example.0.json ./tmp/encrypted.json
The response looks like:
`
✔ success Encrypted document saved to: tmp/encrypted.json
⚠ warning Here is the key to decrypt the document: don't lose it: 9bac5be27bac31d852fc1e48eb9d5249ec6ad7978da23377b5879f7a24994cb2
Using the decrypt command, you can decrypt documents that were encrypted using the encrypt method.
The following shows the syntax of the decrypt command:
`bash`
open-attestation decrypt
The following is a command example:
`bash`
open-attestation decrypt ./src/__tests__/fixture/did-dns-encrypted.json decrypted.json 88da9b9cd61cfc1677ae7e79dba9b3aeba4b40c95f94c950759e76c6210b5402
The response looks like:
`
✔ success Decrypted document saved to: decrypted.json
#### Deploying a new Token Registry
The deploy token-registry command deploys a token registry contract on the blockchain. You can use the --factory-address flag with the Factory Contract that were deployed using this command.
To deploy a standalone token registry, refer to the Token-Registry repository.
The following shows the syntax of the deploy token-registry command:
`bash`
open-attestation deploy token-registry
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation deploy token-registry "My Sample Token" MST --network sepolia
The response looks like:
`
✔ success Token registry deployed at 0x4B127b8d5e53872d403ce43414afeb1db67B1842
#### Issuing a document to token registry
The token-registry issue command issues a hash to a token registry deployed on the blockchain.
* The --tokenId option indicates the document hash--beneficiary
* The option indicates the beneficiary's wallet address--holder
* The option indicates the document holder's wallet address
The following shows the syntax of the token-registry issue command:
`bash`
open-attestation token-registry issue --network
>Important: In this command, you can use instead of issue and they will be strictly equivalent.
For more ways to provide the wallet, see here.
In the example below:
* You will use 0x6FFeD6E6591b808130a9b248fEA32101b5220eca as beneficiary and holder.
* You will need to replace the value above with a wallet address you control, to be able to perform different actions on the transferable records later.
* The key.txt file stores the private key to token registry.
`bash`
open-attestation token-registry issue --address 0x8431012Bc040942B59e3C5bf428221eab0b2f723 --tokenId 0x0d9839a8034cb783d98bd57bcbaafb4dc3614c4193d2edf8a655c1ec6635b7ea --beneficiary 0x6FFeD6E6591b808130a9b248fEA32101b5220eca --holder 0x6FFeD6E6591b808130a9b248fEA32101b5220eca -n sepolia -f key.txt
The response looks like:
`
✔ success Token with hash 0x0d9839a8034cb783d98bd57bcbaafb4dc3614c4193d2edf8a655c1ec6635b7ea has been issued on 0x8431012Bc040942B59e3C5bf428221eab0b2f723 with the initial recipient being 0x6FFeD6E6591b808130a9b248fEA32101b5220eca and initial holder 0x6FFeD6E6591b808130a9b248fEA32101b5220eca
#### Token Registry roles
The interfaces for the assignment and revocation of roles are available in the Token Registry repository.
#### Deploying a new document store
The deploy document-store command deploys a document store contract on the blockchain.
The following shows the command syntax:
`bash`
open-attestation deploy document-store
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation deploy document-store "My Name" --network sepolia
The response looks like:
`
✔ success Document store deployed at 0x4B127b8d5e53872d403ce43414afeb1db67B1842
##### Specifying a different owner
By default, the owner of the document store will be the deployer. You can specify a different owner using the --owner option.
The following shows a command example:
`bash`
open-attestation deploy document-store "My Name" --owner 0x1234 --network sepolia
#### Issuing a document to document store
The document-store issue command issues a hash to a document store deployed on the blockchain.
The following shows the command syntax:
`bash`
open-attestation document-store issue --address
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation document-store issue --network sepolia --address 0x19f89607b52268D0A19543e48F790c65750869c6 --hash 0x43033b53a462036304f526aeaf3aaeea8d905997d6fde3bb1a02188eadbaaec1
The response looks like:
`
✔ success Document/Document Batch with hash 0x0c1a666aa55d17d26412bb57fbed96f40ec5a08e2f995a108faf45429ae3511f has been issued on 0x19f89607b52268D0A19543e48F790c65750869c6
#### Revoking a document on document store
The document-store revoke command revokes a hash to a document store deployed on the blockchain.
The following shows the command syntax:
`bash`
open-attestation document-store revoke --address
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation document-store revoke --network sepolia --address 0x19f89607b52268D0A19543e48F790c65750869c6 --hash 0x43033b53a462036304f526aeaf3aaeea8d905997d6fde3bb1a02188eadbaaec1
The response looks like:
`
✔ success Document/Document Batch with hash 0x0c1a666aa55d17d26412bb57fbed96f40ec5a08e2f995a108faf45429ae3511f has been revoked on 0x19f89607b52268D0A19543e48F790c65750869c6
#### Granting a role on document store
The document-store grant-role command grants a role on the document store deployed on the blockchain to a wallet.
The following shows the command syntax:
`bash`
open-attestation document-store grant-role --address
The --role option accepts the following values:
- admin
-
-
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation document-store grant-role --address 0x80732bF5CA47A85e599f3ac9572F602c249C8A28 --new-owner 0xf81ea9d2c0133de728d28b8d7f186bed61079997 --role admin --network sepolia
The response looks like:
`
✔ success Document store 0x80732bF5CA47A85e599f3ac9572F602c249C8A28's role of: admin has been granted to wallet 0xf81ea9d2c0133de728d28b8d7f186bed61079997
#### Revoking a role on document store
The document-store revoke-role command revokes a role on the document store deployed on the blockchain to a wallet.
The following shows the command syntax:
`bash`
open-attestation document-store revoke-role --address
The --role option accepts the following values:
- admin
-
-
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation document-store revoke-role --address 0x80732bF5CA47A85e599f3ac9572F602c249C8A28 --new-owner 0xf81ea9d2c0133de728d28b8d7f186bed61079997 --role admin --network sepolia
The response looks like:
`
✔ success Document store 0x80732bF5CA47A85e599f3ac9572F602c249C8A28's role of: admin has been revoked from wallet 0xf81ea9d2c0133de728d28b8d7f186bed61079997
#### Transferring the ownership of document store
The document-store transfer-ownership command transfers the ownership of a document store deployed on the blockchain to another wallet.
The following shows the command syntax:
`bash`
open-attestation document-store transfer-ownership --address
For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the OA_PRIVATE_KEY environment variable.
`bash`
open-attestation document-store transfer-ownership --address 0x80732bF5CA47A85e599f3ac9572F602c249C8A28 --new-owner 0xf81ea9d2c0133de728d28b8d7f186bed61079997 --network sepolia
The response looks like:
`
✔ success Ownership of document store 0x80732bF5CA47A85e599f3ac9572F602c249C8A28 has been transferred to new wallet 0xf81ea9d2c0133de728d28b8d7f186bed61079997
The verify command runs the verification to check if a document is valid.
The following is a command example:
`bash`
open-attestation verify --document ./examples/wrapped-documents/example.0.json --network sepolia
The response looks like:
`
… awaiting Verifying examples/wrapped-documents/example.0.json
✔ success The document is valid
The sign command signs on an OA document directly with a private key.
The following is a command example:
`bash`
open-attestation sign ./examples/unsigned-documents -f ./examples/sample-key -p did:ethr:0x6813Eb9362372EEF6200f3b1dbC3f819671cBA69#controller --output-dir ./examples/signed-documents
You can create, retrieve, or filter DNS TXT records using the commands below.
#### Creating a temporary DNS TXT record
The dns text-record create command creates a temporary DNS TXT record in the OpenAttestation sandbox.
The following is a command example:
`bash`
open-attestation dns txt-record create --address 0xf51030c5751a646284c898cff0f9d833c64a50d6f307b61f2c96c3c838b13bfc --networkId 10
The response looks like:
`
✔ success Record created at exotic-blush-primate.sandbox.openattestation.com and will stay valid until Thu Jul 02 2020 13:51:34 GMT+0800 (Singapore Standard Time)
#### Getting the DNS TXT record list
The dns txt-record get command gets the list of DNS TXT records associated to a domain.
The following is a command example:
`bash`
open-attestation dns txt-record get --location resulting-magenta-locust.sandbox.openattestation.com
The response looks like:
`
┌─────────┬────────────┬────────────┬───────┬──────────┬────────┐
│ (index) │ type │ net │ netId │ addr │ dnssec │
├─────────┼────────────┼────────────┼───────┼──────────┼────────┤
│ 0 │ 'openatts' │ 'ethereum' │ '10' │ '0xabcd' │ false │
└─────────┴────────────┴────────────┴───────┴──────────┴────────┘
#### Filtering the DNS TXT record list
You can use the dns txt-record get command with the --networkId option to filter the list of DNS TXT records associated to a domain on a specific network.
The following is a command example:
`bash`
open-attestation dns txt-record get --location example.openattestation.com --networkId 3
The response looks like:
`
┌─────────┬────────────┬────────────┬───────┬──────────────────────────────────────────────┬────────┐
│ (index) │ type │ net │ netId │ addr │ dnssec │
├─────────┼────────────┼────────────┼───────┼──────────────────────────────────────────────┼────────┤
│ 0 │ 'openatts' │ 'ethereum' │ '3' │ '0x2f60375e8144e16Adf1979936301D8341D58C36C' │ false │
│ 1 │ 'openatts' │ 'ethereum' │ '3' │ '0x532C9Ff853CA54370D7492cD84040F9f8099f11B' │ false │
│ 2 │ 'openatts' │ 'ethereum' │ '3' │ '0x53f3a47C129Ea30D80bC727556b015F02bE63811' │ false │
│ 3 │ 'openatts' │ 'ethereum' │ '3' │ '0x8Fc57204c35fb9317D91285eF52D6b892EC08cD3' │ false │
│ 4 │ 'openatts' │ 'ethereum' │ '3' │ '0xdcA6Eea7024151c270b50FcA9E67161119B06BAD' │ false │
└─────────┴────────────┴────────────┴───────┴──────────────────────────────────────────────┴────────┘
You can create, encrypt, decrypt, or provide a wallet using the commands below.
#### Creating a wallet
The wallet create command creates a new wallet.
The following is a command example:
`bash`
open-attestation wallet create --of ./tmp
The response looks like:
`
ℹ info Creating a new wallet
? Wallet password [hidden]
… awaiting Encrypting Wallet [====================] [100/100%]
ℹ info Wallet with public address 0x6348a96D96D56665C2E9619f81355918779f3d9E successfully created. Find more details:
✔ success Wallet successfully saved into /path/to/tmp
#### Encrypting a wallet
Using the wallet encrypt command, you can encrypt a wallet.
>Note: If you want to provide the wallet private key, see the "Providing the wallet" section.
The following is a command example:
`bash`
open-attestation wallet encrypt --of ./tmp
The response looks like:
`
ℹ info Encrypting a wallet
? Wallet password [hidden]
… awaiting Encrypting Wallet [====================] [100/100%]
ℹ info Wallet with public address 0xB26B4941941C51a4885E5B7D3A1B861E54405f90 successfully created. Find more details:
✔ success Wallet successfully saved into /path/to/tmp
`
#### Decrypting a wallet
The wallet decrypt command decrypts a wallet to get its information.
>Important: Some information revealed by this command can be sensitive, e.g. the wallet private key.
The following is a command example:
`bash`
open-attestation wallet decrypt wallet.json
The response looks like:
`
⚠ warning You are about to reveal the private key of your wallet. Please type "yes" (without quotes) into the terminal to prove that you understand the risks
? ack: yes
ℹ info User consented to risks
? Wallet password [hidden]
… awaiting Decrypting Wallet [====================] [100/100%]
ℹ info Wallet successfully decrypted
✔ success Wallet information:
- address: 0x19bf1b00f78f521999d9A4246818F362fcaA1A96
- public key: 0x04e1a6facd0fee89e44ae51c1352e32224e79caaa3ccf5afa9d77f10f92f7c4c584ccdf6cfb9a71584c18408a1a0e12341556757268117afebda00d6d6e71133bf
- private key ....
#### Providing the wallet
When interacting with blockchain, you need to provide a way to access your wallet. All functions that require this provide multiple ways for you to enter your wallet information:
1. It is recommended to use the --encrypted-wallet-path option where you provide a path to an encrypted wallet.
1. Use the OA_PRIVATE_KEY environment variable to hold the private key.
1. Use the --key-file option where you provide a path to a file containing the private key.
1. Use the --key option where you provide the private key directly to the command.
>Important: When you use the --key option, the private key may be stored in the machine's bash history.
The following is a code example using the --encrypted-wallet-path option:
`bash`
open-attestation deploy document-store "My Name" --network sepolia --encrypted-wallet-path /path/to/wallet.json
The response looks like:
`bashThen you will be prompted to type your password to decrypt the wallet
? Wallet password [input is hidden]
$3
The
command generates a configuration file named config.json with sandbox DNS, document store, and token registry.>Note: You need a
wallet.json file with sufficient funds in the specified network for this command to work. Currently, OpenAttestation does not provide any faucet to dispense funds into wallet.json. You can search online for some faucets.You can use the following options in this command:
-
--output-dir option specifies in which folder the configuration file will be created.
- --encrypted-wallet-path option indicates a path to an encrypted wallet.-
--config-template-url option provides a path to reference a configuration template file hosted on a public URL.-
--config-template-path option provides a path to reference a config template file locally.There are two ways of using this command to generate a configuration file. Both ways will return a new configuration file with the sandbox DNS, updated document store, and updated token registry.
#### Method 1: Using the
config-template-url option (recommended)These are the reference config templates:
- V2 config template
- V3 config template
Step 1. Make sure the
wallet.json file has sufficient funds.`bash
open-attestation wallet create --output-file wallet.json
`Step 2. Generate the configuration file by providing the
file and a URL to the configuration file template.`
open-attestation config create --output-dir ./example-configs --encrypted-wallet-path /wallet.json
You need to provide certain information in the response:
// Please fill in the necessary information when prompted.
ℹ info Creating a new config file
? Wallet password [hidden]
? Using a config template URL? Yes
? Please enter the config template URL https://raw.githubusercontent.com/TradeTrust/tradetrust-config/master/build/reference/config-v2.json
? Select Network sepolia
#### Method 2: Using the
optionStep 1. Make sure the
wallet.json file has sufficient funds.`bash
open-attestation wallet create --output-file wallet.json
`Step 2. Generate the configuration file by providing the
file and an existing configuration file.`bash
open-attestation config create --output-dir ./example-configs --encrypted-wallet-path /wallet.json
`You need to provide certain information in the response:
// Please fill in the necessary information when prompted.
ℹ info Creating a new config file
? Wallet password [hidden]
? Using a config template URL? No
? Please enter the config template path /config.json
? Select Network sepolia
$3
The
command cancels a pending transaction.>Important: This action is irreversible.
You need to use the following options:
-
--nonce option specifies which transaction is to be canceled.-
--gas-price option specifies the gas price, which is required to be higher than the pending transaction.-
--transaction-hash option can be used as an alternative to the --nonce and --gas-price options. It will automatically increase the transaction gas price by 100%.- To learn more about the options for providing the wallet, see this GitHub readme.
The following is the command syntax:
`bash
open-attestation transaction cancel --nonce --gas-price [option]
`The following shows a command example with the
option:`bash
open-attestation transaction cancel --nonce 1 --gas-price 300 --network sepolia --encrypted-wallet-path /path/to/wallet
`
The following shows another example with the option:`bash
open-attestation transaction cancel --transaction-hash 0x000 --network sepolia --encrypted-wallet-path /path/to/wallet
`$3
#### Changing the holder
Using the
command, the owner of a transferable record can change the holder.The following shows the command syntax:
`bash
open-attestation title-escrow change-holder --token-registry --tokenId --newHolder [options]
`For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the
environment variable.
`bash
open-attestation title-escrow change-holder --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --newHolder 0xB26B4941941C51a4885E5B7D3A1B861E54405f90
`
The response looks like:
✔ success Transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990's holder has been successfully changed to holder with address: 0xB26B4941941C51a4885E5B7D3A1B861E54405f90
#### Nominating the change of owner
With the
command, the owner of the transferable record can nominate a new owner.>Important: This command will fail if you are not the owner of the transferable record.
The following shows the command syntax:
`bash
open-attestation title-escrow nominate-change-owner --token-registry --tokenId --newOwner [options]
`For more ways to provide the wallet, see here.
The following command is a recommended example with the private key set in the
environment variable.
The following shows a command example:
`bash
open-attestation title-escrow nominate-change-owner --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --newOwner 0xB26B4941941C51a4885E5B7D3A1B861E54405f90
`
The response looks like:
✔ success Transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990's holder has been successfully nominated to new owner with address: 0xB26B4941941C51a4885E5B7D3A1B861E54405f90
#### Endorsing the transfer to owner
Using the
command, the transferable record holder can endorse the transfer to an approved owner and holder.>Important: This command will fail if there is no approved owner or holder information on the transferable record.
The following is the command syntax:
`bash
open-attestation title-escrow endorse-transfer-owner --token-registry --tokenId --newBeneficiary [options]
`
For more ways to provide the wallet, see here.The following command is a recommended example with the private key set in the
environment variable.
The following shows a command example:
`bash
open-attestation title-escrow endorse-transfer-owner --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --newBeneficiary 0x2f60375e8144e16Adf1979936301D8341D58C36C
`
The response looks like:
✔ success Transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990's holder has been successfully endorsed to approved beneficiary at 0x2f60375e8144e16Adf1979936301D8341D58C36C
#### Endorsing the change of owner
Using the
command, the transferable record owner can endorse the change to a new owner and holder.>Important: This command will fail if the new holder and owner's addresses you provide are the same as the current owner and holder's addresses.
The following is the command syntax:
`bash
open-attestation title-escrow endorse-change-owner --token-registry --tokenId --newOwner --newHolder [options]
`
For more ways to provide the wallet, see here.The following command is a recommended example with the private key set in the
environment variable.
`bash
open-attestation title-escrow endorse-change-owner --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --newOwner 0xB26B4941941C51a4885E5B7D3A1B861E54405f90 --newHolder 0x2f60375e8144e16Adf1979936301D8341D58C36C
`
The response looks like:
✔ success Transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990's holder has been successfully endorsed to new owner with address 0x2f60375e8144e16Adf1979936301D8341D58C36C and new holder with address: 0xB26B4941941C51a4885E5B7D3A1B861E54405f90
#### Surrendering a document
With the
command, the entity (who is both an owner and a holder) can surrender the transferable record to the token registry.The following is the command syntax:
`bash
open-attestation title-escrow surrender --token-registry --tokenId [options]
`
For more ways to provide the wallet, see here.The following command is a recommended example with the private key set in the
environment variable.
`bash
open-attestation title-escrow reject-surrendered --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --network sepolia
`
The response looks like:
✔ success Transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 has been surrendered.
#### Rejecting a surrendered document
With the
command, the token registry can reject a surrendered transferable record.The following shows the command syntax:
`bash
open-attestation title-escrow reject-surrendered --token-registry --tokenId [options]
`
For more ways to provide the wallet, see here.The following command is a recommended example with the private key set in the
environment variable.
`bash
open-attestation title-escrow reject-surrendered --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --network sepolia
`
The response looks like:
✔ success Surrendered transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 has been rejected.
#### Accepting a surrendered document
Using the
command, the token registry will be able to accept a surrendered transferable record.The following shows the command syntax:
`bash
open-attestation title-escrow accept-surrendered --token-registry --tokenId [options]
`
For more ways to provide the wallet, see here.The following command is a recommended example with the private key set in the
environment variable.
`bash
open-attestation title-escrow accept-surrendered --token-registry 0x4933e30eF8A083f49d14759b2eafC94E56F0b3A7 --tokenId 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 --network sepolia
`
The response looks like:
✔ success Surrendered transferable record with hash 0x951b39bcaddc0e8882883db48ca258ca35ccb01fee328355f0dfda1ff9be9990 has been accepted.Help
To get additional information, run each of the following commands with the
option:`
open-attestation deploy
open-attestation document-store
open-attestation encrypt
open-attestation filter
open-attestation verify
open-attestation wrap
open-attestation sign
Development
To start a development server on the local machine, run the command below:
npm run dev --
To run tests for your projects, run the command below:
npm run test
Performance testing
To run performance testing for OA functionality, follow the instructions below.
$3
Using the
command, you can monitor the response time spent on wrapping a batch of documents.The default command (with no options) will test two documents without
base64 image in one iteration:`
npm run benchmark
The number of documents and iterations can be modified using these options below:
- First argument: The number of documents for batched wrapping
- Second argument: The number of performance test iterations to achieve higher accuracy
- Third argument: The file path for testing
>Important: For the Windows user, be sure to provide the file path in quotation marks "".
The following is a command example, testing four documents in one iteration from the specified path:
bash
npm run benchmark 4 1 performance-tests/unwrapped_document_wImage.json
``