Stellar Service Part 2: Testing and basic integration

[This post is slightly outdated, but the details are still informative to learn more about Rehive’s Stellar Extension. As a shortcut we recommend that you start by trying out our automated configuration by creating an account here.]

This is the second part of our Stellar setup guide. It will take you through the basics of using the service for accepting deposits, making transactions on a user’s behalf, and some simple integrations. A working Stellar setup and Rehive company are required to continue. You can find part 1 here.

Now let’s get to the fun part! Transacting on the Stellar network.

We will be using both the Rehive browsable API as well as the Stellar Service Swagger API (testnet API) to emulate an integration by a third party. This will be slightly more technical than the previous blog post as it aims to give a brief outline of some key API endpoints that would be used in client integrations (wallets, dashboards, web applications etc).

Creating our new user

Before we dive in, a key concept in the Stellar ecosystem is the use of memos in transactions. A memo is essentially just an extra bit of information that can be attached to a Stellar transaction. This is useful in the case of the Stellar Service where each company has a single deposit address that all users make transactions to. In the service, we need a way to easily identify which deposit belongs to a user. To do this, each user sets a unique memo (username) before they can make a deposit to the company’s warm storage. Once this is done, the user sends funds to the warm storage address and can attach the memo to the Stellar transaction so that the service can correctly allocate funds to them on the Rehive ledger.

Now let’s quickly create a new Rehive user via the browsable API register endpoint. You will be given a JSON object of the user data. Make sure to save the user’s API token. The Stellar service uses the Rehive auth token to authorize the user and admin endpoints.

Next we will be using the Stellar Service Swagger API to set the user’s username and retrieve some deposit data. Browse down until you see PATCH /user/ user_partial_update:

1. Hit the lock symbol on the right and enter: “Token YOUR_USERS_API_TOKEN” in the value input of the modal. Then hit “Authorize”. This sets the “Authorization” header for all subsequent calls.
2. Click “Try it out” which should allow you to edit the PATCH data. Enter a lowercase username for new user. Then hit “Execute”.

The user’s memo is now set!

If you followed part one you should be pretty comfortable with generating a Stellar account and funding it so let’s make another one! This will be used to emulate a user sending funds to your application.

To get a user’s deposit information we simply do a GET on the same user endpoint. This will return basic user information as well as a crypto object containing the deposit address and memo that we need to make a deposit.

Making a deposit as a user

For this part we will emulate being a user using your company. I will be using the Stellar Labs transaction builder to manually build a transaction but any kind of wallet will work as well. If using a wallet you can skip this next section and just send the transaction.

Using the Stellar labs transaction builder

Main form

1. Input the Source account - this is the account we just created for our user.
2. “Fetch next sequence” button will get the latest sequence for the account.
3. Fee can be left blank so it defaults to 100 Stroops (0.00001 lumens).
4. For the memo choose the “Text” option and input the memo for your user that we set earlier.

Operation type

1. Select payment.
2. Set the destination as the deposit address for your company. This is the warm storage account.
3. Select native and put in the amount of XLM to deposit.
4. Hit sign the transaction -> input the user accounts private key.
5. Then finally broadcast the signed transaction to the network using: “Submit to Post Transaction endpoint” button.

For the sake of brevity we will skip over specifics details when it comes to Stellar transactions, as they are not too important for this tutorial. Once the transaction has been submitted we can log into the Rehive dashboard to check if the transaction has been detected and correctly allocated to your new user.

More details can also be viewed on the transaction by going to the Stellar services transactions listing page. Here you can view the transaction hash, a more explicit Stellar response, or the error response the Stellar Service got from Rehive when trying to update the ledger.

If everything went well the user should now have a balance allocated to them for the amount sent through. Next we will use the Stellar Service API to broadcast a Stellar transaction on the user behalf from the company’s hotwallet.

Creating and broadcasting a Stellar transaction

Now that we have a user with a balance, sending a transaction on behalf of the user is much easier as the Rehive service signs and broadcasts the transaction on behalf of the user using the company’s Hotwallet account. To send the transaction, browse down in the swagger API to /transactions/send/. This follows the same process as before with the only fields we care about being amount - which is the lowest denomination - where 1 XLM will be a value of 10000000, and to_reference, which can be a Stellar public address, Rehive user identifier, or email. The email/identifier will force an off-chain transaction to another user in the company (one way to save on fees) and the Stellar public address will broadcast and send an on-chain transaction. Update the fields using the Stellar public address we generated for the user and hit “Execute”. If all was well a transaction id should be returned!

A few things happen under the hood when creating the send transaction:

1. The service deducts the amount from the user balance.
2. The service deducts the fee and transaction amount from the company Hotwallet.
3. If both are successful, it signs and broadcasts the transaction to the Stellar network.

To double check everything worked as expected, navigate to the transaction listing page in the Stellar Service’s management section of the dashboard. There should be a new complete transaction with a transaction hash value. The hash is the Stellar transaction hash which we can use to check the on-chain ledger for more details, using Stellar Labs transaction explorer.

Congrats on following this far! Hopefully this has been insightful into the basics of Stellar transactions as well as using and integrating with the Rehive service! The next part of the series will focus on creating, issuing, and trading assets on the Stellar network via the Rehive service.

Looking to get started? Get a quote here for a white label wallet on Stellar.

You can find more information here:

Rehive Website
Rehive Products
Rehive Docs
Rehive Dashboard
Rehive Wallet