All Products
Search
Document Center

Blockchain as a Service:Envelope transaction interface

Last Updated:Aug 15, 2024

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