NEAR Java 8+ API
This project implements the API to interact with a NEAR Node. It wraps the Json-RPC requests and maps the results to Java objects.
Dependencies
- Java 8+
- Maven (via wrapper)
Build instructions
./mvnw package
Using the Maven Central repository
Using Maven
<dependency>
<groupId>com.syntifi.near</groupId>
<artifactId>near-java-api</artifactId>
<version>0.1.0</version>
</dependency>
Using gradle
implementation 'com.syntifi.near:near-java-api:0.1.0'
References
This project used the following references:
- Official docs @ docs.near.org
How to
1. Set-up a connection
nearClient = NearService.usingPeer("archival-rpc.testnet.near.org");
2. Access Keys
2.1 View access key
Returns information about a single access key for given account.
If permission of the key is FunctionCall, it will return more details such as the allowance, receiver_id, and method_names.
By finality
String accountId = "client.chainlink.testnet";
String publicKey = "ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW";
AccessKey accessKey = nearClient.viewAccessKey(Finality.FINAL, accountId, publicKey);
By height
String accountId = "client.chainlink.testnet";
String publicKey = "ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW";
AccessKey accessKey = nearClient.viewAccessKey(78443365, accountId, publicKey);
By hash
String accountId = "client.chainlink.testnet";
String publicKey = "ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW";
AccessKey accessKey = nearClient.viewAccessKey("8bVg8wugs2QHqXr42oEsCYyH7jvR9pLaAP35dFqx2evU", accountId, publicKey);
2.2 View access key list
Returns all access keys for a given account.
By finality
String accountId = "client.chainlink.testnet";
AccessKeyList accessKeyList = nearClient.viewAccessKeyList(Finality.FINAL, accountId);
By height
String accountId = "client.chainlink.testnet";
AccessKeyList accessKeyList = nearClient.viewAccessKeyList(78772585, accountId);
By hash
String accountId = "client.chainlink.testnet";
AccessKeyList accessKeyList = nearClient.viewAccessKeyList("DwFpDPiQXBaX6Vw3aKazQ4nXjgzw1uk6XpUkfTSJrbXf", accountId);
2.3 View access key changes (single)
Returns individual access key changes in a specific block. You can query multiple keys by passing an array of objects containing the account_id and public_key.
By finality
Key[] keys = new Key[1];
Key key0 = new Key("example-acct.testnet", "ed25519:25KEc7t7MQohAJ4EDThd2vkksKkwangnuJFzcoiXj9oM");
keys[0] = key0;
AccessKeyChanges accessKeyChanges = nearClient.viewSingleAccessKeyChanges(Finality.FINAL, keys);
By height
Key[] keys = new Key[1];
Key key0 = new Key("example-acct.testnet", "ed25519:25KEc7t7MQohAJ4EDThd2vkksKkwangnuJFzcoiXj9oM");
keys[0] = key0;
AccessKeyChanges accessKeyChanges = nearClient.viewSingleAccessKeyChanges(78433961, keys);
By hash
Key[] keys = new Key[1];
Key key0 = new Key("example-acct.testnet", "ed25519:25KEc7t7MQohAJ4EDThd2vkksKkwangnuJFzcoiXj9oM");
keys[0] = key0;
AccessKeyChanges accessKeyChanges = nearClient.viewSingleAccessKeyChanges("Cr82U81VqHgCz9LzZjPivh9t16e8es6aFCv9qvDMMH88", keys);
2.4 View access key changes (all)
Returns changes to all access keys of a specific block. Multiple accounts can be quereied by passing an array of account_ids.
By finality
String[] accountIds = new String[1];
accountIds[0] = "client.chainlink.testnet";
AccessKeyChanges accessKeyChanges = nearClient.viewAllAccessKeyChanges(Finality.FINAL, accountIds);
By height
String[] accountIds = new String[1];
accountIds[0] = "client.chainlink.testnet";
AccessKeyChanges accessKeyChanges = nearClient.viewAllAccessKeyChanges(78433518, accountIds);
By hash
String[] accountIds = new String[1];
accountIds[0] = "client.chainlink.testnet";
AccessKeyChanges accessKeyChanges = nearClient.viewAllAccessKeyChanges("Ais9kPbHvk6XmEYptoEpBtyFW77V16TZNHHnYtmXWr1d",accountIds);
3. Accounts / Contracts
3.1 View account
Returns basic account information.
By finality
Account account = nearClient.viewAccount(Finality.FINAL, "nearkat.testnet");
By height
Account account = nearClient.viewAccount(78439658, "nearkat.testnet");
By hash
Account account = nearClient.viewAccount("5hyGx7LiGaeRiAN4RrKcGomi1QXHqZwKXFQf6xTmvUgb", "nearkat.testnet");
3.2 View account changes
Returns account changes from transactions in a given account.
By finality
String[] accountIds = new String[1];
accountIds[0] = "nearkat.testnet";
AccountChanges accountChanges = nearClient.viewAccountChanges(Finality.FINAL, accountIds);
By height
String[] accountIds = new String[1];
accountIds[0] = "nearkat.testnet";
AccountChanges accountChanges = nearClient.viewAccountChanges(78440142, accountIds);
By hash
String[] accountIds = new String[1];
accountIds[0] = "nearkat.testnet";
AccountChanges accountChanges = nearClient.viewAccountChanges("7vWp2djKLoJ3RE1sr8RzSKQtyzKpe2wZ7NCcDuFNuL7j", accountIds);
3.3 View contract code
Returns the contract code (Wasm binary) deployed to the account. Please note that the returned code will be encoded in base64.
By finality
ContractCode contractCode = nearClient.viewContractCode(Finality.FINAL, "guest-book.testnet");
By height
ContractCode contractCode = nearClient.viewContractCode(78440518, "guest-book.testnet");
By hash
ContractCode contractCode = nearClient.viewContractCode("uLxyauKPhSk1tebYKi3k69pHSaT2ZLzWy4JwtGm52pu", "guest-book.testnet");
3.4 View contract state
Returns the state (key value pairs) of a contract based on the key prefix (base64 encoded). Pass an empty string for prefix_base64 if you would like to return the entire state. Please note that the returned state will be base64 encoded as well.
By finality
ContractState contractState = nearClient.viewContractState(Finality.FINAL, "guest-book.testnet", "");
By height
ContractState contractState = nearClient.viewContractState(78440679, "guest-book.testnet", "");
By hash
ContractState contractState = nearClient.viewContractState("342bkjvnzoZ7FGRE5BwDVkzSRUYXAScTz3GsDB9sEHXg", "guest-book.testnet", "");
3.5 View contract state changes
Returns the state change details of a contract based on the key prefix (encoded to base64). Pass an empty string for this param if you would like to return all state changes.
By finality
String[] accountIds = new String[1];
accountIds[0] = "guest-book.testnet";
ContractStateChanges contractStateChanges = nearClient.viewContractStateChanges(Finality.FINAL, accountIds, "");
By height
String[] accountIds = new String[1];
accountIds[0] = "guest-book.testnet";
ContractStateChanges contractStateChanges = nearClient.viewContractStateChanges(78441183, accountIds, "");
By hash
String[] accountIds = new String[1];
accountIds[0] = "guest-book.testnet";
ContractStateChanges contractStateChanges = nearClient.viewContractStateChanges("5KgQ8uu17bhUPnMUbkmciHxbpFvsbhwdkJu4ptRfR7Zn", accountIds, "");
3.6 View contract code changes
Returns code changes made when deploying a contract. Change is returned is a base64 encoded WASM file.
By finality
String[] accountIds = new String[1];
accountIds[0] = "dev-1602714453032-7566969";
ContractCodeChanges contractCodeChanges = nearClient.viewContractCodeChanges(Finality.FINAL, accountIds);
By height
String[] accountIds = new String[1];
accountIds[0] = "dev-1602714453032-7566969";
ContractCodeChanges contractCodeChanges = nearClient.viewContractCodeChanges(78441560, accountIds);
By hash
String[] accountIds = new String[1];
accountIds[0] = "dev-1602714453032-7566969";
ContractCodeChanges contractCodeChanges = nearClient.viewContractCodeChanges("HpsjZvjtuxarKRsXGVrgB6qtuCcHRgx3Xof1gfT2Jfj7", accountIds);
3.7 Call a contract function
Allows you to call a contract method as a view function.
By finality
ContractFunctionCallResult contractFunctionCallResult = nearClient
.callContractFunction(
Finality.FINAL,
"guest-book.testnet",
"getMessages",
"e30=");
By height
ContractFunctionCallResult contractFunctionCallResult = nearClient
.callContractFunction(79272492,
"guest-book.testnet",
"getMessages",
"e30=");
By hash
ContractFunctionCallResult contractFunctionCallResult = nearClient
.callContractFunction(
"J5QTB4Stz3iwtHvgr5KnVzNUgzm4J1bE5Et6JWrJPC8o",
"guest-book.testnet",
"getMessages",
"e30=");
4. Block / Chunk
4.1 Block details
Queries network and returns block for given height or hash. You can also use finality param to return latest block details.
By finality
Block block = nearClient.getBlock(Finality.FINAL);
By height
Block block = nearClient.getBlock(78770817);
By hash
Block block = nearClient.getBlock("FXTWzPjqWztjHfneqJb9cBDB2QLTY1Rja4GHrswAv1b9");
4.2 Changes in Block
Returns changes in block for given block height or hash. You can also use finality param to return latest block details.
By finality
BlockChanges blockChanges = nearClient.getBlockChanges(Finality.FINAL);
By height
BlockChanges blockChanges = nearClient.getBlockChanges(78770674);
By hash
BlockChanges blockChanges = nearClient.getBlockChanges("BmEZnrmov6h6rMPpWkMV2JtU1C5LP563V5Y5yXwUW2N5");
4.3 Chunk Details
Returns details of a specific chunk. You can run a block details query to get a valid chunk hash.
By finality
Chunk chunk = nearClient.getChunkDetails("9mdG2cRcV8Dsb1EoSjtya81NddjRB2stYCTVukZh7zzw");
By block height and shard id
Chunk chunk = nearClient.getChunkDetails(78567387, 0);
By block hash and shard id
Chunk chunk = nearClient.getChunkDetails("F1HXTzeYgYq28rgsHuKUrRbo5QTBGKFYG7rbxXkRZWXN", 0);
5. Gas
5.1 Gas Price
Returns gas price for a specific block_height or block_hash.
- Using [null] will return the most recent block’s gas price.
Null
GasPrice gasPrice = nearClient.getGasPrice(null);
By height
GasPrice gasPrice = nearClient.getGasPrice(78770817);
By hash
GasPrice gasPrice = nearClient.getGasPrice("FXTWzPjqWztjHfneqJb9cBDB2QLTY1Rja4GHrswAv1b9");
6. Protocol
6.1 Genesis Config
Returns current genesis configuration.
Example
GenesisConfig genesisConfig = nearClient.getGenesisConfig();
6.2 Protocol Config
Returns most recent protocol configuration or a specific queried block. Useful for finding current storage and transaction costs.
By finality
ProtocolConfig protocolConfig = nearClient.getProtocolConfig(Finality.FINAL);
By height
ProtocolConfig protocolConfig = nearClient.getProtocolConfig(78770817);
By hash
ProtocolConfig protocolConfig = nearClient.getProtocolConfig("FXTWzPjqWztjHfneqJb9cBDB2QLTY1Rja4GHrswAv1b9");
7. Network
7.1 Node Status
Returns general status of a given node (sync status, nearcore node version, protocol version, etc), and the current set of validators.
Example
NodeStatus nodeStatus = nearClient.getNodeStatus();
7.2 Network Info
Returns the current state of node network connections (active peers, transmitted data, etc.)
Example
NetworkInfo networkInfo = nearClient.getNetworkInfo();
7.3 Validation Status
Queries active validators on the network returning details and the state of validation on the blockchain.
Null
ValidationStatus networkValidationStatus = nearClient.getNetworkValidationStatus(null);
By height
Block lastBlock = nearClient.getBlock(Finality.OPTIMISTIC);
ValidationStatus networkValidationStatus = nearClient.getNetworkValidationStatus(lastBlock.getHeader().getHeight());
By hash
Block lastBlock = nearClient.getBlock(Finality.FINAL);
ValidationStatus networkValidationStatus = nearClient.getNetworkValidationStatus(lastBlock.getHeader().getHash());
8. Transactions
8.1 Send transaction (async)
Sends a transaction and immediately returns transaction hash.
Example
String signerId = "syntifi-bob.testnet";
String receiverId = "syntifi-alice.testnet";
BigInteger amount = new BigInteger("100", 10);
EncodedHash transactionAsync = TransactionService
.sendTransferActionAsync(nearClient, signerId, receiverId, bobNearPublicKey, bobNearPrivateKey, amount);
8.2 Send transaction (await)
Sends a transaction and waits until transaction is fully complete. (Has a 10 second timeout)
Example
String signerId = "syntifi-alice.testnet";
String receiverId = "syntifi-bob.testnet";
BigInteger amount = new BigInteger("100", 10);
TransactionAwait transactionAwait = TransactionService
.sendTransferActionAwait(nearClient, signerId, receiverId, aliceNearPublicKey, aliceNearPrivateKey, amount);
8.3 Transaction Status
Queries status of a transaction by hash and returns the final transaction result.
Example
String transactionHash = "DwWUi6WbVHKTCDjVu4gmuQfryqjwTjrZ6ntRcKcGN6Gd";
String accountId = "isonar.testnet";
TransactionStatus transactionStatus = nearClient.getTransactionStatus(transactionHash, accountId);
8.4 Transaction Status with Receipts
Queries status of a transaction by hash, returning the final transaction result and details of all receipts.
Example
String transactionHash = "DwWUi6WbVHKTCDjVu4gmuQfryqjwTjrZ6ntRcKcGN6Gd";
String accountId = "isonar.testnet";
TransactionStatus transactionStatusWithReceipts = nearClient.getTransactionStatusWithReceipts(transactionHash, accountId);
8.5 Receipt by ID
Fetches a receipt by it’s ID (as is, without a status or execution outcome)
Example
String receiptId = "8b9Vt1xH8DZecMda1YqUcMWA41NvknUJJVd2XEQikPRs";
Receipt transactionReceipt = nearClient.getTransactionReceipt(receiptId);
9. Json File Wallets
9.1 Loads a Wallet from a json file
Loads a Wallet object from a json file.
Example
String fileName = "./my-wallet.json";
WalletService.writeWalletToFile(fileName, wallet)
9.2 Writes a Wallet to a json file
Writes a Wallet object to a json file.
Example
String fileName = "./my-wallet.json";
Wallet wallet = WalletService.loadWalletFromFile(fileName);