Skip to content

Documentation

Marco Walz edited this page Mar 11, 2019 · 3 revisions

How to use the SDK?

Access SDK services

The services of the SDK can be accessed using the factory pattern. Every service has its own factory which allows to get the service either with default config (ae_uat using https://sdk-testnet.aepps.com/v2) or using a XServiceConfiguration builder pattern configuration object:

new ChainServiceFactory().getService(); // get default configured service

new TransactionServiceFactory().getService( TransactionServiceConfiguration.configure().baseUrl( "http://localhost/v2").compile() ); //set the baseUrl to localhost

Transactions of any type are created using a factory residing in the transaction service. This provides a uniform way of creating and abstracts the setting of some necessary parameters, f.e. like the fee calculation model, which must be transparent. A new transaction is created in two steps:

/* 
 * Step 1: create transaction object of desired type 
 */
transactionService = ... 				// resolve TxService like above
AbstractTransaction<?> spendTx =			// abstract supertype of tx
        transactionService						
            .getTransactionFactory()			// get the factory and create desired tx type
            .createSpendTransaction(sender, recipient, amount, payload, null, ttl, nonce);

/* 
 * Step 2: create unsigned transaction object 
 * especially a this point, the automated fee calculation will take place, 
 * depending on the actual transaction type 
 */
UnsignedTx unsignedTx =
        transactionService.createUnsignedTransaction(spendTx).blockingGet();

Generate and post a transaction

// secret needed to recover KeyPair and sign tx
final String testSecret = "<your_private_key>";

// the KeyPairService doesn't need specific configuration parameters
final KeyPairService keyPairService = new KeyPairServiceFactory().getService();
BaseKeyPair keyPair = keyPairService.generateBaseKeyPairFromSecret(testSecret);

final String baseUrl = "https://sdk-testnet.aepps.com/v2"; // default: https://sdk-testnet.aepps.com/v2
final Network testnet = Network.TESTNET; // default: TESTNET -> ae_uat

// get services with required configuration
// you can also call getService() which will load the default settings (see above)
ServiceConfiguration serviceConf = ServiceConfiguration.configure().baseUrl(baseUrl).compile();
final AccountService accountService = new AccountServiceFactory().getService(serviceConf);
final ChainService chainService = new ChainServiceFactory().getService(serviceConf);
// the TransactionService needs to know the network because the signature of tx is handled differently
final TransactionService transactionService = new TransactionServiceFactory().getService(TransactionServiceConfiguration.configure().baseUrl(baseUrl).network(testnet).compile());

final String recipient = "<recipient_address>";

// get block to determine current height for calculation of TTL
KeyBlock block = chainService.getCurrentKeyBlock().blockingGet();
// get the current account to determine nonce which has to be increased
Account account = accountService.getAccount(keyPair.getPublicKey()).blockingGet();

// amount to send -> (in future we will provide utils to calculate æternity units)
BigInteger amount = BigInteger.valueOf(1);
// some payload included within tx
String payload = "works =)";
// self defined fee is optional. if you provide null as fee our implementation will automatically calculate the fee
BigInteger fee = BigInteger.valueOf(<SELF_DEFINED_FEE>);
// tx will be valid for the next ten blocks
BigInteger ttl = block.getHeight().add(BigInteger.TEN);
// we need to increase the current account nonce by one
BigInteger nonce = account.getNonce().add(BigInteger.ONE);

// create the tx (with self defined fee)
AbstractTransaction<?> spendTxWithSelfDefinedFee =
        transactionService
                .getTransactionFactory()
                .createSpendTransaction(
                        keyPair.getPublicKey(), recipient, amount, payload, fee, ttl, nonce);
// create the tx (with calculated fee)
AbstractTransaction<?> spendTxWithCalculatedFee =
        transactionService
                .getTransactionFactory()
                .createSpendTransaction(
                        keyPair.getPublicKey(), recipient, amount, payload, null, ttl, nonce);

// choose one of the spendTx above to create the UnsignedTx-object
UnsignedTx unsignedTx =
        transactionService.createUnsignedTransaction(spendTxWithCalculatedFee).blockingGet();

// sign the tx
Tx signedTx =
        transactionService.signTransaction(unsignedTx, keyPair.getPrivateKey());

// hopefully you receive a successful txResponse
PostTxResponse txResponse = transactionService.postTransaction(signedTx).blockingGet();

Generate a HD wallet

The implementation of HD wallets is based on bitcoinj

Although possible, it's not recommended to create the HD wallet based on a user choosen list of mnemonic words, because this will lack randomicity. Additionally it's strongly recommended to set password, which additionally salts the mnemonic phrase and increases security. All derived keys should be created with the hardened flag. Otherwise it is possible to reconstruct all descendent private and public keys from a known private key and all descendent public keys from a known public key.

final KeyPairService keyPairService = new KeyPairServiceFactory().getService();

// create the master
MnemonicKeyPair generatedKeyPair =
                    keyPairService.generateMasterMnemonicKeyPair("superSafeRandomSaltPassword");
// get the mnemonics
master.getMnemonicSeedWords()

// derive a key                    
BaseKeyPair generatedDerivedKey =
                            EncodingUtils.createBaseKeyPair(
                                keyPairService.generateDerivedKey(master, true).toRawKeyPair());
Clone this wiki locally
You can’t perform that action at this time.