As a user, I use a shortcode to send SWT to another Swarm City user.

[kikipluche]

Abstract:

In order to send SWT in Swarm City on Rinkeby, the sender needs the address, the userName and the avatar of the receiver. For this, we use the concept of shortCode. We use this concept for 3 reasons:

• to make sure all transactions happen securely in the same ethereum network
• to make doing a transaction in Swarm City fool-proof
• to minimize the use of blockchain-jargon

How it works:

The receiver shares his shortcode with the sender offline (e.g. by phone, or in real life). The sender taps the 'send-SWT'-button and enters an amount and a shortcode of the receiver in the first view of the send-flow. When submitting, an API call is made. The shortcode is sent to the API, the API returns the public key, the username and the avatar (after resolving the ipfsHash)

The username is displayed, along with the avatar image. The sender confirms the identity of the receiver. The sender then confirms the total transaction (= amount and receiver). When confirming, a transaction is created on the sender's client. The sender signs this transaction. The signed transaction is sent to the API service "sendSignedTransaction".

A green progress screen is shown. The user can continue as soon as the transactionHash is received. This screen has a timeout of 30 seconds - meaning if a transactionHash is not received in 30 seconds, the green screen will show an error and the user can return to the wallet view.

When successful, the journey ends at the wallet-view, where a new historyItem is seen in the transactionHistory.

The generated code is single-use , we never will re-use a shortcode. Not when it expires , and not when the request was canceled.

Jobs:

N/a

API:

readShortCode

A function readShortCode that returns the user data for the given shortcode.

emit : readShortCode data:

{
 shortCode: <String> // shortCode - like "12345"
}

This function returns the payload that was attached to this shortcode - if it exists and didn't yet expire. the return code for the data will be 200.

response on success:

{
    response: 200,
    data: {
      address: "0xabc...123",
      userName: "swarm citizen",
      avatar: <String> // base64
     }
}

response on failure:

If the shortcode is not a valid shortcode, the API will return a 400 response code. The user data is not returned.

{
    response: 400
}

replyShortCode

A socket handler that accepts the shortcode a signed transaction and puts it in the transaction pool.

emit : replyShortCode data:

{
    shortCode : <String>
    tx : '0x...', // signed transaction encoded as a HEX string
}

response on success:

{
    response: 200,
    data: {
        transactionHash: '0x...'
    }
}

response on server error:

{
    response: 500,
    data : <String> // the error description in EN
}

API Documentation

Internally the tx is just delivered to the transaction pool , and wraps around the sendSignedTransaction call

Reference of server code : https://github.com/swarmcity/SwarmCityAPI/blob/master/src/functions/SendRawTxFunction.js

Example usage on client: https://github.com/swarmcity/SwarmCityAPI/blob/master/test/testSendRawTx.js#L34-L41

Socket cheatsheet https://socket.io/docs/emit-cheatsheet/

---

What it looks like in front end:

route: /my-wallet

In the wallet-view, we see the 'send SWT'-button in the middle of the page, above the 'shortcode'-button.

When the user taps the 'send SWT'-button, the middle part of the page changes: the two buttons disappear, and first view of the send-flow appears.

First view:

The first view of the send-flow contains:

• inputfield (label: 'Amount', type: 'Number') for the amount you want to send
• inputfield (label: 'Receiver’s shortcode', type: 'Number') for the shortcode of the receiver
• x-mark (cancel-button)
• big white button with blue next-icon (confirm-button)

When the x-mark is tapped, the flow is cancelled: this makes the default view appear again in the middle of the page (= 2 buttons).

The big white button is disabled until the values of both inputfields are valid:

• The amount is a Numeric value with decimals
• The amount is less than the total balance
• The amount is more than 0 SWT
• The shortcode is a Numeric 5 digit value.

When the big white button is enabled, the user can tap to submit the values and go to the second view.

Second view:

The second view of the send-flow contains:

• copy: 'Looking for receiver…'
• blue x-mark (cancel-button)

There is a timeout of 30 seconds on this view - when there's no response, the view changes to third view - errorstate.

When the receiver is found, the view changes to third view - normalstate.

When the user taps the blue X-mark (cancel-button), the whole process is aborted.

Third view - normalstate:

The third view of the send-flow contains:

• copy: 'Receiver found!'
• avatar of the receiver
• userName of the receiver
• the publicKey of the receiver
• blue x-mark (cancel-button)
• big white button with next-icon (confirm-button)

When the user taps the big white button with next-icon, he confirms the receiver, and the page changes to the confirm-sending-page.

When the user taps the blue X-mark (cancel-button), the whole process is aborted.

Third view - errorstate:

The third view - errorstate of the send-flow contains:

• copy: 'No receiver found.'
• blue x-mark (cancel-button)

When the user taps the blue X-mark (cancel-button), the whole process is aborted.

confirm-sending-page

The confirm-sending-page contains:

• copy: 'You’re about to send (amount) SWT to (receiver userName)'
• copy: 'This can't be undone.'
• black x-mark (cancel-button)
• big white button with blue V-mark (confirm-button)

When the user taps the black X-mark (cancel-button), the whole process is aborted.

When the user taps the big white button with blue V-mark, he confirms the transaction, triggering the password-unlock for signing this transaction.

confirm-sending-page (with password-unlock)

The password-unlock is an overlay on the page it is on. It contains:

• avatar
• inputfield (label: 'password?')
• black x-mark (cancel-button)
• big white button with blue V-mark (confirm-button)

When the user taps the black X-mark (cancel-button), the password-unlock dissappears, showing the page below as she was.

The big white button with blue V-mark is disabled until it contains 1 character. When it is enabled, and the user taps it, he signs the transaction. The signed transaction is sent to the API. The page changes to transaction-progress-page.

transaction-progress-page

The transaction-process-page contains:

• copy: 'Your transaction is being processed.'
• copy: 'Received TXhash'
• white dots / white V-mark / black Xmark When the txhash hasn't arrived yet, we see the 3 white dots (animating). When the transactionHash hàs arrived, the dots turn into the white V-mark. There is a timeout of 30 seconds on this page. When the timout ends and no transactionHash was received, the 3 white dots turn into the black Xmark and the errormessage is shown, as seen on transaction-progress-page (error).
• a big white button with a black next-icon

When entering the page, the big white button with black next-icon is disabled. When the transactionHash is received (making the white dots turn into the white V), the button is enabled.

When the user taps this button, the page changes back to wallet-view, ending the send-flow (resulting in a new historyItem).

transaction-progress-page (error) The transaction-progressing-page (error) contains:

• copy: 'Your transaction is being processed.'
• copy: 'Received TXhash'
• black Xmark see explanation above
• a black line
• copy 'Something went wrong, no TXhash was received.'
• a big white button with a black prev-icon

When in this view, the process of sending has failed (because no transactionHash was received). Tapping the big white button with black prev-icon, will lead the user back to the wallet-view.

Documentation / references

N/a

♡

[xardass]

When a user loses connection before txHash has been received, there is no sign of a pending transaction in his txHistory. There is a risk the user will repeat the same transaction, not knowing that his previous one DID get sent to the mempool.

Maybe we can think about limiting the shortcode to single usage? Once the API makes a transaction to that shortcode, enfore the creation of a new one?

Update:

• Specifications already designed shortcode as single-use.
• losing connection = edge-case for further discussion

[bkawk]

Exposing the user to the terminology TxHash on the transaction-progressing-page with text such as 'Received TXhash' and 'Something went wrong, no TXhash was received.' I feel is going against the intention "to not bother users with blockchain-jargon (public keys etc.)"

The 30 second timeout presents the possibility for the user to make a transaction, sign it, send it, wait more than 30 seconds and not get a txHash back, the user will then feel that the transaction didn't go through and may make a second transaction, when in fact the first transaction did complete.

[kikipluche]

we will review the 30 seconds and review the copy, maybe change to "this is taking longer than expected" => to be discussed.

Update: we will first test this version, if this error message leads to wrong behaviour, we can iterate and change.

[kikipluche]

TxHash will stay like this, for this iteration. Losing connection and the edge case people doing a transaction twice is to be seen during testing, we will take this matter in a general epic about logging.

[kikipluche]

19/3: This epic is clear for dev, ready for execution

[bkawk]

In the abstract, you detail " I need the address" who is the I? Is it the API?

[bkawk]

The text reads "Something went wrong, no TXhash was received." I still feel this is contrary to the abstract where this is stated "to not bother users with blockchain-jargon (public keys etc.)"

[bkawk]

I feel this is a core piece of functionality, the abstract also states "to make doing a transaction in Swarm City fool-proof" The 30 seconds I still feel is a shortcut and we should fully solve this before introducing possibilities for errors to fail to the code base.

[xardass]

@bkawk In the epic, we read

The generated code is single-use , we never will re-use a shortcode. Not when it expires , and not when the request was canceled.

I suggest that the stakeholders expand on this point that once a shortCode has been used, the API disables it. This would effectively avoid having a user send the same transaction multiple times if he doesn't get succes notification on the first try.

[BvL13]

@kikipluche we need clarification on this or we will start guessing: either we delete the

• to make doing a transaction in Swarm City fool-proof
• to not bother users with blockchain-jargon (public keys etc.)

or we clarify in the description as Xardas describes it for - to make doing a transaction in Swarm City fool-proof

• to not bother users with blockchain-jargon (public keys etc.) we should not use TXHash but rather use another term

[kikipluche]

1. the I in the abstract is the sender, i have changed the word in the description.
2. we don't want to bother users with blockchain jargon all the time, we do feel that at some points it is usefull, for example on the green page, which is a progress page, when there is an actual transaction on the blockchain happening, at that point we do give blockchain related feedback. And when an error occurs, we do talk about a TXhash. People might want to ask other users in a support channel for help, at that point naming the TXhash is the best option, for more experiences users will be able to help and check on etherscan or something. So we are selective in showing blockchain related things. In case of sending we use the shortcode, because it feels way more low-level than a blockchainaddress. And it comes closer to being fool-proof, especially with being on Rinkeby, using the shortcode will ensure users are all on the Rinkeby network. Can you agree to leave the fool-proof and the blockchain-jargon sentences in?

[kikipluche]

@bkawk about the 30 seconds, i understand your hesitation, but can we agree to build the simplest version first, so whatever went wrong, after 30sec the user gets the error page and goes back to the wallet view. When we get feedback when testing that the transaction did go through, but something went wrong in giving back the TXhash, we can iterate on this issue. But for now, we keep it as simple as this.

[bkawk]

I agree with @xardass that we just need that one point expanding on.

@kikipluche I feel the statements we make should be true, or they should be removed

[kingflurkel]

Thank you all for these great comments!

I changed these things:

• to minimize the use of blockchain-jargon
• changed 'publicKey' to address in data:

  data: {
    address: "0xabc...",
    userName: "swarm citizen",
    avatar: <String> // base64
   }

[xardass]

What about the single-use shortcode (see my question above)? Can we understand this as disabling the shortcode once it has been used for a transaction? This would effectively make it foolproof.

[kingflurkel]

@xardass

My suggestion is to change:

• "The generated code is single-use , we never will re-use a shortcode. Not when it expires , and not when the request was canceled." To:
• "The generated code is single-use , we never will re-use a shortcode. Not when it expires , and not when the request was canceled. When the sender sends the signed transaction to the API (replyShortCode), the API will remove the shortcode from the LevelDB." And update the API description for "replyShortCode". Both on return error or result the shortcode will be removed.