Package org.nervos.muta

Class Muta

java.lang.Object

org.nervos.muta.Muta

public class Muta
extends java.lang.Object

Muta is a comprehensive class in front of all worker class

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Muta.RegistryEntry

Field Summary

Fields

Modifier and Type	Field	Description
protected Account	account	Account handles all jobs of signing
protected Client	client	Client is on duty of GraphQl communication
protected java.util.Map<Muta.RegistryEntry,com.fasterxml.jackson.core.type.TypeReference<?>>	eventRegistry
protected MutaRequestOption	mutaRequestOption	Where options lies
protected com.fasterxml.jackson.databind.ObjectMapper	objectMapper	Jackson's JSON marshall-er
protected java.util.function.Predicate<Muta>	sendTxBeforeHook	A hook before calling Client.sendTransaction(InputRawTransaction, InputTransactionEncryption) You can pass a closure/lambda expression to do some Predication work You can set, unset it whenever

Constructor Summary

Constructors

Constructor	Description
Muta(Client client, Account account, MutaRequestOption defaultReqOption)	Constructor with all params you can customize
Muta(Client client, Account account, MutaRequestOption defaultReqOption, java.util.List<EventRegisterEntry<?>> eventRegisterEntries)	Constructor with all params you can customize, and register concerned events

Method Summary

Modifier and Type	Method	Description
InputTransactionEncryption	appendSignedTransaction(InputRawTransaction inputRawTransaction, InputTransactionEncryption inputTransactionEncryption)	This method use internal account info to sign transaction, and append the signed signature together with the given signature, a.k.a.
protected void	checkClient()	Simple check if client is set, a.k.a.
<P> InputRawTransaction	compose(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, P payloadData, GAddress sender)	Use the given params to compose a Transaction, you can use this method to compose Transaction offline.
InputRawTransaction	compose(GHash chainId, GUint64 cyclesLimit, GUint64 cyclesPrice, GHash nonce, GUint64 timeout, @NonNull java.lang.String serviceName, @NonNull java.lang.String method, java.lang.String payload, GAddress sender)	Verbose version of compose(String, String, Object, GAddress)
static Muta	defaultMuta()
boolean	ec_recover(@lombok.NonNull byte[] signature, @lombok.NonNull byte[] msgHash, @lombok.NonNull byte[] targetAddress)	do ecdsa recovery of secp256k1
boolean	ec_verify(@lombok.NonNull byte[] signature, @lombok.NonNull byte[] msgHash, @lombok.NonNull byte[] publicKey)	do ecdsa verification of secp256k1
Block	getBlock(GUint64 height)	Start a GetBlock GraphQl query
java.math.BigInteger	getLatestHeight()	Directly send Graph query to get the latest mined block's height
Receipt	getReceipt(GHash txHash)	Start a GetReceipt GraphQl query
<R> ParsedServiceResponse<R>	getReceiptSucceedData(GHash txHash, com.fasterxml.jackson.core.type.TypeReference<R> tr, @NonNull java.util.List<ParsedEvent<?>> events)	Unmarshall the JSON string according to the given type param.
<P> ParsedServiceResponse<P>	getReceiptSucceedDataRetry(GHash txHash, com.fasterxml.jackson.core.type.TypeReference<P> tr, @NonNull java.util.List<ParsedEvent<?>> events)	Poll the receipt of the given transaction hash, unmarshall it to java object
SignedTransaction	getTransaction(GHash txHash)	Start a GetTransaction GraphQl query
protected <T> ParsedServiceResponse<T>	parseServiceResponse(ServiceResponse serviceResponse, com.fasterxml.jackson.core.type.TypeReference<T> tr)	Unmarshall ServiceResponse's succeedData, which should be JSON string, into class by type param.
<T> T	queryService(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, @NonNull java.lang.String payload, GUint64 height, GAddress caller, GUint64 cyclePrice, GUint64 cycleLimit, com.fasterxml.jackson.core.type.TypeReference<T> tr)	Send GraphQl queryService query with given payload and more detailed params
<T> T	queryService(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, com.fasterxml.jackson.core.type.TypeReference<T> tr)	Send GraphQl queryService query without payload
<T,P> T	queryService(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, P payloadData, com.fasterxml.jackson.core.type.TypeReference<T> tr)	Send GraphQl queryService query with given payload
void	register(java.util.List<EventRegisterEntry<?>> eventRegisterEntries)	Register concerned events
<P> GHash	sendTransaction(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, P payloadData)	Send a transaction and return its transaction hash, this is the commonly used sendTransaction(), sendTransaction() only with serviceName, method and payloadData
GHash	sendTransaction(GHash chainId, GUint64 cyclesLimit, GUint64 cyclesPrice, GHash nonce, GUint64 timeout, @NonNull java.lang.String serviceName, @NonNull java.lang.String method, java.lang.String payload)	Send a transaction and return its transaction hash, you can set all params by this function.
GHash	sendTransaction(InputRawTransaction inputRawTransaction, InputTransactionEncryption inputTransactionEncryption)	Send a transaction and return its transaction hash, by a DEFINED Raw Transaction and its Encryption(signature).
<P,R> R	sendTransactionAndPollResult(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, P payloadData, com.fasterxml.jackson.core.type.TypeReference<R> tr)	Send a transaction with commonly used param and poll the result of the execution, a.k.a.
<P,R> R	sendTransactionAndPollResult(@NonNull java.lang.String serviceName, @NonNull java.lang.String method, P payloadData, com.fasterxml.jackson.core.type.TypeReference<R> tr, @NonNull java.util.List<ParsedEvent<?>> events)	Send a transaction with commonly used param and poll the result of the execution, a.k.a.
InputTransactionEncryption	signTransaction(InputRawTransaction inputRawTransaction)	Manually sign a transaction and return the signature

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

client

protected final Client client

Client is on duty of GraphQl communication

account

protected final Account account

Account handles all jobs of signing

mutaRequestOption

protected final MutaRequestOption mutaRequestOption

Where options lies

objectMapper

protected final com.fasterxml.jackson.databind.ObjectMapper objectMapper

Jackson's JSON marshall-er

sendTxBeforeHook

protected java.util.function.Predicate<Muta> sendTxBeforeHook

A hook before calling Client.sendTransaction(InputRawTransaction, InputTransactionEncryption) You can pass a closure/lambda expression to do some Predication work You can set, unset it whenever

eventRegistry

protected java.util.Map<Muta.RegistryEntry,com.fasterxml.jackson.core.type.TypeReference<?>> eventRegistry

Constructor Detail

Muta

public Muta(Client client,
            Account account,
            MutaRequestOption defaultReqOption)

Constructor with all params you can customize

Parameters:

client - client client

account - account account

defaultReqOption - options mutaRequestOption

Muta

public Muta(Client client,
            Account account,
            MutaRequestOption defaultReqOption,
            java.util.List<EventRegisterEntry<?>> eventRegisterEntries)

Constructor with all params you can customize, and register concerned events

Parameters:

client - client client

account - account account

defaultReqOption - options mutaRequestOption

eventRegisterEntries - events you concern EventRegisterEntry

Method Detail

defaultMuta

public static Muta defaultMuta()

Returns:

Muta

getLatestHeight

public java.math.BigInteger getLatestHeight()
                                     throws java.io.IOException

Directly send Graph query to get the latest mined block's height

Returns:

Block height, literally

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

getBlock

public Block getBlock(GUint64 height)
               throws java.io.IOException

Start a GetBlock GraphQl query

Parameters:

height - The height want to query, leave null for the latest

Returns:

The block info, note the block could be null

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

getReceipt

public Receipt getReceipt(GHash txHash)
                   throws java.io.IOException

Start a GetReceipt GraphQl query

Parameters:

txHash - The transaction hash of transaction you want to query

Returns:

The Receipt of the transaction's execution result, maybe null

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

getTransaction

public SignedTransaction getTransaction(GHash txHash)
                                 throws java.io.IOException

Start a GetTransaction GraphQl query

Parameters:

txHash - The transaction hash of transaction you want to query

Returns:

The SignedTransaction when it sends, maybe null

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

queryService

public <T> T queryService(@NonNull
                          @NonNull java.lang.String serviceName,
                          @NonNull
                          @NonNull java.lang.String method,
                          com.fasterxml.jackson.core.type.TypeReference<T> tr)
                   throws java.io.IOException

Send GraphQl queryService query without payload

Type Parameters:

T - type param to auto unmarshall JSON string

Parameters:

serviceName - The name of the service

method - The method name of the service

tr - TypeReference to hold type param

Returns:

unmarshalled object of type T

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

queryService

public <T,P> T queryService(@NonNull
                                  @NonNull java.lang.String serviceName,
                                  @NonNull
                                  @NonNull java.lang.String method,
                                  P payloadData,
                                  com.fasterxml.jackson.core.type.TypeReference<T> tr)
                           throws java.io.IOException

Send GraphQl queryService query with given payload

Type Parameters:

T - type param to auto unmarshall JSON string

P - type param to aulto marshal JSON string, the type param should be friendly with Jackson

Parameters:

serviceName - The name of the service

method - The method name of the service

payloadData - The payload data, it will be automatically marshalled to JSON string

tr - TypeReference to hold type param

Returns:

unmarshalled object of type T

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

queryService

public <T> T queryService(@NonNull
                          @NonNull java.lang.String serviceName,
                          @NonNull
                          @NonNull java.lang.String method,
                          @NonNull
                          @NonNull java.lang.String payload,
                          GUint64 height,
                          GAddress caller,
                          GUint64 cyclePrice,
                          GUint64 cycleLimit,
                          com.fasterxml.jackson.core.type.TypeReference<T> tr)
                   throws java.io.IOException

Send GraphQl queryService query with given payload and more detailed params

Type Parameters:

T - type param to auto unmarshall JSON string

Parameters:

serviceName - The name of the service

method - The method name of the service

payload - The payload data string, should be marshalled JSON string

tr - TypeReference to hold type param

height - On which height this queryService should run

caller - in the name of caller this queryService should run

cyclePrice - give a specified cyclePrice

cycleLimit - give a specified cycleLimit

Returns:

unmarshalled object of type T, or null for error in ServiceResponse

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

sendTransaction

public <P> GHash sendTransaction(@NonNull
                                 @NonNull java.lang.String serviceName,
                                 @NonNull
                                 @NonNull java.lang.String method,
                                 P payloadData)
                          throws java.io.IOException

Send a transaction and return its transaction hash, this is the commonly used sendTransaction(), sendTransaction() only with serviceName, method and payloadData

Type Parameters:

P - type param to aulto marshal JSON string, the type param should be friendly with Jackson

Parameters:

serviceName - The name of the service

method - The method name of the service

payloadData - The payload data, it will be automatically marshalled to JSON string

Returns:

Transaction Hash

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

sendTransaction

public GHash sendTransaction(GHash chainId,
                             GUint64 cyclesLimit,
                             GUint64 cyclesPrice,
                             GHash nonce,
                             GUint64 timeout,
                             @NonNull
                             @NonNull java.lang.String serviceName,
                             @NonNull
                             @NonNull java.lang.String method,
                             java.lang.String payload)
                      throws java.io.IOException

Send a transaction and return its transaction hash, you can set all params by this function. Otherwise, chose sendTransaction(String, String, Object)

Parameters:

chainId - ChainId of the Muta chain

cyclesLimit - cyclesLimit you want to set

cyclesPrice - cyclesPrice you want to set

nonce - you can set an random nonce as you wish

timeout - set a timeout for this block

serviceName - the name of the service

method - the method name

payload - the payload for the method

Returns:

transaction hash

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

sendTransaction

public GHash sendTransaction(InputRawTransaction inputRawTransaction,
                             InputTransactionEncryption inputTransactionEncryption)
                      throws java.io.IOException

Send a transaction and return its transaction hash, by a DEFINED Raw Transaction and its Encryption(signature). This method allows you to use composed Tx and sign it offline, or use the signature to do more things, like Multi-Sig

Parameters:

inputRawTransaction - The transaction, literally

inputTransactionEncryption - The signature of the transaction to pass to Muta Chain to verify, this could be a Multi-Sig

Returns:

Transaction hash

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

sendTransactionAndPollResult

public <P,R> R sendTransactionAndPollResult(@NonNull
                                                  @NonNull java.lang.String serviceName,
                                                  @NonNull
                                                  @NonNull java.lang.String method,
                                                  P payloadData,
                                                  com.fasterxml.jackson.core.type.TypeReference<R> tr,
                                                  @NonNull
                                                  @NonNull java.util.List<ParsedEvent<?>> events)
                                           throws java.io.IOException

Send a transaction with commonly used param and poll the result of the execution, a.k.a. receipt. And then poll the receipt to get the receipt and then return it.

Type Parameters:

P - The generic of payload, should be friendly with Jackson

R - The generic of return data, should be friendly with Jackson

Parameters:

serviceName - the name of the service

method - the method of the service

payloadData - the payload used in the method, will be marshalled by Jackson to JSON string,

tr - Type reference to hold type param

events - List to contain parsed event

Returns:

The unmarshalled java object, or null for error returned in ServiceResponse

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

sendTransactionAndPollResult

public <P,R> R sendTransactionAndPollResult(@NonNull
                                                  @NonNull java.lang.String serviceName,
                                                  @NonNull
                                                  @NonNull java.lang.String method,
                                                  P payloadData,
                                                  com.fasterxml.jackson.core.type.TypeReference<R> tr)
                                           throws java.io.IOException

Send a transaction with commonly used param and poll the result of the execution, a.k.a. receipt. And then poll the receipt to get the receipt and then return it.

Type Parameters:

P - The generic of payload, should be friendly with Jackson

R - The generic of return data, should be friendly with Jackson

Parameters:

serviceName - the name of the service

method - the method of the service

payloadData - the payload used in the method, will be marshalled by Jackson to JSON string,

tr - Type reference to hold type param

Returns:

The unmarshalled java object, or null for error returned in ServiceResponse

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

getReceiptSucceedDataRetry

public <P> ParsedServiceResponse<P> getReceiptSucceedDataRetry(GHash txHash,
                                                               com.fasterxml.jackson.core.type.TypeReference<P> tr,
                                                               @NonNull
                                                               @NonNull java.util.List<ParsedEvent<?>> events)
                                                        throws java.io.IOException

Poll the receipt of the given transaction hash, unmarshall it to java object

Type Parameters:

P - The generic of return data

Parameters:

txHash - the transaction hash you want to poll

tr - Type reference to hold type param

events - List to hold events

Returns:

The java object or error

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

getReceiptSucceedData

public <R> ParsedServiceResponse<R> getReceiptSucceedData(GHash txHash,
                                                          com.fasterxml.jackson.core.type.TypeReference<R> tr,
                                                          @NonNull
                                                          @NonNull java.util.List<ParsedEvent<?>> events)
                                                   throws java.io.IOException

Unmarshall the JSON string according to the given type param. While receipt is ready but the

Type Parameters:

R - The generic of the return data to be unmarshalled

Parameters:

txHash - The transaction hash

tr - Type reference to hold type param

events - List to hold events

Returns:

Return null for receipt is null(maybe not ready), return ParsedServiceResponse if get receipt

Throws:

java.io.IOException - Exception, maybe HTTP/network error, or GraphQl execution failure

compose

public <P> InputRawTransaction compose(@NonNull
                                       @NonNull java.lang.String serviceName,
                                       @NonNull
                                       @NonNull java.lang.String method,
                                       P payloadData,
                                       GAddress sender)
                                throws java.io.IOException

Use the given params to compose a Transaction, you can use this method to compose Transaction offline.

Type Parameters:

P - The type param of the payloadData, should be friendly with Jackson

Parameters:

serviceName - the name of the service

method - the method of the service

payloadData - the payload to be used by method

sender - Who sends this

Returns:

The composed transaction

Throws:

java.io.IOException - JSON marshal exception

compose

public InputRawTransaction compose(GHash chainId,
                                   GUint64 cyclesLimit,
                                   GUint64 cyclesPrice,
                                   GHash nonce,
                                   GUint64 timeout,
                                   @NonNull
                                   @NonNull java.lang.String serviceName,
                                   @NonNull
                                   @NonNull java.lang.String method,
                                   java.lang.String payload,
                                   GAddress sender)
                            throws java.io.IOException

Verbose version of compose(String, String, Object, GAddress)

Parameters:

chainId - ChainId of Muta Chain

cyclesLimit - Specific cyclesLimit

cyclesPrice - Specific cyclesPrice

nonce - You can set the random nonce as you wish

timeout - Timeout option of transaction

serviceName - name of service

method - method of service

payload - payload of method

sender - who sends the transaction

Returns:

Composed transaction

Throws:

java.io.IOException - JSON marshal exception

signTransaction

public InputTransactionEncryption signTransaction(InputRawTransaction inputRawTransaction)

Manually sign a transaction and return the signature

Parameters:

inputRawTransaction - The transaction to be signed

Returns:

Signed signature

appendSignedTransaction

public InputTransactionEncryption appendSignedTransaction(InputRawTransaction inputRawTransaction,
                                                          InputTransactionEncryption inputTransactionEncryption)
                                                   throws java.io.IOException

This method use internal account info to sign transaction, and append the signed signature together with the given signature, a.k.a. Multi-Sig

Parameters:

inputRawTransaction - The transaction to be signed

inputTransactionEncryption - The signature to be appended with

Returns:

Appended Signature, a.k.a. Multi-Sig

Throws:

java.io.IOException - JSON marshal exception

checkClient

protected void checkClient()

Simple check if client is set, a.k.a. online mode.

parseServiceResponse

protected <T> ParsedServiceResponse<T> parseServiceResponse(ServiceResponse serviceResponse,
                                                            com.fasterxml.jackson.core.type.TypeReference<T> tr)
                                                     throws java.io.IOException

Unmarshall ServiceResponse's succeedData, which should be JSON string, into class by type param.

Type Parameters:

T - generic to indicate how to unmarshall JSON string

Parameters:

serviceResponse - ServiceResponse to be parsed

tr - Type reference to hold type param

Returns:

Unmarshalled java object

Throws:

java.io.IOException - JSON unmarshall error or service response error

ec_recover

public boolean ec_recover(@NonNull
                          @lombok.NonNull byte[] signature,
                          @NonNull
                          @lombok.NonNull byte[] msgHash,
                          @NonNull
                          @lombok.NonNull byte[] targetAddress)

do ecdsa recovery of secp256k1

Parameters:

signature - the signature, combined with r and s, respective of 32 bytes

msgHash - the digest of message, which is 32 bytes, calc-ed by keccak256

targetAddress - which address you assume the signature is for

Returns:

match or not

ec_verify

public boolean ec_verify(@NonNull
                         @lombok.NonNull byte[] signature,
                         @NonNull
                         @lombok.NonNull byte[] msgHash,
                         @NonNull
                         @lombok.NonNull byte[] publicKey)

do ecdsa verification of secp256k1

Parameters:

signature - the signature, combined with r and s, respective of 32 bytes

msgHash - the digest of message, which is 32 bytes, calc-ed by keccak256

publicKey - the public key which signs the signature

Returns:

match or not

register

public void register(java.util.List<EventRegisterEntry<?>> eventRegisterEntries)

Register concerned events

Parameters:

eventRegisterEntries - List of concerned events