FOR REVIEW ONLY - java-algorand-sdk 1.20.0

.test-env

@@ -3,6 +3,8 @@ SDK_TESTING_URL="https://github.com/algorand/algorand-sdk-testing"
 SDK_TESTING_BRANCH="master"
 SDK_TESTING_HARNESS="test-harness"
 
+INSTALL_ONLY=0
+
 VERBOSE_HARNESS=0
 
 # WARNING: If set to 1, new features will be LOST when downloading the test harness.

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 1.20.0
+
+### Enhancements
+* REST API: Add algod block hash endpoint, add indexer block header-only param. by @winder in https://github.com/algorand/java-algorand-sdk/pull/413
+
 # 1.19.0
 
 ### Enhancements

Makefile

@@ -11,7 +11,10 @@ display-all-java-steps:
 	find src/test/java/com/algorand/algosdk -name "*.java" | xargs grep "io.cucumber.java.en" 2>/dev/null | grep -v Binary | cut -d: -f1 | sort | uniq | xargs grep -E "@(Given|Then|When)"
 
 harness:
-	./test-harness.sh
+	./test-harness.sh up
+
+harness-down:
+	./test-harness.sh down
 
 docker-javasdk-build:
 	# Build SDK testing environment

README.md

@@ -19,7 +19,7 @@ Maven:
 <dependency>
     <groupId>com.algorand</groupId>
     <artifactId>algosdk</artifactId>
-    <version>1.19.0</version>
+    <version>1.20.0</version>
 </dependency>
 ```
 

pom.xml

@@ -4,7 +4,7 @@
 
     <groupId>com.algorand</groupId>
     <artifactId>algosdk</artifactId>
-    <version>1.19.0</version>
+    <version>1.20.0</version>
     <packaging>jar</packaging>
 
     <name>${project.groupId}:${project.artifactId}</name>

src/main/java/com/algorand/algosdk/v2/client/algod/GetBlockHash.java

@@ -0,0 +1,65 @@
+package com.algorand.algosdk.v2.client.algod;
+
+import com.algorand.algosdk.v2.client.common.Client;
+import com.algorand.algosdk.v2.client.common.HttpMethod;
+import com.algorand.algosdk.v2.client.common.Query;
+import com.algorand.algosdk.v2.client.common.QueryData;
+import com.algorand.algosdk.v2.client.common.Response;
+import com.algorand.algosdk.v2.client.model.BlockHashResponse;
+
+
+/**
+ * Get the block hash for the block on the given round.
+ * /v2/blocks/{round}/hash
+ */
+public class GetBlockHash extends Query {
+
+    private Long round;
+
+    /**
+     * @param round The round from which to fetch block hash information.
+     */
+    public GetBlockHash(Client client, Long round) {
+        super(client, new HttpMethod("get"));
+        this.round = round;
+    }
+
+   /**
+    * Execute the query.
+    * @return the query response object.
+    * @throws Exception
+    */
+    @Override
+    public Response<BlockHashResponse> execute() throws Exception {
+        Response<BlockHashResponse> resp = baseExecute();
+        resp.setValueType(BlockHashResponse.class);
+        return resp;
+    }
+
+   /**
+    * Execute the query with custom headers, there must be an equal number of keys and values
+    * or else an error will be generated.
+    * @param headers an array of header keys
+    * @param values an array of header values
+    * @return the query response object.
+    * @throws Exception
+    */
+    @Override
+    public Response<BlockHashResponse> execute(String[] headers, String[] values) throws Exception {
+        Response<BlockHashResponse> resp = baseExecute(headers, values);
+        resp.setValueType(BlockHashResponse.class);
+        return resp;
+    }
+
+    protected QueryData getRequestString() {
+        if (this.round == null) {
+            throw new RuntimeException("round is not set. It is a required parameter.");
+        }
+        addPathSegment(String.valueOf("v2"));
+        addPathSegment(String.valueOf("blocks"));
+        addPathSegment(String.valueOf(round));
+        addPathSegment(String.valueOf("hash"));
+
+        return qd;
+    }
+}

src/main/java/com/algorand/algosdk/v2/client/common/AlgodClient.java

@@ -10,6 +10,7 @@
 import com.algorand.algosdk.v2.client.algod.AccountApplicationInformation;
 import com.algorand.algosdk.v2.client.algod.GetPendingTransactionsByAddress;
 import com.algorand.algosdk.v2.client.algod.GetBlock;
+import com.algorand.algosdk.v2.client.algod.GetBlockHash;
 import com.algorand.algosdk.v2.client.algod.GetTransactionProof;
 import com.algorand.algosdk.v2.client.algod.GetSupply;
 import com.algorand.algosdk.v2.client.algod.GetStatus;
@@ -141,6 +142,14 @@ public GetBlock GetBlock(Long round) {
         return new GetBlock((Client) this, round);
     }
 
+    /**
+     * Get the block hash for the block on the given round.
+     * /v2/blocks/{round}/hash
+     */
+    public GetBlockHash GetBlockHash(Long round) {
+        return new GetBlockHash((Client) this, round);
+    }
+
     /**
      * Get a proof for a transaction in a block.
      * /v2/blocks/{round}/transactions/{txid}/proof

src/main/java/com/algorand/algosdk/v2/client/indexer/LookupBlock.java

@@ -24,6 +24,15 @@ public LookupBlock(Client client, Long roundNumber) {
         this.roundNumber = roundNumber;
     }
 
+    /**
+     * Header only flag. When this is set to true, returned block does not contain the
+     * transactions
+     */
+    public LookupBlock headerOnly(Boolean headerOnly) {
+        addQuery("header-only", String.valueOf(headerOnly));
+        return this;
+    }
+
    /**
     * Execute the query.
     * @return the query response object.

src/main/java/com/algorand/algosdk/v2/client/model/Block.java

@@ -33,6 +33,12 @@ public String genesisHash() {
     @JsonProperty("genesis-id")
     public String genesisId;
 
+    /**
+     * Participation account data that needs to be checked/acted on by the network.
+     */
+    @JsonProperty("participation-updates")
+    public ParticipationUpdates participationUpdates;
+
     /**
      * (prev) Previous block hash.
      */
@@ -150,6 +156,7 @@ public boolean equals(Object o) {
         Block other = (Block) o;
         if (!Objects.deepEquals(this.genesisHash, other.genesisHash)) return false;
         if (!Objects.deepEquals(this.genesisId, other.genesisId)) return false;
+        if (!Objects.deepEquals(this.participationUpdates, other.participationUpdates)) return false;
         if (!Objects.deepEquals(this.previousBlockHash, other.previousBlockHash)) return false;
         if (!Objects.deepEquals(this.rewards, other.rewards)) return false;
         if (!Objects.deepEquals(this.round, other.round)) return false;

src/main/java/com/algorand/algosdk/v2/client/model/BlockHashResponse.java

@@ -0,0 +1,30 @@
+package com.algorand.algosdk.v2.client.model;
+
+import java.util.Objects;
+
+import com.algorand.algosdk.v2.client.common.PathResponse;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Hash of a block header.
+ */
+public class BlockHashResponse extends PathResponse {
+
+    /**
+     * Block header hash.
+     */
+    @JsonProperty("blockHash")
+    public String blockHash;
+
+    @Override
+    public boolean equals(Object o) {
+
+        if (this == o) return true;
+        if (o == null) return false;
+
+        BlockHashResponse other = (BlockHashResponse) o;
+        if (!Objects.deepEquals(this.blockHash, other.blockHash)) return false;
+
+        return true;
+    }
+}

src/main/java/com/algorand/algosdk/v2/client/model/ParticipationUpdates.java

@@ -0,0 +1,33 @@
+package com.algorand.algosdk.v2.client.model;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+import com.algorand.algosdk.v2.client.common.PathResponse;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Participation account data that needs to be checked/acted on by the network.
+ */
+public class ParticipationUpdates extends PathResponse {
+
+    /**
+     * (partupdrmv) a list of online accounts that needs to be converted to offline
+     * since their participation key expired.
+     */
+    @JsonProperty("expired-participation-accounts")
+    public List<String> expiredParticipationAccounts = new ArrayList<String>();
+
+    @Override
+    public boolean equals(Object o) {
+
+        if (this == o) return true;
+        if (o == null) return false;
+
+        ParticipationUpdates other = (ParticipationUpdates) o;
+        if (!Objects.deepEquals(this.expiredParticipationAccounts, other.expiredParticipationAccounts)) return false;
+
+        return true;
+    }
+}

src/test/java/com/algorand/algosdk/unit/AlgodPaths.java

@@ -98,4 +98,9 @@ public void getLightBlockHeaderProof(Long round) {
     public void getStateProof(Long round) {
         ps.q = algodClient.GetStateProof(round);
     }
+
+    @When("we make a Lookup Block Hash call against round {long}")
+    public void getBlockHash(Long round) {
+        ps.q = algodClient.GetBlockHash(round);
+    }
 }

src/test/java/com/algorand/algosdk/unit/IndexerPaths.java

@@ -333,4 +333,11 @@ public void searchForApplications(String string) {
         ps.q = q;
     }
 
+
+    @When("we make a Lookup Block call against round {long} and header {string}")
+    public void anyBlockLookupCall(Long round, String headerOnly) {
+        LookupBlock q = this.indexerClient.lookupBlock(round);
+        if (headerOnly.contentEquals("true")) q.headerOnly(true);
+        ps.q = q;
+    }
 }

src/test/java/com/algorand/algosdk/unit/ResponsesShared.java

@@ -191,6 +191,9 @@ public void we_make_any_call_to(String client, String endpoint) throws Exception
                         Response<StateProof> r = algod.GetStateProof(1234L).execute();
                         response = r;
                         break;
+                    case "GetBlockHash":
+                        response = algod.GetBlockHash(1234L).execute();
+                        break;
                     default:
                         Assertions.fail("Unsupported algod endpoint: " + endpoint);
                 }

src/test/unit.tags

@@ -4,6 +4,7 @@
 @unit.algod.ledger_refactoring
 @unit.applications
 @unit.atomic_transaction_composer
+@unit.blocksummary
 @unit.dryrun
 @unit.dryrun.trace.application
 @unit.feetest
@@ -19,6 +20,7 @@
 @unit.responses.messagepack
 @unit.responses.messagepack.231
 @unit.responses.unlimited_assets
+@unit.responses.blocksummary
 @unit.sourcemap
 @unit.stateproof.paths
 @unit.stateproof.responses

test-harness.sh

@@ -1,6 +1,47 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# test-harness.sh setup/start cucumber test environment.
+#
+# Configuration is managed with environment variables, the ones you
+# are most likely to reconfigured are stored in '.test-env'.
+#
+# Variables:
+#   SDK_TESTING_URL     - URL to algorand-sdk-testing, useful for forks.
+#   SDK_TESTING_BRANCH  - branch to checkout, useful for new tests.
+#   SDK_TESTING_HARNESS - local directory that the algorand-sdk-testing repo is cloned into.
+#   VERBOSE_HARNESS     - more output while the script runs.
+#   INSTALL_ONLY        - installs feature files only, useful for unit tests.
+#
+#   WARNING: If set to 1, new features will be LOST when downloading the test harness.
+#   REGARDLESS: modified features are ALWAYS overwritten.
+#   REMOVE_LOCAL_FEATURES - delete all local cucumber feature files before downloading these from github.
+#
+#   WARNING: Be careful when turning on the next variable.
+#   In that case you'll need to provide all variables expected by `algorand-sdk-testing`'s `.env`
+#   OVERWRITE_TESTING_ENVIRONMENT=0
+
+SHUTDOWN=0
+if [ $# -ne 0 ]; then
+  if [ $# -ne 1 ]; then
+    echo "this script accepts a single argument, which must be 'up' or 'down'."
+    exit 1
+  fi
+
+  case $1 in
+    'up')
+      ;; # default.
+    'down')
+      SHUTDOWN=1
+      ;;
+    *)
+      echo "unknown parameter '$1'."
+      echo "this script accepts a single argument, which must be 'up' or 'down'."
+      exit 1
+      ;;
+  esac
+fi
+
 START=$(date "+%s")
 
 THIS=$(basename "$0")
@@ -23,10 +64,19 @@ if [ -d "$SDK_TESTING_HARNESS" ]; then
   ./scripts/down.sh
   popd
   rm -rf "$SDK_TESTING_HARNESS"
+  if [[ $SHUTDOWN == 1 ]]; then
+    echo "$THIS: network shutdown complete."
+    exit 0
+  fi
 else
   echo "$THIS: directory $SDK_TESTING_HARNESS does not exist - NOOP"
 fi
 
+if [[ $SHUTDOWN == 1 ]]; then
+  echo "$THIS: unable to shutdown network."
+  exit 1
+fi
+
 git clone --depth 1 --single-branch --branch "$SDK_TESTING_BRANCH" "$SDK_TESTING_URL" "$SDK_TESTING_HARNESS"
 
 
@@ -63,6 +113,11 @@ if [[ $VERBOSE_HARNESS == 1 ]]; then
 fi
 echo "$THIS: seconds it took to get to end of cloning and copying: $(($(date "+%s") - START))s"
 
+if [[ $INSTALL_ONLY == 1 ]]; then
+  echo "$THIS: configured to install feature files only. Not starting test harness environment."
+  exit 0
+fi
+
 ## Start test harness environment
 pushd "$SDK_TESTING_HARNESS"