SDK

An SDK is a JS library that helps to communicate with a relayer. The SDK makes it easy to manage a contract by creating basic contract-calling messages. It uses a private key to sign these messages and send them to the relayer, which propagates them to the network.

Creating an SDK

new UniversalLoginSDK(relayerURL, providerURL, sdkConfig)

Parameters:
  • relayerURL : string - a URL address of a relayer
  • providerURL : string - JSON-RPC URL of an Ethereum node
  • sdkConfig (optional) : object - specific sdk options listed below (each of them is optional):
    • applicationInfo : object - detailed info about application: applicationName, type (e.g. laptop, mobile), logo (image source)
    • paymentOptions : object - specific transaction options: gasLimit, gasPrice, gasToken
    • observedTokensAddresses : array of strings - addresses of tokens used
    • observedCurrencies: array with combination of USD, ETH and DAI - shortcuts of currencies used
    • notice : string - additional info shown on the top of React components e.g. ‘Beta version’
    • executionFactoryTick : number - perdiod of time in miliseconds which factory wait with retry if transaction failed
    • authorizationsObserverTick : number - perdiod of time in miliseconds which last between authorization check
    • balanceObserverTick : number - perdiod of time in miliseconds which last between balance update
    • priceObserverTick : number - perdiod of time in miliseconds which last between price update
Returns:
UniversalLoginSDK instance
Example:
import UniversalLoginSDK from '@unilogin/sdk';

const sdkConfig = {
  applicationInfo: {
    applicationName: 'Universal Login Application',
    type: 'laptop',
    logo: 'http://logo.universallogin.io'
  },
  paymentOptions: {
    gasPrice: 1500000000,
    gasLimit: 2000000,
    gasToken: '0x0000000000000000000000000000000000000000
  },
  observedTokensAddresses: ['0x0000000000000000000000000000000000000000', '0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2'],
  observedCurrencies: ['USD', 'ETH'],
  notice: 'This is beta version',
  executionFactoryTick: 1000,
  authorizationsObserverTick: 1000,
  balanceObserverTick: 1000,
  priceObserverTick: 1000
};

const universalLoginSDK = new UniversalLoginSDK(
  'http://myrelayer.ethworks.io',
  'http://localhost:18545',
  sdkConfig
);
Default sdkConfig:
sdkConfig = {
applicationInfo: {
    applicationName: 'Unknown application',
    logo: 'none',
    type: 'unknown'
  },
  paymentOptions: {
    gasPrice: 10000000000,
    gasLimit: 200000,
    gasToken: '0x0000000000000000000000000000000000000000
  },
  observedTokensAddresses: ['0x0000000000000000000000000000000000000000'],
  observedCurrencies: ['USD', 'DAI', 'ETH'],
  notice: '',
  executionFactoryTick: 1000,
  authorizationsObserverTick: 3000,
  balanceObserverTick: 3000,
  priceObserverTick: 300000
};

getWalletContractAddress(ensName)

gets a wallet contract address by an ENS name

Parameters:
  • ensName : string - an ENS name
Returns:
promise that resolves to address if the ENS name is registered or null if the ENS name is available
Example:
const contractAddress = await sdk.getWalletContractAddress('justyna.my-super-domain.test');

walletContractExist(ensName)

checks if an ENS name is registered.

Parameters:
  • ensName : string - an ENS name
Returns:
promise that resolves to true if the ENS name is registered or false if the ENS name is available
Example:
const walletContractExist = await sdk.walletContractExist('justyna.my-super-domain.test');

Creating a wallet contract

createFutureWallet

sdk.createFutureWallet()

Creates a FutureWallet, which contains all information required to deploy and use a Wallet in the future.

Returns:
promise that resolves to FutureWallet.

FutureWallet contains:

  • privateKey - that will be connected to ContractWallet. The key will be used to sign transactions once the wallet is deployed.

  • contract address - an address under which the wallet will be deployed in the future.

  • waitForBalance - a function that waits for a contract address balance change in a way that will allow the wallet contract to be deployed.

    Returns:

    promise, that resolves (only when the wallet contract balance is changed to satisfy relayer requirements) to {tokenAddress, contractAddress}

  • deploy - a function that requests wallet contract deployment.

    Parameters:
    • ensName : string - a chosen ENS name
    • gasPrice : string - gas price of a deployment transaction
    Returns:

    promise that resolves to the deployed wallet contract address

Example:
const {privateKey, contractAddress, waitForBalance, deploy} = await sdk.createFutureWallet();
await waitForBalance();
await deploy('myname.example-domain.eth');

connect

sdk.connect(contractAddress)

requests adding a new key to a contract.

Parameters:
  • contractAddress : string - an address of the contract to manage a connection
Returns:

promise that resolves to privateKey, where:

  • privateKey - the private key that is requested to add to manage the contract
Example:
const privateKey = sdk.connect('0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA');

denyRequest

sdk.denyRequest(contractAddress, publicKey, privateKey)

removes the request for adding a new key from pending authorizations.

Parameters:
  • contractAddress : string - an address of a contract to remove a request
  • publicKey : string - an address to remove from add requests
  • privateKey : string - a private key to sign a request
Returns:

promise that resolves to publicKey, where:

  • publicKey - an address removed from pending authorisations
Example:
const publicKey = await sdk.denyRequest('0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA', '0xb19Ec9bdC6733Bf0c825FCB6E6Da95518DB80D13');

Creating a deployed wallet

new DeployedWallet(contractAddress, name, privateKey, sdk)

creates the DeployedWallet object

Parameters:
  • contractAddress : string - an address of a contract to remove a request
  • name : string - a name for deployed wallet
  • privateKey : string - a private key to sign a request
  • sdk : object - a UniversalLoginSDK object
Returns:

DeployedWallet instance

Example:

import {DeployedWallet} from '@unilogin/sdk';

const deployedWallet = new DeployedWallet('0x2828282882215356332', 'name.mylogin.eth', '0x1183823828282356343143', sdk);

Transaction execution

execute

deployedWallet.execute(message)

executes any message.

Parameters:
  • message : object - a message that is sent to a contract, includes:
    • from : string - an address of the contract that requests execution
    • to : string - a beneficient of this execution
    • data : string - the data of execution
    • value : string - value of transaction
    • gasToken : string - token address to refund
    • gasPrice : number - price of gas to refund
    • gasLimit : number - limit of gas to refund
Returns:

promise that resolves to the Execution

Example:

const message = {...transferMessage, from: contractAddress, gasToken: ETHER_NATIVE_TOKEN.address, data: '0x'};
const {waitToBeSuccess} = await deployedWallet.execute(message);

Execution contains:

  • messageStatus - a current status of the sent message (learn more)
  • waitToBeMined - a function that returns a promise that resolves to MessageStatus once the transaction enclosed with Message is mined
Example:
const message = {
  from: '0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA',
  to: '0xbA03ea3517ddcD75e38a65EDEB4dD4ae17D52A1A',
  data: '0x0',
  value: '500000000000000000',
  gasToken: '0x9f2990f93694B496F5EAc5822a45f9c642aaDB73',
  gasPrice: 1000000000,
  gasLimit: 1000000
};

await deployedWallet.execute(
  message,
);

In this case contract 0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA sends 0.5 eth to 0xbA03ea3517ddcD75e38a65EDEB4dD4ae17D52A1A.

messageStatus

_images/messageStatus.png
  • required : number - the amount of required signatures to execute the message
  • collectedSignatures : string[] - signatures collected by a relayer
  • totalCollected : number - the amount of collected signatures
  • messageHash : string - hash of the message
  • state : MessageState - one of the message states: AwaitSignatures, Queued, Pending, Error, Success
  • transactionHash (optional) : string - a transaction hash is only possible when the message state is Pending, Success or Error
  • error (optional) : string - only when the message state is Error

sdk.getMessageStatus(messageHash)

requests a message status of a specific message

Parameters:
  • messageHash - a hash of a message
Returns:
promise that resolves to MessageStatus

Managing a wallet contract

addKey

deployedWallet.addKey(publicKey, executionOptions)

adds a key to manage a wallet contract.

Parameters:
  • publicKey : string - a public key to manage the contract
  • executionOptions : object - an optional parameter that includes details of transactions for example gasLimit or gasPrice
Returns:
promise that resolves to the Execution
Example:
const executionOptions = {
  gasToken: '0x850437540FE07d02045f88cAe122Bc66B1BdE957',
  gasPrice: 1000000,
  gasLimit: 150000
};
await deployedWallet.addKey(
  '0x96E8B90685AFD981453803f1aE2f05f8Ebc3cfD0',
  executionOptions,
);

addKeys

deployedWallet.addKey(publicKeys, executionOptions)

adds multiple keys to manage a contract.

Parameters:
  • publicKeys : array of strings - public keys to add
  • executionOptions : object - an optional parameter that includes details of transactions for example gasLimit or gasPrice
Returns:
promise that resolves to the Execution
Example:
const publicKeys = [
  '0x96E8B90685AFD981453803f1aE2f05f8Ebc3cfD0',
  '0xb19Ec9bdC6733Bf0c825FCB6E6Da95518DB80D13'
];
const executionOptions = {
  gasToken: '0x850437540FE07d02045f88cAe122Bc66B1BdE957',
  gasPrice: 1000000,
  gasLimit: 150000
};
await deployedWallet.addKeys(
  publicKeys,
  executionOptions,
);

removeKey

deployedWallet.removeKey(publicKey, executionOptions)

removes a key from a contract.

Parameters:
  • publicKey : string - a public key to remove
  • executionOptions : object - an optional parameter that includes details of transactions for example gasLimit or gasPrice
Returns:
promise that resolves to the Execution
Example
const executionOptions = {
  gasToken: '0x9f2990f93694B496F5EAc5822a45f9c642aaDB73',
  gasPrice: 1000000,
  gasLimit: 150000
};
await deployedWallet.removeKey(
  '0xbA03ea3517ddcD75e38a65EDEB4dD4ae17D52A1A',
  executionOptions
);

Events

Key added and key removed

sdk.start()

Starts listening to blockchain events and fetches supported tokens detials.

sdk.stop()

Stops listening to blockchain events.

sdk.subscribe(eventType, filter, callback)

subscribes KeyAdded or KeyRemoved event.

Parameters:
  • eventType : string - a type of an event, possible event types: KeyAdded, KeyRemoved
  • filter : object - a filter for events, includes:
    • contractAddress : string - an address of a contract to observe
    • key : string - a public key used to subscribe to an event
  • callback
Returns:
event listener
Example:
const filter = {
  contractAddress: '0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA',
  key: '0xbA03ea3517ddcD75e38a65EDEB4dD4ae17D52A1A'
};
const subscription = sdk.subscribe(
  'KeyAdded',
  filter,
  (keyInfo) => {
    console.log(`${keyInfo.key} was added.`);
  }
);

Result

0xbA03ea3517ddcD75e38a65EDEB4dD4ae17D52A1A was added

subscription.remove()

removes subscription

Example:
const subscription = sdk.subscribe(
  'KeyAdded',
  filter,
  (keyInfo) => {
    subscription.remove();
  }
);

Authorisations

sdk.subscribeAuthorisations(walletContractAddress, privateKey, callback)

subscribes AuthorisationChanged event

Parameters:
  • walletContractAddress : string - an address of a contract to observe
  • privateKey : string - a private key used to sign a get authorization request
  • callback
Returns:
unsubscribe function
Example:
const unsubscribe = sdk.subscribe(
  '0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA',
  '0x5c8b9227cd5065c7e3f6b73826b8b42e198c4497f6688e3085d5ab3a6d520e74',
  (authorisations) => {
    console.log(`${authorisations}`);
    unsubscribe();
  }
);

Result

[{deviceInfo:
    {
      ipAddress: '89.67.68.130',
      browser: 'Safari',
      city: 'Warsaw'
    },
  id: 1,
  walletContractAddress: '0xA193E42526F1FEA8C99AF609dcEabf30C1c29fAA',
  key: ''}]