Trust Developer
Search…
Usage Guide
We present here an overview of the basic wallet operations. Language-specific samples are provided in step-by-step guides.
The covered basic operations are:
- Wallet management
- Creating a new multi-coin wallet
- Importing a multi-coin wallet
- Address derivation (receiving)
- Generating the default address for a coin
- Generating an address using a custom derivation path (expert)
- Transaction signing (e.g. for sending)
For the examples we use Bitcoin, Ethereum and Binance Coin as sample coins/blockchains.
Note: Wallet Core does not cover communication with blockchain networks (nodes): address derivation is covered, but address balance retrieval not; transaction signing is covered, but broadcasting transactions to the network not.
In this guide we use small code examples from a Swift sample application, but the focus is on the explanations.
Wallet Management
Multi-Coin Wallet
The Multi-Coin Wallet is a structure allowing accounts for many coins, all controlled by a single recovery phrase. It is a standard HD Wallet (Hierarchically Derived), employing the standard derivation schemes, interoperable with many other wallets: BIP39 for recovery phrase, BIP44/BIP84 for account derivation.
Creating a New Multi-Coin Wallet
When a new wallet is created, a new seed (and thus recovery phrase) is chosen at random.
After creation, the user has to be informed and guided to backup the recovery phrase.
The random generation employs secure random generation, as available on the device.
1
let wallet = HDWallet(strength: 128, passphrase: "")
Copied!
Input parameter
Description
strength
The strength of the secret seed. Higher seed means more information content, longer recovery phrase. Default value is 128, but 256 is also possible.
passphrase
Optional passphrase, used to scramble the seed. If specified, the wallet can be imported and opened only with the passphrase (Not to be confused with recovery phrase).
Importing a Multi-Coin Wallet
A previously created wallet can be imported using the recovery phrase. Typical usecases for import are:
- re-importing a wallet later, into a later installation, or
- importing into another device, or
- importing into another wallet app.
If the wallet was created with a passphrase, it is also required.
1
let wallet = HDWallet(mnemonic: "ripple scissors kick mammal hire column oak again sun offer wealth tomorrow wagon turn fatal", passphrase: "")
Copied!
Input parameter
Description
mnemonic
a.k.a. recovery phrase. The string of several words that was used to create the wallet.
passphrase
Optional passphrase, used to encrypt the seed.
Account Address Derivation
Each coin needs a different account, with matching address. Addresses are derived from the multi-coin wallet. Derivation is based on a derivation path, which is unique for each coin, but can have other parameters as well. Each coin has a default derivation path, such as
"m/84'/0'/0'/0/0" for Bitcoin and "m/44'/60'/0'/0/0" for Ethereum.Generating the Default Address for a Coin
The simplest is to get the default address for a coin -- this requires no further inputs. The address is generated using the default derivation path of the coin.
For example, the default BTC address, derived for the wallet with the mnemonic shown above, with the default BTC derivation path (
m/84'/0'/0'/0/0) is: bc1qpsp72plnsqe6e2dvtsetxtww2cz36ztmfxghpd. For Ethereum, this is 0xA3Dcd899C0f3832DFDFed9479a9d828c6A4EB2A7.Here is the sample code fort obtaining the default address for different coins:
1
let addressBTC = wallet.getAddressForCoin(coin: .bitcoin)
2
let addressETH = wallet.getAddressForCoin(coin: .ethereum)
3
let addressBNB = wallet.getAddressForCoin(coin: .binance)
Copied!
Generating an Address Using a Custom Derivation Path (Expert)
It is also possible to derive addresses using custom derivation paths. This can be done in two steps: first a derived private key is obtained, then an address from it.
Warning: use this only if you are well aware of the semantics of the derivation path used!
Security Warning: if secrets such as private keys are handled by the wallet, even if for a short time, handle with care! Avoid any risk of leakage of secrets!
1
let key = wallet.getKey(derivationPath: "m/44\'/60\'/1\'/0/0") // m/44'/60'/1'/0/0
2
let address = CoinType.ethereum.deriveAddress(privateKey: key)
Copied!
For example, a second Ethereum address can be derived using the custom derivation path
”m/44'/60’/1’/0/0” (note the 1 in the third position), yielding address 0x68eF4e5660620976a5968c7d7925753D3Cc40809.Transaction Signing
In general, when creating a new blockchain transaction, a wallet has to:
- 1.Put together a transaction with relevant fields (source, target, amount, etc.)
- 2.Sign the transaction, using the account private key. This is done by Wallet Core.
- 3.Send to a node for broadcasting to the blockchain network.
The exact fields needed for a transaction are different for each blockchain. In Wallet Core, signing input and output parameters are typically represented in a protobuf message (internally needed for serialization for passing through different language runtimes).
A generic, coin-independent signer also exists (AnySigner), but its usage is recommended only in browser-based applications.
Bitcoin Transaction Signing
Bitcoin is the first
UTXO (Unspent Transaction Output) based cryptocurrency / blockchain, if you haven't read the documentation about Bitcoin, we highly recommend you to read developer glossary and raw transaction format, these will help you understand how to sign a Bitcoin transaction. Wallet Core supports Bitcoin, Bitcoin Cash, Zcash, Decred and a few forks.The most important models in Swift are
BitcoinSigningInput and BitcoinUnspentTransactionBitcoinSigningInput
Field
Sample value
Description
hash_type
BitcoinSigHashType.all
amount
10000
Amount (in satoshi) to send (value of new UTXO will be created)
byteFee
1
Transaction fee is
byte_fee x transaction_size, Wallet Core will calculate the fee for you by defaulttoAddress
bc1q03h6k5lt6pzfjaanz5mlnmuc7aha2t3nkz7gh0
Recipient address (Wallet Core will build lock script for you)
changeAddress
1AC4gh14wwZPULVPCdxUkgqbtPvC92PQPN
Address to receive changes, can be empty if you sweep a wallet
privateKey
[Data(...), Data(...)]
Private keys for all the input UTXOs in this transaction
scripts
[
script_hash: Data(...)]Redeem scripts indexed by script hash, usually for
P2SH, P2WPKH or P2WSHutxo
[BitcoinUnspentTransaction]
All the input UTXOs, see below table for more details
useMaxAmount
false
Consume all the input UTXOs, it will affect fee estimation and number of output
BitcoinUnspentTransaction
Field
Sample value
Description
outPoint
BitcoinOutPoint(hash:index:)
Refer to a particular transaction output, consisting of a 32-byte TXID and a 4-byte output index number (vout)
amount
10000
A value field for transferring zero or more satoshis
script
0x76a9146cfa0e96c34fce09c0e4e671fcd43338c14812e588ac
A script (ScriptPubKey) included in outputs which sets the conditions that must be fulfilled for those satoshis to be spent
1
let utxoTxId = Data(hexString: "050d00e2e18ef13969606f1ceee290d3f49bd940684ce39898159352952b8ce2")! // latest utxo for sender, "txid" field from blockbook utxo api: https://github.com/trezor/blockbook/blob/master/docs/api.md#get-utxo
2
let privateKey = PrivateKey(data: Data(hexString: "7fdafb9db5bc501f2096e7d13d331dc7a75d9594af3d251313ba8b6200f4e384")!)!
3
let address = CoinType.bitcoinCash.deriveAddress(privateKey: privateKey)
4
5
let utxo = BitcoinUnspentTransaction.with {
6
$0.outPoint.hash = Data(utxoTxId.reversed()) // reverse of UTXO tx id, Bitcoin internal expects network byte order
7
$0.outPoint.index = 2 // outpoint index of this this UTXO, "vout" field from blockbook utxo api
8
$0.outPoint.sequence = UINT32_MAX
9
$0.amount = 5151 // value of this UTXO, "value" field from blockbook utxo api
10
$0.script = BitcoinScript.lockScriptForAddress(address: address, coin: .bitcoinCash).data // Build lock script from address or public key hash
11
}
12
13
let input = BitcoinSigningInput.with {
14
$0.hashType = BitcoinScript.hashTypeForCoin(coinType: .bitcoinCash)
15
$0.amount = 600
16
$0.byteFee = 1
17
$0.toAddress = "1Bp9U1ogV3A14FMvKbRJms7ctyso4Z4Tcx"
18
$0.changeAddress = "1FQc5LdgGHMHEN9nwkjmz6tWkxhPpxBvBU" // can be same sender address
19
$0.utxo = [utxo]
20
$0.privateKey = [privateKey.data]
21
}
22
23
let output: BitcoinSigningOutput = AnySigner.sign(input: input, coin: .bitcoinCash)
24
guard output.error.isEmpty else { return }
25
// encoded transaction to broadcast
26
print(output.encoded)
Copied!
It's worth to note that you can also calcuate fee and change manually (by using a
BitcoinTransactionPlan struct)
Below is another real world Zcash transparent transaction demonstrate this1
let utxos = [
2
BitcoinUnspentTransaction.with {
3
$0.outPoint.hash = Data(hexString: "53685b8809efc50dd7d5cb0906b307a1b8aa5157baa5fc1bd6fe2d0344dd193a")!
4
$0.outPoint.index = 0
5
$0.outPoint.sequence = UINT32_MAX
6
$0.amount = 494000
7
$0.script = Data(hexString: "76a914f84c7f4dd3c3dc311676444fdead6e6d290d50e388ac")!
8
}
9
]
10
11
let input = BitcoinSigningInput.with {
12
$0.hashType = BitcoinSigHashType.all.rawValue
13
$0.amount = 488000
14
$0.toAddress = "t1QahNjDdibyE4EdYkawUSKBBcVTSqv64CS"
15
$0.coinType = CoinType.zcash.rawValue
16
$0.privateKey = [Data(hexString: "a9684f5bebd0e1208aae2e02bc9e9163bd1965ad23d8538644e1df8b99b99559")!]
17
$0.plan = BitcoinTransactionPlan.with {
18
$0.amount = 488000
19
$0.fee = 6000
20
$0.change = 0
21
// Sapling branch id
22
$0.branchID = Data(hexString: "0xbb09b876")!
23
$0.utxos = utxos
24
}
25
}
26
27
let output: BitcoinSigningOutput = AnySigner.sign(input: input, coin: .zcash)
28
29
// encoded transaction to broadcast
30
print(output.encoded)
Copied!
Besides orignal Bitcoin RPC, there are many other APIs / block explorer can get UTXO and broadcast raw transaction, like: insight api, trezor blockbook, blockchain com, blockchair api.
Ethereum Transaction Signing
A simple Ethereum send transaction needs the following fields:
Field
Sample value
Description
chainID
1
Network selector, use 1 for mainnet (see https://chainid.network for more)
nonce
1
The count of the number of outgoing transactions, starting with 0
gasPrice
3600000000
The price to determine the amount of ether the transaction will cost
gasLimit
21000
The maximum gas that is allowed to be spent to process the transaction
to
<address>
The account the transaction is sent to, if empty, the transaction will create a contract
value
100000000
The amount of ether to send
data
Could be an arbitrary message or function call to a contract or code to create a contract
Several parameters, like the current nonce and gasPrice values can be obtained from Ethereum node RPC calls (see https://github.com/ethereum/wiki/wiki/JSON-RPC, e.g., eth_gasPrice).
Code example to fill in the signer input parameters:
1
let input = EthereumSigningInput.with {
2
$0.chainID = Data(hexString: "01")!
3
$0.gasPrice = Data(hexString: "d693a400")! // decimal 3600000000
4
$0.gasLimit = Data(hexString: "5208")! // decimal 21000
5
$0.toAddress = "0xC37054b3b48C3317082E7ba872d7753D13da4986"
6
$0.transaction = EthereumTransaction.with {
7
$0.transfer = EthereumTransaction.Transfer.with {
8
$0.amount = Data(hexString: "0348bca5a16000")!
9
}
10
}
11
$0.privateKey = wallet.getKeyForCoin(coin: .ethereum).data
12
}
Copied!
Then Signer is invoked, and the signed and encoded output retrieved:
1
let output: EthereumSigningOutput = AnySigner.sign(input: input, coin: .ethereum)
2
print(" data: ", output.encoded.hexString)
Copied!
For more details on Ethereum transactions, check the Ethereum documentation. A few resources are here:
- https://medium.com/@codetractio/inside-an-ethereum-transaction-fa94ffca912f
- https://kauri.io/article/7e79b6932f8a41a4bcbbd194fd2fcc3a/v2/ethereum-101-part-4-accounts-transactions-and-messages
- https://github.com/ethereumbook/ethereumbook/blob/develop/06transactions.asciidoc
Binance Chain (BNB) Transaction Signing
Binance Chain is built upon cosmos-sdk, instead of
Message, transaction in Binance Chain is called Order, Binance.proto shows all the orders that Wallet Core currently supports.To sign a order, you need to use
BinanceSigningInput:Field
Sample value
Description
sendOrder
<sendOrder>
SendOrder contains
inputs and outputs, see below sample code for more detailsA Swift sample code send order is shown below:
1
let privateKey = PrivateKey(data: Data(hexString: "95949f757db1f57ca94a5dff23314accbe7abee89597bf6a3c7382c84d7eb832")!)!
2
let publicKey = privateKey.getPublicKeySecp256k1(compressed: true)
3
4
let token = BinanceSendOrder.Token.with {
5
$0.denom = "BNB" // BNB or BEP2 token symbol
6
$0.amount = 1 // Amount, 1 BNB
7
}
8
9
// A.k.a from / sender
10
let orderInput = BinanceSendOrder.Input.with {
11
$0.address = CosmosAddress(hrp: .binance, publicKey: publicKey)!.keyHash
12
$0.coins = [token]
13
}
14
15
// A.k.a to / recipient
16
let orderOutput = BinanceSendOrder.Output.with {
17
$0.address = CosmosAddress(string: "bnb1hlly02l6ahjsgxw9wlcswnlwdhg4xhx38yxpd5")!.keyHash
18
$0.coins = [token]
19
}
20
21
let input = BinanceSigningInput.with {
22
$0.chainID = "Binance-Chain-Nile" // Testnet Chain id
23
$0.accountNumber = 0 // On chain account number
24
$0.sequence = 0 // Sequence number
25
$0.source = 0 // BEP10 source id
26
$0.privateKey = privateKey.data
27
$0.memo = ""
28
$0.sendOrder = BinanceSendOrder.with {
29
$0.inputs = [orderInput]
30
$0.outputs = [orderOutput]
31
}
32
}
33
34
let output: BinanceSigningOutput = AnySigner.sign(input: input, coin: .binance)
35
// encoded order to broadcast
36
print(output.encoded)
Copied!
For more details please check the Binance Chain documentation:
- https://docs.binance.org/encoding.html
- https://docs.binance.org/api-reference/dex-api/paths.html#http-api
Consult the complete sample applications for more details.
Last modified 26d ago
Copy link
Contents
Wallet Management
Multi-Coin Wallet
Creating a New Multi-Coin Wallet
Importing a Multi-Coin Wallet
Account Address Derivation
Generating the Default Address for a Coin
Generating an Address Using a Custom Derivation Path (Expert)
Transaction Signing
Bitcoin Transaction Signing
Ethereum Transaction Signing
Binance Chain (BNB) Transaction Signing