Skip to main content

​
Overview

Shinami’s Gas Station only supports integration with your app’s backend (no CORS support) for security reasons. This limits exposure of your Gas Station API keys. If these keys are leaked, bad actors have the ability to sponsor transactions from your fund until it has been drained or you disable the key in our dashboard. This guide will help you integrate a connected browser wallet with Shinami Gas Station transaction sponsorship. We show possible integration flow diagrams with links to associated sample code. If you have not already set up a Shinami Gas Station Fund and Access Key, and sent a successful sponsorship request, see our Gas Station tutorial. It’s useful to run the intial example to understand sponsorship before you connect the frontend, and the code repo you clone includes the code for this tutorial as well. Finally, after you review the images and code below, if you get stuck on something and have a question feel free to reach out to us.

​
Examples

​
Sample app overview

We’ve created a sample app that uses the Aptos Labs wallet-adapter-react library and the Shinami TypeScript SDK. It integrates well with Razor Chrome extension wallet out of the box. We’ve included it in our shinamicorp/shinami-examples repo here. It’s not meant as a starter template for a production app (as an example its API endpoints have no authentication mechanism). Instead, it’s meant to show you a very simple working example so you can understand the core concepts involved. It includes a README.md file to help you get it up and running quickly if you want to see a working example.

​
Consider obtaining the user signature pre-sponsorship

You should think about whether building the transaction on the frontend or backend is a better fit for your app. The same goes for where to submit the transaction for execution. All combinations work, as long as you ask for sponsorship from your backend. In general, it’s beneficial to have the user sign the transaction before you ask for a sponsorship. This is because if you ask for a sponsorship and then the user fails to sign, you’ll still pay our small, minimum fee for creating a sponsorship that goes unused. This means that the user will sign against the 0x0 placeholder feePayer address generated when you build a feePayer transaction, and then the transaction you submit will need to have the actual feepayer’s address set (done automatically by our TypeScript SDK).

​
Build and sign on the FE, sponsor and submit on the BE

This example shows how to build and sign a transaction on the frontend, then send it to your backed for Shinami Gas Station sponsorship and submission to a Movement node. Signing is done with a connected browser wallet. Image Movement-Connected-Wallet-BE-sponsor-and-submit-tx Overview of steps The links in the steps below take you to the relevant code locations in our sample React + TypeScript app on GitHub. The key functions in the sample app are connectedWalletTxFEBuildBESubmit on the frontend and sponsorAndSubmitTx on the backend.
  1. Frontend: Build a feePayer transaction (sample code).
  2. Frontend: Obtain the sender’s signature over the transaction (sample code).
  3. Frontend: Send a request to your app’s backend to sponsor and submit the transaction. This request will include serialized versions of the transaction and the sender’s AccountAuthenticator (sample code).
  4. Backend: Send a gas_sponsorAndSubmitSignedTransaction request to Shinami’s Gas Station (with the de-serialized transaction and sender AccountAuthenticator) (sample code).
  5. Shinami: Shinami will sponsor the transaction and then submit it with the sender and feePayer signatures, returning the PendingTransactionResponse to your backend if successful.
  6. Backend: Handle the response as needed.
  7. Backend: Send a response to the frontend (sample code).
  8. Frontend: Handle the response (this is the response to the request in Step 3). In our sample app, we poll a Movement node until it has a record of the transaction and then print the user’s message that was included in the transaction (sample code).

​
Build and sponsor on the BE, sign and submit on the FE

This example shows how to build and sponsor a transaction on your backend, then sign and submit it on your frontend. Signing is done with a connected browser wallet. Image Movement-Connected-Wallet-BE-build-and-sponsor-FE-submit-tx Overview of steps The links in the steps below take you to the relevant code locations in our sample React + TypeScript app on GitHub. The key functions in the sample app are connectedWalletTxBEBuildFESubmit on the FE and buildAndSponsorTx on the BE.
  1. Frontend: Send a request to your app’s backend to build and sponsor a transaction. Include any data from the FE needed to build the transaction. In our case, that’s the sender’s address and the message the user submitted in the form on the page (sample code).
  2. Backend: Build a feePayer transaction (sample code).
  3. Backend: Make a gas_sponsorTransaction request to Shinami’s Gas Station to sponsor the transaction (sample code).
  4. Backend or Frontend: Set the transaction’s feePayerAddress to the feePayer address value returned from the Gas Station sponsorship request (our TypeScript SDK sets this for you automatically and so does not explicitly return it to you). The sender can sign the transaction with either the actual feePayer address or the special 0x0 address assigned when you create a feePayer transaction. However, you must ensure the actual feePayer’s address is set on the transaction before you submit it to the Movement blockchain. If not, you’ll get an INVALID_SIGNATURE error because the feePayer’s signature was over a transaction with the feePayer address but the submitted transaction still has the 0x0 address.
  5. Backend: Return the serialized transaction, feePayer AccountAuthenticator, and (optionally) feePayer’s address to the frontend (sample code).
  6. Frontend: Deserialize the transaction and obtain the sender’s signature over the transaction (sample code).
  7. Frontend: Submit the transaction, along with the sender and (deserialized) feePayer signatures, to a Movement node (sample code).
  8. Frontend: Handle the response (a PendingTransactionResponse if successful). In our sample app, we poll a Movement node until it has a record of the transaction and then print the user’s message that was included in the transaction (sample code).

​
Other flows in our sample app

​
Appendix

​
Common issues

​
INVALID_SIGNATURE error when submitting the transaction

  • Make sure the transaction you’re submitting has been updated to use the feePayer’s address (instead of the 0x0 that gets set when a feePayer transaction is built).

​
Serializing and deserializing

Here are examples of serializing and deserializing key data types you’ll pass between your frontend and backend. Our sample app code does this in context, but they are presented here for quick viewing. Use a separate Serializer and Deserializer for each piece of data you are working it. In the examples below, though, we don’t use a Serializer because we take advantage of the built in ability of the types to serialize into string representation of a BCS-serialized Hex instance. Serialize on one end (BE or FE) 
// AccountAuthenticator
const serializedAccountAuthenticator = authenticator.bcsToHex().toString();
// AccountAddress
const serializedAccountAddress = accountAddress.bcsToHex().toString();
// SimpleTransaction
const serializedSimpleTransaction = simpleTx.bcsToHex().toString();
Deserialize on the other 
import {
  SimpleTransaction, Deserializer, AccountAuthenticator, Hex, AccountAddress
} from "@aptos-labs/ts-sdk";

AccountAuthenticator.deserialize(new Deserializer(
  Hex.fromHexString(serializedAccountAuthenticator).toUint8Array()));

AccountAddress.deserialize(new Deserializer(
  Hex.fromHexString(serializedAccountAddress).toUint8Array()));

SimpleTransaction.deserialize(new Deserializer(
  Hex.fromHexString(serializedSimpleTransaction).toUint8Array()));