Skip to content

Latest commit

 

History

History
607 lines (411 loc) · 24.6 KB

README.md

File metadata and controls

607 lines (411 loc) · 24.6 KB
Raw

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:

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