com.chain.api.Transaction Maven / Gradle / Ivy

package com.chain.api;

import com.chain.exception.*;
import com.chain.http.*;
import com.google.gson.annotations.SerializedName;

import java.util.*;
import java.util.concurrent.TimeUnit;

/**
 * A single transaction on a Chain Core.
 */
public class Transaction {
  /**
   * Unique identifier, or transaction hash, of a transaction.
   */
  public String id;

  /**
   * Time of transaction.
   */
  public Date timestamp;

  /**
   * Unique identifier, or block hash, of the block containing a transaction.
   */
  @SerializedName("block_id")
  public String blockId;

  /**
   * Height of the block containing a transaction.
   */
  @SerializedName("block_height")
  public int blockHeight;

  /**
   * Position of a transaction within the block.
   */
  public int position;

  /**
   * User specified, unstructured data embedded within a transaction.
   */
  @SerializedName("reference_data")
  public Map referenceData;

  /**
   * A flag indicating one or more inputs or outputs are local.
   * Possible values are "yes" or "no".
   */
  @SerializedName("is_local")
  public String isLocal;

  /**
   * List of specified inputs for a transaction.
   */
  public List inputs;

  /**
   * List of specified outputs for a transaction.
   */
  public List outputs;

  /**
   * Paged results of a transaction query.
   */
  public static class Items extends PagedItems {
    /**
     * Returns a new page of transactions based on the underlying query.
     * @return a page of transactions
     * @throws APIException This exception is raised if the api returns errors while processing the query.
     * @throws BadURLException This exception wraps java.net.MalformedURLException.
     * @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
     * @throws HTTPException This exception is raised when errors occur making http requests.
     * @throws JSONException This exception is raised due to malformed json requests or responses.
     */
    public Items getPage() throws ChainException {
      Items items = this.client.request("list-transactions", this.next, Items.class);
      items.setClient(this.client);
      return items;
    }
  }

  /**
   * Transaction.QueryBuilder utilizes the builder pattern to create {@link Transaction} queries.

   * The possible parameters for each query can be found on this class as well as the {@link BaseQueryBuilder} class.

   * All parameters are optional, and should be set to filter the results accordingly.
   */
  public static class QueryBuilder extends BaseQueryBuilder {
    /**
     * Executes a transaction query based on provided parameters.
     * @param client client object which makes server requests
     * @return a page of transactions
     * @throws APIException This exception is raised if the api returns errors while processing the query.
     * @throws BadURLException This exception wraps java.net.MalformedURLException.
     * @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
     * @throws HTTPException This exception is raised when errors occur making http requests.
     * @throws JSONException This exception is raised due to malformed json requests or responses.
     */
    public Items execute(Client client) throws ChainException {
      Items items = new Items();
      items.setClient(client);
      items.setNext(this.next);
      return items.getPage();
    }

    /**
     * Sets the earliest transaction timestamp to include in results
     * @param time start time in UTC format
     * @return updated QueryBuilder object
     */
    public QueryBuilder setStartTime(long time) {
      this.next.startTime = time;
      return this;
    }

    /**
     * Sets the latest transaction timestamp to include in results
     * @param time end time in UTC format
     * @return updated QueryBuilder object
     */
    public QueryBuilder setEndTime(long time) {
      this.next.endTime = time;
      return this;
    }

    /**
     * Sets the ascending_with_long_poll flag on this query to facilitate
     * notifications.
     * @return updated QueryBuilder object
     */
    public QueryBuilder setAscendingWithLongPoll() {
      this.next.ascendingWithLongPoll = true;
      return this;
    }

    /**
     * Sets a timeout on this query.
     * @param timeoutMS timeout in milliseconds
     * @return updated QueryBuilder object
     */
    public QueryBuilder setTimeout(long timeoutMS) {
      this.next.timeout = timeoutMS;
      return this;
    }
  }

  /**
   * A single input included in a transaction.
   */
  public static class Input {
    /**
     * The type of the input.

     * Possible values are "issue" and "spend".
     */
    public String type;

    /**
     * The id of the asset being issued or spent.
     */
    @SerializedName("asset_id")
    public String assetId;

    /**
     * The alias of the asset being issued or spent (possibly null).
     */
    @SerializedName("asset_alias")
    public String assetAlias;

    /**
     * The definition of the asset being issued or spent (possibly null).
     */
    @SerializedName("asset_definition")
    public Map assetDefinition;

    /**
     * The tags of the asset being issued or spent (possibly null).
     */
    @SerializedName("asset_tags")
    public Map assetTags;

    /**
     * A flag indicating whether the asset being issued or spent is local.
     * Possible values are "yes" or "no".
     */
    @SerializedName("asset_is_local")
    public String assetIsLocal;

    /**
     * The number of units of the asset being issued or spent.
     */
    public long amount;

    /**
     * The id of the output consumed by this input. Null if the input is an issuance.
     */
    @SerializedName("spent_output_id")
    public String spentOutputId;

    /**
     * The id of the account transferring the asset (possibly null if the input is an issuance or an unspent output is specified).
     */
    @SerializedName("account_id")
    public String accountId;

    /**
     * The alias of the account transferring the asset (possibly null if the input is an issuance or an unspent output is specified).
     */
    @SerializedName("account_alias")
    public String accountAlias;

    /**
     * The tags associated with the account (possibly null).
     */
    @SerializedName("account_tags")
    public Map accountTags;

    /**
     * A program specifying a predicate for issuing an asset (possibly null if input is not an issuance).
     */
    @SerializedName("issuance_program")
    public String issuanceProgram;

    /**
     * User specified, unstructured data embedded within an input (possibly null).
     */
    @SerializedName("reference_data")
    public Map referenceData;

    /**
     * A flag indicating if the input is local.
     * Possible values are "yes" or "no".
     */
    @SerializedName("is_local")
    public String isLocal;
  }

  /**
   * A single output included in a transaction.
   */
  public static class Output {
    /**
     * The id of the output.
     */
    @SerializedName("id")
    public String id;

    /**
     * The type the output.

     * Possible values are "control" and "retire".
     */
    public String type;

    /**
     * The purpose of the output.

     * Possible purposes are "receive" and "change". Only populated if the
     * output's control program was generated locally.
     */
    public String purpose;

    /**
     * The output's position in a transaction's list of outputs.
     */
    public int position;

    /**
     * The id of the asset being controlled.
     */
    @SerializedName("asset_id")
    public String assetId;

    /**
     * The alias of the asset being controlled.
     */
    @SerializedName("asset_alias")
    public String assetAlias;

    /**
     * The definition of the asset being controlled (possibly null).
     */
    @SerializedName("asset_definition")
    public Map assetDefinition;

    /**
     * The tags of the asset being controlled (possibly null).
     */
    @SerializedName("asset_tags")
    public Map assetTags;

    /**
     * A flag indicating whether the asset being controlled is local.
     * Possible values are "yes" or "no".
     */
    @SerializedName("asset_is_local")
    public String assetIsLocal;

    /**
     * The number of units of the asset being controlled.
     */
    public long amount;

    /**
     * The id of the account controlling this output (possibly null if a control program is specified).
     */
    @SerializedName("account_id")
    public String accountId;

    /**
     * The alias of the account controlling this output (possibly null if a control program is specified).
     */
    @SerializedName("account_alias")
    public String accountAlias;

    /**
     * The tags associated with the account controlling this output (possibly null if a control program is specified).
     */
    @SerializedName("account_tags")
    public Map accountTags;

    /**
     * The control program which must be satisfied to transfer this output.
     */
    @SerializedName("control_program")
    public String controlProgram;

    /**
     * User specified, unstructured data embedded within an input (possibly null).
     */
    @SerializedName("reference_data")
    public Map referenceData;

    /**
     * A flag indicating if the output is local.
     * Possible values are "yes" or "no".
     */
    @SerializedName("is_local")
    public String isLocal;
  }

  /**
   * A built transaction that has not been submitted for block inclusion (returned from {@link Transaction#buildBatch(Client, List)}).
   */
  public static class Template {
    /**
     * A hex-encoded representation of a transaction template.
     */
    @SerializedName("raw_transaction")
    public String rawTransaction;

    /**
     * The list of signing instructions for inputs in the transaction.
     */
    @SerializedName("signing_instructions")
    public List signingInstructions;

    /**
     * For core use only.
     */
    private boolean local;

    /**
     * False (the default) makes the transaction "final" when signing,
     * preventing further changes - the signature program commits to
     * the transaction's signature hash.  True makes the transaction
     * extensible, committing only to the elements in the transaction
     * so far, permitting the addition of new elements.
     */
    @SerializedName("allow_additional_actions")
    private boolean allowAdditionalActions;

    /**
     * allowAdditionalActions causes the transaction to be signed so
     * that it can be used as a base transaction in a multiparty trade
     * flow. To enable this setting, call this method after building the
     * transaction, but before sending it to the signer.
     *
     * All participants in a multiparty trade flow should call this
     * method except for the last signer. Do not call this option if
     * the transaction is complete, i.e. if it will not be used as a
     * base transaction.
     * @return updated transaction template
     */
    public Template allowAdditionalActions() {
      this.allowAdditionalActions = true;
      return this;
    }

    /**
     * A single signing instruction included in a transaction template.
     */
    public static class SigningInstruction {
      /**
       * The input's position in a transaction's list of inputs.
       */
      public int position;

      /**
       * A list of components used to coordinate the signing of an input.
       */
      @SerializedName("witness_components")
      public WitnessComponent[] witnessComponents;
    }

    /**
     * A single witness component, holding information that will become the input witness.
     */
    public static class WitnessComponent {
      /**
       * The type of witness component.

       * Possible types are "data" and "signature".
       */
      public String type;

      /**
       * Data to be included in the input witness (null unless type is "data").
       */
      public String data;

      /**
       * The number of signatures required for an input (null unless type is "signature").
       */
      public int quorum;

      /**
       * The list of keys to sign with (null unless type is "signature").
       */
      public KeyID[] keys;

      /**
       * The program whose hash is signed. If empty, it is
       * inferred during signing from aspects of the
       * transaction.
       */
      public String program;

      /**
       * The list of signatures made with the specified keys (null unless type is "signature").
       */
      public String[] signatures;
    }

    /**
     * A class representing a derived signing key.
     */
    public static class KeyID {
      /**
       * The extended public key associated with the private key used to sign.
       */
      public String xpub;

      /**
       * The derivation path of the extended public key.
       */
      @SerializedName("derivation_path")
      public String[] derivationPath;
    }
  }

  /**
   * A single response from a call to {@link Transaction#submitBatch(Client, List)}
   */
  public static class SubmitResponse {
    /**
     * The transaction id.
     */
    public String id;
  }

  /**
   * Builds a batch of transaction templates.
   * @param client client object which makes server requests
   * @param builders list of transaction builders
   * @return a list of transaction templates
   * @throws APIException This exception is raised if the api returns errors while building transaction templates.
   * @throws BadURLException This exception wraps java.net.MalformedURLException.
   * @throws ConnectivityException This exception is raised if there are connectivity issues with the server.
   * @throws HTTPException This exception is raised when errors occur making http requests.
   * @throws JSONException This exception is raised due to malformed json requests or responses.
   */
  public static BatchResponse