Envelope transaction interface - Blockchain as a Service

An envelope transaction is executed in an independent group to protect privacy. The smart contract platform supports envelope transactions of deploying, calling, updating, and querying for contracts.

depositEnvelope

This API is called synchronously for envelope transactions.

Function prototype

public DepositEnvelopeResponse depositEnvelope(DepositEnvelopeRequest request)

Request parameter

Parameter	Required	Type	Description
request	true	`DepositEnvelopeRequest`	The envelope transaction request.

DepositEnvelopeRequest parameter.

Parameter	Required	Type	Description
anoymousIdentity	true	Identity	The anonymous identity.
signerBases	true	`List<SignerBase>`	The signature configuration option.
keypair	true	Keypair	The key pair.

GroupTransactionRequest is the parent class of DepositEnvelopeRequest.

Parameter	Type	Description
request	`AbstractTransactionRequest`	Inner transactions, including deploying contracts, invoking contracts, and updating contracts.

Response field

Response field	Field type	Description
response	`DepositEnvelopeResponse`	The envelope transaction response.

DepositEnvelopeResponse parameter.

Parameter	Type	Description
transactionReceipt	`TransactionReceipt`	The transaction receipt.
blockNumber	BigInteger	The block number.
txIndex	int	The transaction offset
txHash	Hash	The transaction hash
isLocalTransaction	boolean	Whether the transaction is a local transaction

TransactionReceipt parameter.

Parameter	Type	Description
result	long	Transaction execution result: 0 represents success, while other values indicate failure.
gasUsed	BigInteger	Gas fees incurred by the transaction.
logs	`List<logEntry>`	Log output of the transaction result.
output	byte[]	The output of the transaction, which in this context is the execution result of the virtual machine.

LogEntry parameter.

Parameter	Type	Description
from	Identity	The field in the transaction result log representing the transaction sender.
to	Identity	The field in the transaction result log representing the transaction receiver.
topics	List<String>	The field in the transaction result log representing the event topic of the transaction execution.
logData	byte[]	The field in the transaction result log representing the log data of the transaction execution.

Example

public void depositEnvelope() {
        // create Group
        CreateGroupRequest createGroupRequest = new CreateGroupRequest(new PublicKey(keypair.getPubkeyId()), Utils.getIdentityByName("Administrator"));
        createGroupResponse = sdk.getEnvelopeService().createGroup(createGroupRequest);

        // join group
        byte[] groupPrivateKey = createGroupResponse.getPrivateKey();
        PublicKey anoymousPublicKey = new PublicKey(keypair.getPubkeyId());
        JoinGroupRequest joinGroupRequest = new JoinGroupRequest(groupPrivateKey, anoymousPublicKey, createGroupResponse.getGroupId(), Utils.getIdentityByName("Administrator"));
        JoinGroupResponse joinGroupResponse = sdk.getEnvelopeService().joinGroup(joinGroupRequest);

        // get groupId by createGroupResponse
        BaseFixedSizeByteArray.Fixed20ByteArray groupId = createGroupResponse.getGroupId();

        // get keypair from createGroupResponse
        Pkcs8KeyOperator pkcs8KeyOperator = new Pkcs8KeyOperator();
        Keypair keypair = pkcs8KeyOperator.loadFromPrivkey(createGroupResponse.getPrivateKey());

        // create signerOption by keypair
        SignerOption signerOption = new SignerOption();
        List<SignerBase> signerBases = new ArrayList<>();
        signerBases.add(MyCrypto.getInstance().createSigner(keypair));
        signerOption.setSigners(signerBases);

        // create inner request
        // build account
        String accountName = "accountName";
        Identity userIdentity = Utils.getIdentityByName(accountName);
        Account account = new Account();
        account.setIdentity(userIdentity);
        account.setBalance(BigInteger.ZERO);
        account.setStatus(AccountStatus.NORMAL);
        AuthMap authMap = new AuthMap();
        account.setAuthMap(authMap.updateAuth(new PublicKey(administratorPublicKey1), 100));
        account.setAuthMap(authMap.updateAuth(new PublicKey(administratorPublicKey2), 100));
        account.setAuthMap(authMap.updateAuth(new PublicKey(administratorPublicKey3), 100));
        account.setAuthMap(authMap.updateAuth(new PublicKey(administratorPublicKey4), 100));
        account.setRecoverKey(new PublicKey(administratorPublicKey1));
        CreateAccountRequest createAccountRequest = new CreateAccountRequest(Utils.getIdentityByName("Administrator"), account);

        // create DepositEnvelopeRequest
        IHash hashTool = HashFactory.getHash();

        DepositEnvelopeRequest request = new DepositEnvelopeRequest(createAccountRequest, groupId, signerBases, keypair);
        request.setAnonymousIdentity(new Identity(hashTool.hash(keypair.getPubkeyId())));

        DepositEnvelopeResponse depositEnvelopeResponse = sdk.getEnvelopeService().depositEnvelope(request);
        if (!depositEnvelopeResponse.isSuccess()) {
            logger.error("depositEnvelope failed, errorCode :{}, errorDesc: {}", depositEnvelopeResponse.getErrorCode().getErrorCode(), depositEnvelopeResponse.getErrorCode().getErrorDesc());
        } else {
            // transaction receipt
            TransactionReceipt transactionReceipt = depositEnvelopeResponse.getTransactionReceipt();
            if (transactionReceipt.getResult() != 0) {
                logger.error("depositEnvelope failed, errorCode :{}, errorDesc: {}", ErrorCode.valueOf((int) transactionReceipt.getResult()).getErrorCode(), ErrorCode.valueOf((int) transactionReceipt.getResult()).getErrorDesc());
            } else {
                logger.info("depositEnvelope success. Return information: {}", transactionReceipt.toString());
            }
        }
    }

asyncDepositRequest

This API is called asynchronously for envelope transactions.

Function prototype

public int asyncDepositRequest(DepositEnvelopeRequest request, IAsyncCallback callback)

Request parameter

Parameter	Required	Type	Description
request	true	`DepositEnvelopeRequest`	The envelope transaction request.
callback	true	IAsyncCallback	The callback function.

DepositEnvelopeRequest parameter.

Parameter	Required	Type	Description
anoymousIdentity	true	Identity	The anonymous identity.
signerBases	true	`List<SignerBase>`	The signature configuration option.
keypair	true	Keypair	The key pair.

GroupTransactionRequest is the parent class of DepositEnvelopeRequest.

Parameter	Type	Description
request	`AbstractTransactionRequest`	Inner transactions, including deploying contracts, invoking contracts, and updating contracts.

Response field

Response field	Field type	Description
result	int	The return value.

Asynchronous Response field

Response field	Field type	Description
errorCode	int	The SDK sends a message timeout or successfully.
response	`Response`	The response returned by the platform, where `response.getErrorCode()` is the error code returned by the platform.

(DepositEnvelopeResponse)Response

Response field	Field type	Description
transactionReceipt	`TransactionReceipt`	The transaction receipt.
blockNumber	BigInteger	The block number.
txIndex	int	The transaction offset
txHash	Hash	The transaction hash
isLocalTransaction	boolean	Whether the transaction is a local transaction

TransactionReceipt parameter.

Parameter	Type	Description
result	long	Transaction execution result: 0 represents success, while other values indicate failure.
gasUsed	BigInteger	Gas fees incurred by the transaction.
logs	`List<logEntry>`	Log output of the transaction result.
output	byte[]	The output of the transaction, which in this context is the execution result of the virtual machine.

LogEntry parameter.

Parameter	Type	Description
from	Identity	The field in the transaction result log representing the transaction sender.
to	Identity	The field in the transaction result log representing the transaction receiver.
topics	List<String>	The field in the transaction result log representing the event topic of the transaction execution.
logData	byte[]	The field in the transaction result log representing the log data of the transaction execution.

Example

DepositEnvelopeRequest request = new DepositEnvelopeRequest(createAccountRequest, groupId, signerBases, keypair);
request.setAnoymousIdentity(new Identity(hashTool.hash(keypair.getPubkeyId())));
int result = sdk.getEnvelopeService().asyncDepositRequest(
    request,
    new IAsyncCallback() {
        @Override
        public void onResponse(int errorCode, Response response) {
            // please refer to the Error Codes topic and check the returned data.
            System.out.println("async deposit envelope, errorCode:" + errorCode + ", response: " + response.getErrorCode());
            DepositEnvelopeResponse receiptResponse = (DepositEnvelopeResponse) response;
        }
    });