API Implementation

Samsung Blockchain Keystore API Level
Get Instance
Get SeedHash
Check For Mandatory App Update
Is Root Seed Backed Up
Get Supported Coins
Get HD Path
Get a List of Addresses
Get a List of Extended Public Keys
Sign a Transaction
Is Reboot Authentication Required
Go to Samsung Blockchain Keystore Settings
Handle Error Codes
Deeplinks

Samsung Blockchain Keystore API Level

Samsung Blockchain Keystore API Level plays a key role to ensure that the required API level of Samsung Blockchain Keystore on a user’s device is properly installed to support the API that your Android app tries to call.

For example, if your Android app is trying to implement a new Samsung Blockchain Keystore API that requires “API Level 2”, your Android app will need to check whether Samsung Blockchain Keystore app installed on user’s device also supports API Level 2. If a user’s app supports API Level 1, then your app will need to guide users to update Samsung Blockchain Keystore app to the latest version. Users can be directed to the update page in Galaxy Store. Otherwise, there will be a runtime exception due to API Level Exception when calling APIs with level higher than the level supported by the user’s version.

The API Level for each API will be mentioned in the Javadoc, under “Since” title, and developers can call “getKeystoreApiLevel API” to check the current API Level on the user’s device. Your Android app will need to check the API Level whenever needed – it may be at the beginning of running Samsung Blockchain Keystore app or every time your app calls an API.

public void getKeystoreApiLevel() {
	int keystoreApiLevel = ScwService.getInstance().getKeystoreApiLevel();
	boolean isKeystoreApiSupported = keystoreApiLevel > 0;
}

Get Instance

ScwService.getInstance( ) will need to be used to call any of the APIs provided by Samsung Blockchain Keystore. If Samsung Blockchain Keystore is supported on the device, an instance will be returned. If it is not available on the device, then null will be returned. If null is returned, it means Samsung Blockchain Keystore is not supported on the user’s device. A different keystore or a wallet needs to be used.

ScwService scwServiceInstance = ScwService.getInstance();

Get Seed Hash

getSeedHash API aims to help developers distinguish two things:

(1) Check whether user has set up Samsung Blockchain Keystore.

(2) Check whether Root Seed (recovery phrase) has been changed or not.

Every time a new Root Seed (or a wallet) is created or restored, the seed hash in a String value will be changed. Actually, this is not the preimage of the real seed, but a pseudo hash value. So, it is not possible to calculate the real seed with the pseudo one.

It is strongly recommended for the application to cache the returned hash value to reduce the number of times to check the derived address’s validity. If the returned value is same as cached, the derived addresses are still valid, so the application keeps using these addresses. Otherwise, the application should refresh the addresses from new seed with getAddressList() or getExtendedPublicKeyList() API. Whenever the application starts, it needs to call getSeedHash().

In case that the returned value is a zero-length string, it means that there is no wallet in the Samsung Blockchain Keystore. So, the application UI needs to guide users to jump to Samsung Blockchain Keystore to create a wallet with ScwDeepLink.MAIN deeplink.

public void getSeedHash() {
    String seedHash = ScwService.getInstance().getSeedHash();
    boolean initialized =  (seedHash != null && seedHash.length() > 0);
    }

Check Mandatory App Update

checkForMandatoryAppUpdate API is to help developers check if a user must update Samsung Blockchain Keystore. Because Samsung Blockchain Keystore handles only one task at a time, make sure to NOT call the checkForMandatoryAppUpdate API in the background as it may cause other API calls or requests to be cancelled.

If a mandatory app update is needed, users can be directed to the Galaxy Store using a deeplink, ScwDeepLink.GALAXY_STORE. Otherwise, users will see the mandatory app update popups during an operation process, such as signing a transaction, and will need to update Samsung Blockchain Keystore before proceeding.

Note: ScwService.ScwCheckForMandatoryAppUpdateCallback will need to be implemented correspondingly .

ScwService.ScwCheckForMandatoryAppUpdateCallback callback =
    new ScwService.ScwCheckForMandatoryAppUpdateCallback() {
                @Override
                    public void onMandatoryAppUpdateNeeded(boolean needed) {
                        if(needed){
                            startDeepLink(ScwDeepLink.GALAXY_STORE);
                        }
                    }
                };
                   
    ScwService.getInstance().checkForMandatoryAppUpdate(callback);

How to handle the returned value

A Boolean needed value of whether a mandatory update is needed or not will be returned.

If needed, developers will need to guide users to go to Samsung Blockchain Keystore app page in Galaxy Store to update.

Is Root Seed Backed Up

isRootSeedBackedUp API helps developers check if there is a backup of Root Seed. Since a user can create a wallet without a backup of Root Seed, developers can advise the user to make Root Seed backup.

If a backup of Root Seed is needed, the users will be directed to the page which backs up the mnemonic phrases in the Samsung Blockchain Keystore using a deep link, ScwDeepLink.BACKUP_WALLET.

Boolean isBackedUp = ScwService.getInstance().isRootSeedBackedUp();

        if (!isBackedUp) {
            startDeepLink(ScwDeepLink.BACKUP_WALLET);
        }

How to handle the returned value

The result of Root Seed backup will be returned in a Boolean type.

Get Supported Coins

getSupportedCoins API is used to find out which type of cryptocurrencies are supported, in case there is a different logic that developers must implement for different cryptocurrencies. It is returned in an int array of standard coin types according to BIP standard – for example, 60 for Ethereum.

int[] supportedCoins = ScwService.getInstance().getSupportedCoins();
                
        StringBuilder sb = new StringBuilder();
        sb.append("Supported coins").append('\n');
        for (int i = 0; i < supportedCoins.length; i++ ) {
            sb.append('[').append(i).append("] ").append(supportedCoins[i]).append('\n');
        }
            
        String s = sb.toString();

Get HD Path

getHdPath API helps developers derive HD path for a specified coin type. This API can be used as a parameter when deriving an address and requesting to sign a transaction. Note that UTXO-based cryptocurrency, such as Bitcoin will NOT be supported for this API.

No callback will be needed for this API as HD path in String type will be returned immediately.

//Derive HD path for the cryptocurrency that your app supports

    String ethereumHdPath = ScwService.getHdPath(ScwCoinType.ETH, 0);
            
    String klaytnHdPath = ScwService.getHdPath(ScwCoinType.KLAY, 0);
            
    String tronHdPath = ScwService.getHdPath(ScwCoinType.TRON, 0);
    
    String stellarHdPath = ScwService.getHdPath(ScwCoinType.XLM, 0);

There are two parameters needed: coin type and address index.

Coin Type

Use ScwCoinType class to specify the cryptocurrency that your app uses.
Address Index

Address Index is like an account number. It is recommended to use 0 as the default address index. Increasing the address index will generate a different account. For example, if you need another Ethereum account, then you can increase this address index to 1.

If you need just one address for your service, then make sure to use the same coin type and same address index throughout your service so that user does not get confused with multiple addresses.
Examples

The returned value will be HD path in a String format. This HD path will be needed for getAddressList API and signing cryptocurrency APIs.

ScwService.getHdPath(ScwCoinType.ETH, 0) will return “m/44’/60’/0’/0/0”

ScwService.getHdPath(ScwCoinType.ETH, 1) will return “m/44’/60’/0’/0/1”

ScwService.getHdPath(ScwCoinType.KLAY, 0) will return “m/44’/8217’/0’/0/0”

ScwService.getHdPath(ScwCoinType.TRON, 0) will return “m/44’/195’/0’/0/0”

ScwService.getHdPath(ScwCoinType.XLM, 0) will return “m/44’/148’/0’”
For more details on HD path

Refer to Key Management section in Understanding Keystore. You can find how HD path is used in Samsung Blockchain Keystore.

Get a list of Addresses

getAddressList API allows developers to request to get a list of addresses that correspond to a list of HD Paths. A list of the HD Path, compatible with BIP-44 needs to be passed on to bring the addresses. The depth of HD path should be between 3 and 6.

Also, ScwService.ScwGetAddressListCallback will need to be implemented correspondingly.

ScwService.ScwGetAddressListCallback callback = 
    new ScwService.ScwGetAddressListCallback() {
            @Override
            public void onSuccess(List<String> addressList) {
                        
            }
    
            @Override
            public void onFailure(int errorCode, String errorMessage) {
                //handle errors
    
            }
        };

String hdPath =  ScwService.getHdPath(ScwCoinType.ETH, 0);
    
    ArrayList<String> hdPathList = new ArrayList<>();
    hdPathList.add(hdPath);
    
    ScwService.getInstance().getAddressList(callback, hdPathList);

Hierarchical Deterministic Path (HD Path) Examples

hdPath for Ethereum: m/44'/60'/0'/0/0

hdPath for Bitcoin: m/44'/0'/0'/0/0

If you are unsure about what HD path is, then you can generate HD path with getHdPath API. (Except for Bitcoin)
How to handle the returned value

The returned value will be a list of addresses in a List** format. Each address will correspond to the HD path in the ArrayList.
Minimize calling getAddressList API by checking Seed Hash value

To avoid calling getAddressList API as much as possible, please utilize getSeedHash API to check whether the Root Seed has been changed or not, since different Seed Hash value implies that the corresponding address has also been updated.

Get a list of Extended Public Keys

getExtendedPublicKeyList API allows developers to request to get a list of extended Public Keys that correspond to a list of HD Paths. A list of the HD Path, compatible with BIP-44 needs to be passed on to bring the public key. The depth of path should be between 3 and 6.

Take note that the ScwService.ScwGetExtendedPublicKeyListCallback will need to be implemented correspondingly.

ScwService.ScwGetExtendedPublicKeyListCallback callback = 
    new ScwService.ScwGetExtendedPublicKeyListCallback() {
            @Override
            public void onSuccess(List<byte[]> extendedPublicKeyList) {
                        
            }
    
            @Override
            public void onFailure(int errorCode, String errorMessage) {
                //handle errors
    
            }
        };
    
String hdPath =  ScwService.getHdPath(ScwCoinType.ETH, 0);
    
    ArrayList<String> hdPathList = new ArrayList<>();
    hdPathList.add(hdPath);

    ScwService.getInstance().getExtendedPublicKeyList(callback, hdPathList);

Hierarchical Deterministic Path (HD Path) Examples

hdPath for Ethereum: m/44'/60'/0'/0/0

hdPath for Bitcoin: m/44'/0'/0'/0/0
How to handle the returned value

The returned value will be List <byte[]> that corresponds to each HD path requested in the ArrayList. Each byte array is composed of 33 bytes of compressed public key and 32 bytes of chain code. You can derive the child public key based on this data. Note that you need to derive the address of the compressed public key or call getAddressList API to get the address.
Minimize calling getExtendedPublicKeyList API by checking Seed Hash value

Use getSeedHash API to check whether the Root Seed has been changed or not, since different Seed Hash value implies that corresponding public keys have also been updated.

Sign a Transaction

There are seven APIs that support signing cryptocurrency transactions: Ethereum, Personal Sign Message in Ethereum, Bitcoin, Klaytn, Tron, Personal Sign Message in Tron, and Stellar.

Note: Only signing a transaction is included in the Samsung Blockchain Keystore scope.

1. signEthTransaction API

signEthTransaction API as the name implies, sends a request to Samsung Blockchain Keystore to sign an Ethereum Transaction. Likewise, ScwService.ScwSignEthTransactionCallback will need to be implemented.

ScwService.ScwSignEthTransactionCallback callback = 
		new ScwService.ScwSignEthTransactionCallback() {
				@Override
				public void onSuccess(byte[] signedEthTransaction) {
							
				}
		
				@Override
				public void onFailure(int errorCode, String errorMessage) {
					//handle error
							
				}
			};
		
		
		
			String toAddress = "0xe7425ee1bc64ab7c51ce3617cb83e76fd545f1a9";
			String ethAmount = "123.456789";
			String ethGasPrice = "12000000000";
			String ethGasLimit = "21000";
			String data = "";
            Long chainId = 1;
		
		
		String hdPath =  ScwService.getHdPath(ScwCoinType.ETH, 0);
		
		
		byte[] encodedUnsignedEthTx = createRawTransaction(toAddress, ethAmount, ethGasPrice, ethGasLimit, data);
		
		private byte[] createRawTransaction(param1, param2, …){
		
			  //Implement your code here
		
		}
		
		ScwService.getInstance().signEthTransaction(callback, encodedUnsignedEthTx, hdPath, chainId);