Examples

Before following the examples, make sure you have the Crypto SDK installed and ready to use. Some sections may also utilise parts of the Client SDK, but they will highlight this where relevant.

These examples serve to get you up to speed with common usecases for the SDK and to help you understand how to interact with the ARK blockchain. They also provide a way of seeing the SDK in action as opposed to reading about standalone functions.

Transactions

A transaction is an object specifying the transfer of funds from the sender's wallet to the recipient's. Each transaction must be signed by the sender's private key to prove authenticity and origin. After broadcasting through the client SDK, a transaction is permanently incorporated in the blockchain by a Validator Node. Transactions on Mainsail make use of the EIP-155 format, which is a standard for Ethereum transactions, ensuring compatibility with the Ethereum ecosystem.

The crypto SDK can sign a transaction using your private key or passphrase (from which the private key is generated). Ensure you are familiar with digital signatures before using the crypto SDKs.

In order to send a transaction, you will require a nonce value. This value is unique to each transaction and is used to prevent replay attacks. The nonce is incremented by one for each transaction sent from an address. In the examples below, we assume that you have retrieved the nonce prior by using the Client SDK and that it is stored in a variable named $nonce.

Please mind that transaction values are in wei, which is the smallest unit of ARK. The SDK provides a utility to convert ARK to wei and vice versa for ease of use. As these values grow large quickly (1 ARK = 1e18 wei), it is recommended to use the utility functions provided by the SDK to avoid numeric limitations.

Build and Sign a Transfer Transaction

This will give you a signed transfer transaction, ready to be send to the network to be included in a block.

TODO

Build and Sign a Vote Transaction

This will give you a signed vote transaction, ready to be send to the network to be included in a block.

TODO

Build and Sign an Unvote Transaction

This will give you a signed vote transaction, ready to be send to the network to be included in a block.

TODO

Build and Sign a Multipayment Transaction

This will give you a signed multipayment transaction, ready to be send to the network to be included in a block.

TODO

Build and Sign a Validator Registration Transaction

For a Validator Registration you will need to create a BLS keypair prior to creating the transaction. The public key of the BLS keypair will be used as the validator public key in the transaction.

TODO

Build and Sign a Validator Resignation Transaction

After a Validator has been registered on an address, you can also resign it.

TODO

Build and Sign a Username Registration Transaction

Each address can register a unique username on the blockchain. This username has limitations to what characters can be used and how long it can be, which are checked by the SDK before sending the transaction.

TODO

Build and Sign a Username Resignation Transaction

Once an address has a username registered on the blockchain, it can also resign it. This will remove the username from the blockchain and make it available for others to register.

TODO

Build and Sign a Custom EvmCall Transaction (Smart Contract Interaction)

There is also the option to send your own (custom) EvmCall transactions to interact with smart contracts on the ARK blockchain. This is a more advanced feature and requires you to know the contract address and the contract method you want to call. Under the hood all of the above transactions are EvmCall transactions (except Transfer), but they are abstracted away for ease of use.

TODO

Broadcasting Transactions

After signing a transaction, you can broadcast it to the network using the public API SDK. The SDK will handle the serialization and deserialization of the transaction object. This is a combined effort from the Crypto and Client SDKs. For this we assume you already have a signed transaction builder object stored in a variable named $builder, e.g. from the examples above, and a $client object initialized to interact with the network.

TODO

The result will indicate to you if the transaction was successfully broadcasted to the network and accepted or if any issues occured. Note that being accepted on the network only indicates if the transaction is constructed well and the signature is correct. It does not guarantee that the transaction will be able to be processed in the EVM, so you will want to keep an eye on the next block to see if your transaction was successfully executed.

Build and Sign a Transaction using a Second Signature

Although Mainsail does not allow new second signatures to be registered, legacy addresses with one enabled can still use it to sign their transactions. There is a legacySecondSign method on each of the builders that allows you to sign the transaction with a second signature when necessary. One such example is given below.

TODO

Message

The crypto SDK not only supports transactions but can also work with other arbitrary data (expressed as strings). Messages are using the EIP-191 format for compatibility with the Ethereum ecosystem.

Sign

Signing a string works much like signing a transaction: in most implementations, the message is hashed, and the resulting hash is signed using the private key or passphrase.

TODO

Verify

A message's signature can easily be verified by hash, without the private key that signed the message, by using the verify method.

TODO

Identities

The identities class allows for the creation and inspection of keyPairs from passphrases. Here you find vital functions when creating transactions and managing wallets.

Derive the Address from a Passphrase

TODO

Derive the Address from a Public Key

TODO

Derive the Address from a Private Key

TODO

Validate an Address

TODO

Private Key, Public Key, and WIF

This section contains examples on how to work with private keys, public keys, and WIFs. From creating them from passphrases to validating them.

Public Keys may be freely shared, and are included in transaction objects to validate the authenticity. However, Private Keys and WIFs should ALWAYS be kept secret.

Derive the Private Key from a Passphrase

TODO

Derive the Private Key Instance Object from a Hexadecimal Encoded String

TODO

Derive the Private Key from a WIF

TODO

Derive the Public Key from a Passphrase

TODO

Derive the Public Key Instance Object from a Hexadecimal Encoded String

TODO

Derive the WIF from a Passphrase

TODO

Serialization and Deserialization

Serialize

Serialization of a transaction object ensures it is compact and properly formatted to be incorporated in the ARK blockchain. If you are using the crypto SDK in combination with the public API SDK, you should not need to serialize manually.

TODO

Deserialize

A serialized transaction may be deserialized for inspection purposes. The public API does not return serialized transactions, so you should only need to deserialize in exceptional circumstances.

TODO