Tutorial: Send Ethereum transactions

Product: Wallet as a Service (WaaS)

Duration: 30 minutes (if experienced with Postman), 60 minutes.

Level: Beginner

Content:

• Creation of two wallets

• Acquirement of test tokens

• Sending a transaction without our Gas Tank

• Sending a transaction with our Gas Tank

• Balance reading of the wallets

Introduction

This tutorial aims to give you a brief introduction to Tangany Wallet as a Service and will demonstrate some key features while working on the Ethereum blockchain. I will show you how to send some Ethereum (smart contract) transactions and I will guide you to send ERC20 tokens and to check your balance.

This tutorial is very beginner-friendly and requires no coding skills. We will utilize Tangany WaaS, therefore you must already have access to a demo account.

Requirements

1. Demo Account: contact Tangany’s sales & support team to obtain a free demo account to use Tangany WaaS

2. Postman: visit https://docs.tangany.com and click the upper right Run in Postman button to get started. Tangany WaaS specifications will be imported to your Postman workspace. I recommend using a Postman desktop client to avoid cross-browser request issues.

Wallets and transactions

Before you can start calling Tangany WaaS you need to make sure you’re authenticated. Open your Postman client with your already imported Tangany WaaS API collection. Tangany provided an environment variable preset called Default (public) which can be found at the upper right in Postman. Edit this environment preset and fill in the values you received from Tangany’s sales team.

tangany-client-id
tangany-client-secret
tangany-vault-url
tangany-subscription

Head over to your imported Postman Collection Tangany Wallet as a Service. We will start with an easy task. Let’s create two wallets for Alice and Bob. Open the wallets → Create wallet endpoint and switch to the Headers tab. As you can see, authorization headers are already set.

Authorization headers for creating new wallets using Postman's environment preset named Default (public)

Switch to the Body tab and edit the wallet param:

{
  "wallet": "alice",
  "useHsm": false,
  "tags": [
   {
      "description": "This is the new wallet of Alice."
   }
  ]
}

Click Send and repeat this API call for bob. Your response will be similar to this:

Result of create wallet request

Congratulations 
You have successfully created two wallets.

Btw: HSM wallets increase your wallet security even further. Contact Tangany’s support team to get more information. HSM wallets are not supported in demo accounts.

Hint: In postman folder open wallets → List wallets endpoint and click Send to get a list of your created wallets.

Use List Wallets to get a complete list of all your created wallets

As response you should get a complete list of all your wallets:

Send Ethereum transaction

Our newly created wallets don’t hold any Ether. So let’s send some data from Alice to Bob.

1. Open the eth/wallet/{wallet} → Make transaction endpoint in the Postman collection.

2. Open the Params tab and set {{wallet}} to alice or edit the corresponding variable in your Postman environment variables set.

3. Switch to Body tab. Since you don’t know the Ethereum address of Bob’s wallet, you can make use of Tangany’s wallet substitution functionality. Tangany resolves wallet names to its Ethereum address if the sender’s and recipient’s wallet reside in the same Key Vault. Change the request body and click Send:

{
  "amount": "0",
  "wallet": "bob"
}

Oh, snap 🤔. This should not work and you will get a response like:

{
  "statusCode": 400,
  "activityId": "d33cca24-9ff8-4e22-ab8c-1951bdaa1b59",
  "message":    "Cannot process the Ethereum transaction due to
                 insufficient wallet balance: 0 tETH (requires 0                 
                 tETH transaction value and 0.0000525 tETH fee)"
}

What happened? You tried to send a transaction from Alice to Bob with an Ether amount of 0 but still got an insufficient funds error. Every transaction needs some gas for the network to accept and mine it. So even for 0 amount transactions, it’s necessary to hold a positive balance to pay the network fees (gas).

Tangany provides a convenient way to work around this circumstance. Switch to Headers tab, activate tangany-use-gas-tank header and set its value to true.

After you clicked Send again a lot of things will happen in the background. First, Tangany will validate your transaction, as they did before. Then your wallet gets pre-funded. Tangany sends some Ether to your wallet so you can pay your actual transaction. After adding network fees your transaction, it gets signed and sent.

The asynchronous endpoint responds with a status URI like:

{
  "statusUri": "/request/223db8bc-c81b-4874-9ed2-1e7e68052666",
  "id": "223db8bc-c81b-4874-9ed2-1e7e68052666"
}

Open the Get asynchronous request status endpoint in the Postman collection at the very bottom. Your authorization headers and the asynchronous request-id should already be set up. Click Send to get your transaction status.

Your transaction status will run through multiple stages. Pending is the first and indicates a starting process.

{
  "process": "Pending",
  "status": null,
  "created": "2020-08-06T11:19:34Z",
  "updated": "2020-08-06T11:19:34Z",
  "output": null
}

As mentioned above, you used the Tangany gas tank to pre-fund your transaction. This stage may take some seconds because Tangany will send some Ether to your wallet first.

{
  "process": "Running",
  "status": {
    "stage": "pre-funding wallet"
  },
  "created": "2020-08-06T11:19:34Z",
  "updated": "2020-08-06T11:19:47Z",
  "output": null
}

When the network fees were successfully transacted, your actual transaction is signed and sent.

{
  "process": "Running",
  "status": {
    "stage": "sending transaction"
  },
  "created": "2020-08-06T11:19:34Z",
  "updated": "2020-08-06T11:20:26Z",
  "output": null
}

As soon as your transaction was sent, Tangany waits for your transaction to be processed, added to the chain, and to be confirmed. You have control over the confirmation level by setting a tangany-ethereum-tx-confirmations header to none|default|secure. Visit the Tangany docs for more header settings.

{
  "process": "Running",
  "status": {
    "stage": "awaiting transaction confirmation",
    "hash": "0xa62e3b2f20ca77745281e22f2b2f5e73957a7ac0d90ad3e8a631c6f8e1786c42"
  },
  "created": "2020-08-06T11:19:34Z",
  "updated": "2020-08-06T11:20:28Z",
  "output": null
}

The final status provides all information about the successfully added and confirmed transaction.

{
  "process": "Completed",
  "status": {
    "stage": "transaction confirmed"
  },
  "created": "2020-08-06T11:19:34Z",
  "updated": "2020-08-06T11:21:37Z",
  "output": {
    "hash": "0xa62e3b2f20ca77745281e22f2b2f5e73957a7ac0d90ad3e8a631c6f8e1786c42",
    "blockNr": 8444691,
    "data": "0x",
    "status": "confirmed"
  }
}

Done 🎉
You can’t believe it? Go to https://ropsten.etherscan.io/ and search for your transaction hash. You can find your transaction hash in your transaction status request-response.

What about tokens?

Let’s move forward to sending tokens. This short tutorial is not about creating ERC20 tokens, so I deployed one for you.

Bob wants to thank Alice for her transaction and strives to send Alice some TanganyLoveTokens (short TLT). First, he needs to request free love from Tangany by making a smart contract transaction.

1. Open the eth/contract/{contract}/{wallet} → Execute contract endpoint in the Postman collection.

2. In Params tab set wallet to bob andcontract to 0x62f49D4A051a22Cd5573b1197FD3E96F1026346D (updated) or update it in your global environment.

3. Activate tangany-ethereum-tx-speed header in Headers tab and set it to fast. Activate tangany-use-gas-tank header and set it to true.

4. For this tutorial, I modified an ERC20 token that everyone can mint tokens for an address. Switch to the Body tab and paste in the body.

{
    "function": "mint(wallet,uint256)",
    "inputs": [
        "bob",
        "1"
    ]
}

The function property contains the smart contract method which should be called including its argument data types. We call the contract method mint and will provide two arguments:

• wallet (Tangany will resolve it to address)

• uint256 (unsigned integer)

The inputs Array contains the actual values. Bob’s wallet name bob and the amount 1. Since we do not expect any outputs we do not need to provide an outputs property. Press Send to get your asynchronous request-id.

Switch back to your recently used Get asynchronous request status endpoint and check your status.

Check Ethereum token balance

ERC20 tokens provide a standardized set of methods and one of them is balanceOf(). Invoking the balanceOf method of an ERC20 smart contract does not require any gas since it is a read-only Blockchain operation (also known as a "call") which means it does not alter the state of the smart contract (something that a "transaction" would do). Tangany provides a handy shortcut for simple smart contract calls which take an address as method argument and expected output of type uint.

1. Open the eth/contract/{contract}/{wallet} → call → [GET] Call contract method via wallet endpoint in the Postman collection.

2. In the Params tab set wallet to bob andcontract to 0x62f49D4A051a22Cd5573b1197FD3E96F1026346D (updated) and method to balanceOf.

3. Change query parameter type in url from string to uint256:
   type=uint256

4. Click Send and you’ll get a similar response to:

{
  "list": [
    {
      "type": "uint256",
      "value": "1000000000000000000"
    }
  ]
}

Bob is the proud owner of one TanganyLoveToken ❤
The TLT is a standard ERC20 token represented using 18 decimals.

Hint: we used a Tangany shortcut endpoint to get Bob’s balance. There are more contract call endpoints like eth/contract/{contract} → Call contract. You can call every method of a smart contract you know of. Regarding the balance you would receive the same response by providing the contract address in the Params tab and passing this body in the Body tab:

{
    "function": "balanceOf(wallet)",
    "inputs": ["bob"],
    "outputs": ["uint256"]
}

For retrieving balances you can also use eth → Get ERC20 token balance.

Transfer Ethereum Token

To send some love to Alice, Bob needs to make another Ethereum smart contract transaction. Transferring tokens is altering the contracts state so a contract call is not sufficient. Follow the steps you already did to get the TanganyLoveToken except for the request body. The method you want to call is defined like this:

function transfer(address recipient, uint256 amount) public { ... }

Thus your request body should look like this:

{
    "function": "transfer(wallet,uint256)",
    "inputs": [
        "alice",
        "1000000000000000000"
    ]
}

Send the asynchronous request and wait for it to get processed.

Hint: besides known solidity types like uint, address etc. Tangany supports the custom type argument wallet. Under the hood, Tangany resolves it to the address of said wallet and passes it as the type address to the invoked smart contract method. Anyway, for transactions and calls outside your own Key Vault, you have to use real Ethereum addresses. You can obtain Alice’s and Bob’s Ethereum address by calling eth/wallet/{wallet} → Get wallet status
If you use Ethereum addresses the request body of the above contract transaction would change:

{
    "function": "transfer(address,uint256)",
    "inputs": [
        "0xe53e1325a909824009f15e5cb7f6651d0f29058f",
        "1000000000000000000"
    ]
}

That’s all for now. I hope I could give you a brief introduction to Tangany WaaS. For more information visit us at https://tangany.com. I’m open to any kind of feedback, so please let me know.

Take care,
Dan