xtreamly_sdk

• About The Project
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Contact
• Acknowledgments

Xtreamly SDK

The SDK to use Xtreamly
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Xtreamly is an account abstraction service for Web3. Currently, we provide Auth (i.e. SSI) and proxy accounts. You can program your proxy account using lua to automatically do ERC20 transactions on the behalf of your real account. On top of that you can bring your own data and sign up to third party DApps via Xtreamly.`

You can create your own UI based on this SDK. Currently, there is no official one.

(back to top)

Getting Started

You can use this package either in browser or in Node. All the functionality is accessible via three classes: AuthHandler, ProxyHandler and EVMHandlerV5. First two are self-explanatory, the third is a utils class for interaction with Web3 without the need to resort to ethers.js directly.

All the Web3 functionality is based on ethers.js and communication with backend (ICP-Canister) is handled by dfinity-js library.

Note that we're currently in alpha stage. Feel free to report any bug here our via email linked below. Also, any contribution is welcome.

Prerequisites

• node version 16 or a modern browser

Installation

Install the library with your favorite package manager.

• npm

  npm install xtreamly_sdk@latest

• pnpm

  pnpm install xtreamly_sdk@latest

• yarn

  yarn add xtreamly_sdk@latest

Since we're in alpha, we can't gurantee API stability even in major versions

(back to top)

Usage

We provide two distinct functionalities: Auth and Proxy Account. You can use either of those without using the other.

There are three classes you need to use. First two are self explanatory, ProxyHandler for all functionalities related to proxy account and AuthHander for auth and SSI features. The third one is EVMHandler which both said classes use. It's an abstraction layer that wraps ethers.js for our use cases.

Note that all three classes have an async initialize method that should be called before using their methods.

A typical usage consists of three steps:

1. Prepare provider and signer:

To communicate with Web3, you need to have an account (private/public key pair) and a connection to rpc node. These are abstracted in ethers.js as provider and signer objects. These objects are required to initialize EVMHandler and subsequently for all other classes of SDK.

Usually, you either want to use MetaMask or have public/private keys and rpc node (i.e. our Ganache RPC address) in your code. When using MetaMask you need to add our test Ganache network and account to your MetaMask manually.

RPC address and test account:

const testEthNetwork = 'https://test.xtreamly.io:8644'
const testPrivateKey = '0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23b1d';

Now we can create provider using JsonRpcProvier and signer using Wallet from ethers.js since Wallet implements signer interface.

const provider = new ethers.providers.JsonRpcProvider(testEthNetwork);
const wallet = new Wallet(testPrivateKey, provider);

2. Instantiate and initialize EVMHandler class:

Constructor doesn't take any arguments so you just need to instantiate EVMHandler class.

const evmHandler = new EVMHandler()

Initalize method takes either a pair of provider and signer, or an injectedProvider which ought to be provided by MetaMask as window.ethereum object.

1. Using a pair of provided and signer:

await evmHandler.initialize(provider, wallet)

2. Using MetaMask:

await evmHandler.initialize(null, null, window.ethereum);

3. Instantiate and initialize AuthHandler and ProxyHandler classes:

For both use classes, you need to communicate with Xtreamly backend which currently runs as an ICP canister. To do so you'll need to have ICP canister ID as well as ICP network address. For testing purposes use the provided values:

const testCanisterHost = 'http://test.xtreamly.io:4942'
const testCanisterId = 'rrkah-fqaaa-aaaaa-aaaaq-cai'

When our service goes live on ICP mainnet, you wouldn't need the network address

For Auth:

const authHandler = new AuthHandler(evmHandler, testCanisterHost);
await authHandler.initialize();

For Proxy:

const proxyHandler = new ProxyHandler(evmHandler, testCanisterHost);
await proxyHandler.initialize();

4.a Calling Auth Functions

The overall workflow of authentication consists of two paths: Saving data and Retrieving data. In the following schematic you can see the flow and functions needed for each.

Verifiable Credential (or VC for short) encapsulates data itself along metadata and attaches a unique identifier called DID to it for future reference. You don't need to know much about it other than returning / saving the dids when user wants to save data and requesting / loading the dids when you want to retreive data from user.

The created VC would be encrypted and deployed as a smart contract on an EVM blockchain by SDK.

Note that Xtreamly is totally agnostic about the data itself and its format. We just require it to be a string and not being too large since it should be deployed on the blockchain.

1- Saving Data:

• Create Verifiable Credentials for a self presented data:

const testData = 'Test_Data'
const createdVC = await authHandler.createSelfPresentedVCModel(canisterId, testData)

• Deploy the VC and:

const deployedContract = await authHandler.deployVCToEVM(createdVC);

• Inform canister about the deployed contract:

const canister_res = await authHandler.informCanisterAboutDeployedVCContract(canisterId, createdVC.did, deployedContract.address)

2- Retrieving Data:

• Ask canister for data:

The returned data would be exactly the data user had already saved using Xtreamly with provided did. You can't retreive data if you have forgotten its did.

Note that we have to have the did of data we're requesting. Currently, the last two arguments are not used since we're migrating to a new dynamic access control system.

const dataFromCanister = await authHandler.askVCFromCanister(canisterId, createdVC.did, '0x', '0x');

4.b Calling Proxy Functions

Before using proxy account you need to generate one. Since proxy account main function is to automate Web3 interactions, you need to approve the transfer of ERC20 tokens from your real account and also provide enough gas for it. Both these functions are available on ProxyHandler class. Finally, you can (re)program the proxy account by sending a script written in RHAI to Xtreamly.

• Generate proxy account:

const proxyAccount = await proxyHandler.generateProxyAccount(canisterId, wallet.address);

• Approve Transfer of ERC20:

const res = await proxyHandler.approveTransferToProxyAccount(BigInt(10), USDTContractAddress, proxyAccount.address)

• Sending ETH to pay for gas:

const chargeRes = await proxyHandler.chargeEthProxyAccount(proxyAccount, BigInt(10 ** 18));

• Programming proxy account:

Due to a limitation in RHAI implementation, we can't run scripts that have async functions in one go. That is why you need to supply two set of scripts, called Stage1 and Stage2, to sendScriptToProxyAccount function. Some functions need to be called in Stage1 while others in Stage2.

The main function that can only be called in stage1 is balance_erc20. For stage2 it would be transfer_from_erc20. Some functions can be called in either stage, Namely among them is print_to_icp which prints a log in ICP container (You won't see the log, but we see).

There are also important constants to use in script. Chief among them are MY_PROXY_ACCOUNT and STAGE1_RESULT. Remember to return a string from each stage. For more info about proxy scripting refer to the Documentation.

In the sample script below, we're not using stage1, just returning a dummy string. The main action is happening in stage 2 in which we are transferring 5 USDT tokens from our proxy account to a random wallet we just generated.

To identify and program a proxy account, you also need the proxy account token which is saved as a field in ProxyAccount object returned from generateProxyAccount

const USDTContractAddress = '0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab'
const randomWallet = await evmHandler.generateWallet();

const proxyScriptStage1 = `return "OK";`
const proxyScriptStage2 =
`
print_to_icp(MY_PROXY_ACCOUNT);
transfer_from_erc20("${USDTContractAddress}","${wallet.address}", "${randomWallet.address}", 5 , MY_PROXY_ACCOUNT);
return "Stage 2 OK";
`
const proxyScript = new ProxyScript(proxyScriptStage1, proxyScriptStage2);
const res = await proxyHandler.sendScriptToProxyAccount(canisterId, proxyAccount.token, proxyScript);

For more examples, please refer to the Documentation

(back to top)

Roadmap

Our plan is to add these features as fast as possible, possibly in next month. Since we're in Alpha feel free to propose new features.

• [ ] HTTP Outcalls in scripts
• [ ] Dynamic Permissions
• [ ] API Stability
• [ ] Lua Scripting
• [ ] Applets

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

All tests are run using jest. You can run them using:

npm run test

Replace your package manager in case you don't use npm

It's highly recommended to run tests before opening pull request. Also add tests for any new features in your pull request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Xtreamly Team - [e-mail]

Project Link: https://github.com/Xtreamly-Team/Xtreamly_SDK

(back to top)