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

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");

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);

syntifi/near-java-api

NEAR Java 8+ API

Dependencies

Build instructions

Using the Maven Central repository

Using Maven

Using gradle

References

How to

1. Set-up a connection

2. Access Keys

2.1 View access key

2.2 View access key list

2.3 View access key changes (single)

2.4 View access key changes (all)

3. Accounts / Contracts

3.1 View account

3.2 View account changes

3.3 View contract code

3.4 View contract state

3.5 View contract state changes

3.6 View contract code changes

3.7 Call a contract function

4. Block / Chunk

4.1 Block details

4.2 Changes in Block

4.3 Chunk Details

5. Gas

5.1 Gas Price

6. Protocol

6.1 Genesis Config

6.2 Protocol Config

7. Network

7.1 Node Status

7.2 Network Info

7.3 Validation Status

8. Transactions

8.1 Send transaction (async)

8.2 Send transaction (await)

8.3 Transaction Status

8.4 Transaction Status with Receipts

8.5 Receipt by ID

9. Json File Wallets

9.1 Loads a Wallet from a json file

9.2 Writes a Wallet to a json file