The Sequence Unity Embedded Wallet SDK provides full Sequence Embedded Wallet and Indexer integration for your Unity Games, integrated with our own purpose-built for Unity SequenceEthereum library.
https://docs.sequence.xyz/sdk/unity/overview
https://docs.sequence.xyz/guides/jelly-forest-unity-guide/
Unity 2021.3.6f1 or later
- Android
- iOS
- PC standalone -> (Mono builds only when using OpenIdAuthentication -> the platform specific setup requires system commands that don't work on IL2CPP -> see OpenIdAuthentication.PlatformSpecificSetup)
- Mac standalone -> (Mono builds only when using OpenIdAuthentication -> in our testing MacOS doesn't pick up custom URL schemes automatically unless you run some system commands first; these system commands that don't work on IL2CPP -> see OpenIdAuthentication.PlatformSpecificSetup)
- WebGL + WebGPU
As an open source project, we welcome and encourage your contributions!
Please make sure to increment the package version in Packages/Sequence-Unity/package.json according to Semantic Versioning along with your submissions.
The project makes use of Unity's test runner. You can open the test runner window in
Unity by navigating to Window > General > Test Runner.
Many of the tests, specifically those for our custom Ethereum client, make use of a Hardhat-based testchain. This testchain can be found in the root folder of the project - in case you are experiencing issues with it.
Before running tests, boot up the test chain with make start-testchain. You may find that you need to stop (control + c) the testchain and restart it when running the test suite again.
When making large amounts of changes or any changes that may impact builds (assemblies, dependencies, etc.), it is useful to confirm that the SDK still compiles on the targeted platforms. To do this navigate to the top menu and click Sequence Dev > Platform Compile Test. This will build the project, and the currently selected scenes in the build settings, on all targeted platforms. All build errors encountered will be recorded in PlatformCompileTestErrors/<build platform>.txt. The builds will be cleaned up once completed. This test doesn't run any tests against the individual builds; it only confirms that the project builds on a given platform.
It can sometimes be useful to quickly test the project via command line. This can be done without opening Unity or starting the testchain.
Add this line to your ~/.zshrc or ~/.bashrc
export PATH="/Applications/Unity/Hub/Editor/2021.3.6f1/Unity.app/Contents/MacOS:$PATH" - note: this is an example path, the exact path may vary based on your system
Then
source ~/.bashrc or source ~/.zshrc
Then
touch TestResults.xml from the route directory of the project
Run make bootstrap to install dependancies locally that are required for running the testchain.
To run the test please use
make test
This will automatically start the testchain and open Unity to run the tests. When the tests are finished, the testchain and Unity will be shutdown.
The test results can be found in TestResults.xml located in the root directory of the project. The Makefile command will automatically display a summary of the test results.
When a test fails, it is recommended that you open up Unity and test via the usual method.
Note: Please do not run make test while you have the project open in Unity - the tests will not run and you will need to touch TestResults.xml again.
Occasionally, it may be necessary to test the testchain to
a) confirm it is giving the behaviours you expect and
b) to use for comparison with our Unity tests.
We can safely assume that ethers (which we use to test the testchain) works correctly. To test please use make test-testchain. Test output will be in chaintest.out and will also be printed to the terminal. If you need to end the test suite early, use Control+C and make stop.
*Note: if you already have an instance of Unity running, this will open up a new instance of Unity that will terminate upon completion.
Do you have tests that are failing that you don't think should be or were previously passing and you haven't changed anything? Here are a few things to try:
- If you are or were using a debugger, disconnect the debugger from Unity and then reconnect
- Restart the test chain
Control+Candmake start-testchain - Restart Unity
- Also note that since tests on the testchain are being run sequentially, if a prior test fails, it may not have unwound properly and may leave the next test in an unexpected state - causing it to fail.
The SDK comes with a number of samples that can be imported via Samples using the Package Manager. The most important of these is Setup which contains a number of Editor scripts and the SequenceConfig scriptable object resource that need to live in the Assets folder to function correctly with the Unity Editor.
These live inside the Samples~ folder as required by the Package Manager specification. However, the Unity Editor will ignore any folders/files with a '~' character in their name and will not create a .meta file for them or import them. In order to facilitate our development, we create a symbolic link named Samples that points to the Samples~ folder - allowing us to see and interact with our Samples and Setup scripts.
Samples include a set of handful feature boilerplate to get started.
How to create a new Boilerplate:
- Create the scripts inside the
Packages/Sequence Embedded Wallet SDK/Sequence/Samples/Setup/Boilerplates/ - Create a prefab and put it inside the Resources folder in the above directory.
- Create a static function inside
BoilerplateFactory.csto instantiate a new instance of the prefab from Resources. - Add a new
FeatureSelectionButton.csinside theDemoscene and add a uniqueKeyvalue to the component.
The Key value from FeatureSelectionButton.cs allows us to only enable selected features in our WebGL demo.
For example, the url http://localhost:4444/?features=rewards+profile will only enable the Player Profile and Daily Rewards Boilerplates.
If you don't define any feature in the url, all boilerplates are enabled.
The SDK is split into a number of assemblies with different purposes. Each assembly also has a Test assembly or assembly reference containing tests - this way, our tests aren't included in builds.
This contains front-end and example code. Front-end/UI code is considered "example" code for the purposes of this SDK, though it may still be used in production applications.
This contains code related to authentication via Email + OTP, OIDC, or other means.
Defines the SequenceConfig scriptable object and scripts needed to read it. Configuration is done in conjunction with the Sequence Builder.
The integration with our WaaS/Embedded Wallet API. Used to provide users with a seemless and invisible Web3 wallet experience.
This is our custom Ethereum library, purpose-built for Unity.
The integration with our Indexer API. Used to quickly index/read on-chain data.
The integration with our Marketplace API v2 and Swap API. Used to enable secondary marketplace sales of ERC721/1155s.
Our implementation of the Pay product line - supporting credit card based fund onboarding and collectible checkout for both primary and secondary sales. Integrations of payment service providers like Transak and Sardine.
SDK-side extensions to our Sequence Relayer - e.g. transaction queuers.
Universally useful extension methods, helpers, and platform native code used throughout the SDK for a variety of purposes.
The SDK is broken into a number of components with different responsibilities. This section will give an overview of some of the most important components for users and their intended purposes.
IEthClient provides an interface for clients. Clients handle the connection to blockchain networks, making various RPC requests. Any time you wish to query the blockchain or submit a transaction, you will need a client. As a rule of thumb, if a method requires a client, you should expect that you will be making a web request and will need to work with async tasks and be prepared to catch any exceptions that are thrown.
EthWallet implements a standard EOA wallet. A wallet keeps track of its own private/public key pair and address and is responsible for providing its private key to the signer when signing transactions.
A transaction, as implemented in EthTransaction, contains all the data and parameters for an EVM transaction. The object is used for initiating its RLP encoding (transactions must be signed and RLP encoded when submitted). Note that all transactions are encoded with a chain Id included to protect against replay attacks, see EIP-155.
A contract is responsible for creating transactions (for method calls) and messages (for queries) agaisnt it. These transactions are later signed by the wallet + signer and submitted (along with query messages) using a client.
A sample UI scene can be found under Assets > Sequence > SequenceFrontend > Scenes > Demo.unity
This scene contains sample Sequence UI (with integration) for login flow and wallet view, settings, and transaction flow.
The sample Sequence UI is comprised of a few important components.
A UIPage is the base implementation of a "page" in the sample UI. Example pages: LoginPage, TokenInfoPage
It is responsible for opening/closing the page and managing the chosen ITween.
An ITween is an interface for an animation (in/out) that can be applied to a RectTransform (a required component of a UIPage).
Inherriting from UIPage, a UIPanel is the base implementation of a "panel" in the sample UI. Example panels: LoginPanel, WalletPanel
In addition to UIPage responsibilities, UIPanels maintain a stack of UIPages and object[] (open arguments) and are responsible for managing any required event listeners and UI transitions between their child pages (according to Scene inspector heirarchy), including handling the "Back" button.
SequenceSampleUI can be thought of as the "manager" of the sample UI. It holds a reference to all the UIPanels and is responsible for opening them as needed, including at Start(). If you are integrating all or part of the provided sample UI into your project, you may find it more practical to replace SequenceSampleUI with your own UI "manager".
As a Made-With-Unity UI, the sample UI is cross platform and easily customizable.
To make customization even easier, the sample UI comes equipped with a Color Scheme Manager. This monobehaviour script is attached to the SequenceCanvas gameObject. By attaching a ColorScheme scriptable object and clicking the Apply button in the Inspector, the ColorSchemeManager will quickly apply the desired color scheme, allowing for faster UI iterations.
To create a ColorScheme scriptable object, go to Assets > Create > Sequence > Color Scheme. From here, you can give the color scheme a name, move it to the desired directory, and choose your colors.