Transactions
To install the SDK, please refer to the Getting Started page. Once this is done and you have installed the uledger-sdk using npm, you may proceed with the following steps.
The code snippet below is an implementation of creating a transaction and submitting it to the blockchain using the ULedger SDK.
This tutorial assumes that you have an existing blockchain set up with ULedger. To execute this successfully, you will need to replace the placeholder values with real values. This includes your node url, the node id, the url to the atomic clock service, and blockchain id. For additional information, please visit Getting Started and Import ULedger SDK
To complete this step correctly, please make sure you have a wallet set up with ULedger. For more information vistit the crypto wallets tutorial
Transaction Input Structure
For the transaction input, it's important to understand each field. There are size limits to the fields. However, following this guide, you should not have any issues.
const txnInputData: ULedgerTransactionInput = {
blockchainId: "my-test-network",
to: my_address,
payload: {
myPayload: "Hello World!",
foo: "bar",
sampleData: 100
},
payloadType: "DATA"
}
blockchainId: This field should be provided by the ULedger team or can be found on the ULedger portal.
to: This should be the wallet address of the sender. For additional information, please see the section above. In short, to derive your wallet address, take a SHA256 hash of your public key and encode the result in Hexadecimal.
payload: For the payload field, you can use a custom JSON structure. This is where you should input your application-specific data. Take a voting application, for example; you may want to structure your payload like this: payload: {vote_id: 023948, vote_selection: true}.
payloadType: At this moment, the only payload type supported is "DATA." Please use this value and keep an eye out for updates!
Finally, we have our transaction ready and need to upload it to the blockchain network. This is done in the code sample below. It's very simple, we pass in the transaction input created above and the return type is a minted transaction on the blockchain.
// Send the request to the node
const txn = await txnSession.createTransaction(txnInputData);
// Show the result
console.log(txn);
Great work! You've created the first transaction with your new wallet! Once the block has been minted your should be able to query it on our blockchain explorer.
Building the example
Please make sure to replace the placeholder values in the code, specifically service URL's and your blockchain id.
You can run the code using the command below,
ts-node index.ts
🔎 Search Transactions
To install the SDK, please refer to the Getting Started page. Once this is done and you have installed the uledger-sdk using npm, you may proceed with the following steps.
The code snippets provided below serve as examples of how to search for transactions using the ULedger SDK. When searching for transactions, it's important to consider the scope of your search, which may depend on your application's requirements or the information you have regarding the transaction. You have the option to pull transactions by searching with the blockchain ID, transaction ID, block ID, or wallet address. In this tutorial, we will walk you through each method.
This tutorial assumes that you have an existing blockchain set up with ULedger. To execute this successfully, you will need to have a BMS Session created. For additional information, please visit Getting Started and Import ULedger SDK.
Search Transactions by Blockchain ID
In the code below, you can see how we're searching for transactions using the blockchain ID. This method is straightforward because the search parameter is static. Besides that, there are additional parameters used in the function call. Let's go over each one.
- Limit: Indicates the maximum number of transactions that should be returned.
- Offset: Indicates if you would like to offset the index. This allows us to move the starting point of the response array.
- Sort: A boolean value that indicates if you would like the response array to be sorted by time. When set to true, the array will be ordered from newest to oldest.
- Trim: A boolean parameter that indicates if you would like the transactions to omit the payload data.
const limit = 10;
const offset = 0;
const sort = true;
const trim = false;
const txns = await session.listTransactions("{{blockchain id}}", limit, offset, sort, trim);
console.log("Retrieved transactions in chain:\n", txns);
Search Transactions by Wallet Address
In the code below, we demonstrate how to search for transactions using a wallet address. This approach is particularly useful for application development because it enables you to associate wallets with individual users, allowing them to track their own transactional activity.
- Limit: Indicates the maximum number of transactions that should be returned.
- Offset: Indicates if you would like to offset the index. This allows us to move the starting point of the response array.
- Sort: A boolean value that indicates if you would like the response array to be sorted by time. When set to true, the array will be ordered from newest to oldest.
- Trim: A boolean parameter that indicates if you would like the transactions to omit the payload data.
- publicBool: Indicates if you're querying a public or private chain.
// Search terms - which blockchain and which user are we looking for?
const blockchainId = "{{blockchain id}}";
const userIdKeyword = "1b";
// Pagination parameters
const limit = 10;
const offset = 0;
const sort = true;
// Should we exclude the transactions' payloads?
const trim = true;
// Send the request
const history = await session.userHistory(blockchainId, userIdKeyword, limit, offset, sort, trim);
// Log the result
console.log(`Transactions FROM userIds matching '${userIdKeyword}':`);
console.log(history.from);
console.log(`\nTransactions TO userIds matching '${userIdKeyword}':`);
console.log(history.to);
Search Transactions by Transaction ID
In the code below, you will see the method for searching for an individual transaction using the transaction ID. This is useful when you need to retrieve a specific transaction. The trim parameter is a boolean that specifies whether you want the transaction details to exclude the payload data.
// "trim" = exclude the inner payload of the transaction
const trim = true;
// List transaction by id
const txn = await session.searchTransactionById("{{transaction id}}", trim);
console.log("Retrieved transaction by ID:\n", txn);
Search Transactions by Block ID
This method conducts a paginated search through all transactions within a specific block. When provided with a block ID, the function returns a list of transactions contained in that block. It accepts pagination parameters, such as limit and offset. Additionally, there is a sort boolean parameter—if set to true, the function sorts the array of transactions by their timestamp.
Another boolean parameter is trim; when set to true, the function omits the payload from each transaction, returning only the transaction metadata. The response includes three main components: index, count, and payload. Index indicates the pagination index of the items within the payload. Count denotes the total number of transactions found in the specified block. The payload is an array of the transactions that fall within the set pagination parameters for the provided block ID.
- Limit: Indicates the maximum number of transactions that should be returned.
- Offset: Indicates if you would like to offset the index. This allows us to move the starting point of the response array.
- Sort: A boolean value that indicates if you would like the response array to be sorted by time. When set to true, the array will be ordered from newest to oldest.
- Trim: A boolean parameter that indicates if you would like the transactions to omit the payload data.
// Pagination customizations
const limit = 10;
const offset = 0;
const sort = true;
// "trim" = exclude the inner payload of the transactions
const trim = true;
// List transactions in a block
const txns = await session.transactionsFromBlock("{{block id}}", limit, offset, sort, trim);
console.log("Retrieved transactions from block:\n", txns);
Troubleshooting/FAQ
Below are a few examples of known issues or just things to look for if you're having issues creating transactions.
Transaction Creates Successfully in My Code but Is Not Appearing on the Blockchain Explorer:
One possibility is that the block has not been minted yet. In this case, just wait a few minutes and check again. It usually takes about 5 minutes for a block to be minted.
Additionally, this could be because your transaction is exceeding the data size limits. The custom payload section needs to be under 512 bytes. Also, there are size limits on the "to," "from," and "senderSignature." Please refer to the sections above on how to successfully derive your wallet address and transaction signature.
Failing to Create Transaction in My Code:
- Please double-check the placeholder values. Ensure that you're using the correct blockchainId, NodeUrl, NodeId, and AtomicClockUrl.
