core.activity.getLatest

Get the last activities of a user.

core.activity.getLatest
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string Safe address of user
userOptions.limit number pagination page size
userOptions.offset number pagination start index
userOptions.timestamp number show only messages after this time
userOptions.filter symbol optional filter for message types
Returns
Object: List of latest activities

CirclesCore

Base class of CirclesCore.

new CirclesCore(web3: Web3, options: Object)
Parameters
web3 (Web3) instance of Web3
options (Object) global core options
Instance Members
web3
options
CoreError
TransferError
RequestError
ErrorCodes
contracts
utils
activity
organization
safe
token
trust
user

core.organization.isFunded

Returns true if there are enough balance on this Safe address to create an organization account.

core.organization.isFunded
Parameters
account (Object) web3 account instance
userOptions (Object) user arguments
Name Description
userOptions.safeAddress string safe address to check
Returns
boolean: has enough funds

core.organization.deploy

Create a new organization account

core.organization.deploy
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string owner of the organization
Returns
string: transaction hash

core.organization.isOrganization

Find out if address is an organization

core.organization.isOrganization
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string address
Returns
boolean: True if organization

core.organization.prefund

Organizations do not hold their own Token and need to be prefunded with a Circles Token to be functional from the beginning (in case transactions are going through the relayer. This method is a special workaround to create a trust connection to a regular user to then transfer Tokens from that user to the organization.

This method only works if the user and the organization owner are the same as transactions are signed with the same private key.

core.organization.prefund
Parameters
account (Object) web3 account instance
userOptions (Object) user arguments
Name Description
userOptions.from string safe address of user who funds
userOptions.to string safe address of organization
userOptions.value BN funding amount
Returns
string: transaction hash

core.organization.getMembers

Returns a list of organization members.

core.organization.getMembers
Parameters
account (Object) web3 account instance
userOptions (Object) user arguments
Name Description
userOptions.safeAddress string address of the organization
Returns
Array: list of members with connected safes and owner address

core.safe.predictAddress

Predict Safe address.

core.safe.predictAddress
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.nonce number nonce to predict address
Returns
string: Predicted Gnosis Safe address

core.safe.getSafeStatus

Returns status of a Safe in the system. Is it created or already deployed?

core.safe.getSafeStatus
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress number Safe address
Returns
Object: Safe status

core.safe.prepareDeploy

Register a to-be-created Safe in the Relayer and receive a predicted Safe address.

core.safe.prepareDeploy
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.nonce number nonce to predict address
Returns
string: Predicted Gnosis Safe address

core.safe.isFunded

Returns true if there are enough balance on this address to deploy a Safe.

core.safe.isFunded
Parameters
account (Object) web3 account instance
userOptions (Object) user arguments
Name Description
userOptions.safeAddress string safe address to check
Returns
boolean: has enough funds

core.safe.deploy

Requests the relayer to not wait for the Safe deployment task. This might still fail when the Safe is not funded or does not have enough trust connections yet.

core.safe.deploy
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress number to-be-deployed Safe address
Returns
boolean: returns true when successful

core.safe.deployForOrganization

Requests the relayer to deploy a Safe for an organization. The relayer funds the deployment of this Safe when the account is already known and verified / already has a deployed Safe from before.

core.safe.deployForOrganization
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress number to-be-deployed Safe address
Returns
boolean: returns true when successful

core.safe.getAddresses

Finds the Safe addresses of an owner.

core.safe.getAddresses
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.ownerAddress number address of the Safe owner
Returns
string: Safe address

core.safe.getOwners

Returns a list of all owners of the given Gnosis Safe.

core.safe.getOwners
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress number address of the Gnosis Safe
Returns
Array<string>: array of owner addresses

core.safe.addOwner

Add an address as an owner of a given Gnosis Safe.

core.safe.addOwner
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress number address of the Gnosis Safe
userOptions.ownerAddress number owner address to be added
Returns
string: transaction hash

core.safe.removeOwner

Remove owner of a given Gnosis Safe.

core.safe.removeOwner
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress number address of the Gnosis Safe
userOptions.ownerAddress number owner address to be removed
Returns
string: transaction hash

core.token.isFunded

Returns true if there are enough balance on this Safe address to deploy a Token contract.

core.token.isFunded
Parameters
account (Object) web3 account instance
userOptions (Object) user arguments
Name Description
userOptions.safeAddress string safe address to check
Returns
boolean: has enough funds

core.token.checkSendLimit

Returns the direct send limit to a user.

core.token.checkSendLimit
Parameters
account (Object) web3 account instance
userOptions (Object) user arguments
Name Description
userOptions.from string send token from this address
userOptions.to string to this address
Returns
BN: send limit

core.token.deploy

Deploy new Circles Token for a user.

core.token.deploy
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string owner of the Token
Returns
string: transaction hash

core.token.getAddress

Get Token address by passing owner address.

core.token.getAddress
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string address of Token owner
Returns
string: Token address

core.token.listAllTokens

List all available tokens of this user.

core.token.listAllTokens
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string safe address
Returns
Array: list of all tokens with ownerAddress, address and amount

core.token.getBalance

Get summarized balance of all or one Token owned by a user.

core.token.getBalance
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string safe address
userOptions.tokenAddress string optional token address in case only this one should be checked
Returns
BN: current balance

core.token.findTransitiveTransfer

This algorithm makes use of the Ford-Fulkerson method which computes the maximum flow in a trust network between two users. It returns the maximum flow and the transfer steps in the graph for a value (when possible).

This method does not execute any real transactions.

core.token.findTransitiveTransfer
Parameters
account (Object) web3 account instance
userOptions (Object) search arguments
Name Description
userOptions.from string sender Safe address
userOptions.to string receiver Safe address
userOptions.value BN value for transactions path
Returns
Object: maximum possible Circles value and transactions path

core.token.transfer

Transfer Circles from one user to another.

core.token.transfer
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.from string sender address
userOptions.to string receiver address
userOptions.value BN value
userOptions.paymentNote string optional payment note stored in API
Returns
string: transaction hash

core.token.getPaymentNote

Return the payment Note of an transaction from or to the user.

core.token.getPaymentNote
Parameters
account (Object) web3 account instance
userOptions (Object) user options
Name Description
userOptions.transactionHash string hash of transfer transaction
Returns
string: Payment note, null when not given or not allowed

core.token.checkUBIPayout

Return the current value of the pending UBI payout.

core.token.checkUBIPayout
Parameters
account (Object) web3 account instance
userOptions (Object) user options
Name Description
userOptions.safeAddress string address of Token owner
Returns
BN: payout value

core.token.requestUBIPayout

Request a UBI payout.

core.token.requestUBIPayout
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string address of Token owner
Returns
string: Transaction hash

core.trust.isTrusted

Find out if safe address has enough incoming trust connections.

core.trust.isTrusted
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string Safe address of user
userOptions.limit string Incoming trust limit
Returns
Object: Trust state and number of connections

core.trust.getNetwork

Get the current state of a users trust network, containing data to find transfer path between users.

core.trust.getNetwork
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.safeAddress string Safe address of user
Returns
Object: Trust network state

core.trust.addConnection

Give other users possibility to send their Circles to you by giving them your trust.

core.trust.addConnection
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.user string trust receiver / sender
userOptions.canSendTo string trust giver / receiver
userOptions.limitPercentage number trust limit in % for transitive transactions
Returns
string: transaction hash

core.trust.removeConnection

Revoke a trust connection with a user. You don't allow this user to transfer their Token to or through you.

core.trust.removeConnection
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.user string trust receiver / sender
userOptions.canSendTo string trust giver / receiver
Returns
string: transaction hash

core.user.dryRegister

Makes a dry-run registration to check if the username and email are valid.

core.user.dryRegister
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.username string alphanumerical username
userOptions.email string email address
Returns
boolean: Returns true when successful, otherwise throws error

core.user.register

Register a new username and email address and connect it to a Safe address.

core.user.register
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.nonce number nonce which was used to predict address, use it only when Safe was not deployed yet
userOptions.safeAddress string owned Safe address
userOptions.username string alphanumerical username
userOptions.email string email address
Returns
boolean: Returns true when successful

core.user.resolve

Find multiple user entries by Safe address and username.

core.user.resolve
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.addresses Array<string> Array of safe addresses
userOptions.usernames Array<string> Array of usernames
Returns
Array<Object>: List of users

core.user.search

Search for users by username.

core.user.search
Parameters
account (Object) web3 account instance
userOptions (Object) options
Name Description
userOptions.query string Search query
Returns
Array<Object>: List of users

core.utils.matchAddress

Detect an Ethereum address in any string.

core.utils.matchAddress
Parameters
str (string) string
Returns
string: Ethereum address or null

core.utils.toFreckles

Convert to fractional monetary unit of Circles named Freckles.

core.utils.toFreckles
Parameters
value ((string | number)) value in Circles
Returns
string: value in Freckles

core.utils.fromFreckles

Convert from Freckles to Circles number.

core.utils.fromFreckles
Parameters
value ((string | number)) value in Freckles
Returns
number: value in Circles

core.utils.requestRelayer

Send an API request to the Gnosis Relayer.

core.utils.requestRelayer
Parameters
userOptions (Object) request options
Name Description
userOptions.path Array<string> API path as array
userOptions.version number API version 1 or 2
userOptions.method string API request method (GET, POST)
userOptions.data Object data payload

core.utils.requestGraph

Query the Graph Node with GraphQL.

core.utils.requestGraph
Parameters
userOptions (Object) query options
Name Description
userOptions.query string GraphQL query
userOptions.variables Object GraphQL variables

core.utils.listAllTokens

Get a list of all tokens and their current balance a user owns. This can be used to find the right token for a transaction.

core.utils.listAllTokens
Parameters
userOptions (Object) query options
Name Description
userOptions.safeAddress string address of Safe
Returns
Array: List of tokens with current balance and address

core.utils.executeTokenSafeTx

Send Transaction to Relayer and pay with Circles Token.

core.utils.executeTokenSafeTx
Parameters
account (Object) web3 account instance
userOptions (Object) query options
Name Description
userOptions.safeAddress string address of Safe
userOptions.txData Object encoded transaction data
Returns
string: transaction hash

core.utils.executeSafeTx

Send a transaction to the relayer which will be executed by it. The gas costs will be estimated by the relayer before.

core.utils.executeSafeTx
Parameters
account (Object) web3 account instance
userOptions (Object) query options
Name Description
userOptions.safeAddress string address of Safe
userOptions.to string forwarded address (from is the relayer)
userOptions.gasToken string address of ERC20 token
userOptions.txData Object encoded transaction data
userOptions.value number value in Wei
Returns
string: transaction hash

core.utils.requestAPI

Make a request to the Circles server API.

core.utils.requestAPI
Parameters
userOptions (Object) API query options
Name Description
userOptions.path string API route
userOptions.method string HTTP method
userOptions.data Object Request body (JSON)
Returns
Object: API response

core.utils.estimateTransactionCosts

Estimates the total gas fees for a relayer transaction.

core.utils.estimateTransactionCosts
Parameters
account (Object) web3 account instance
userOptions (Object) transaction options
Name Description
userOptions.safeAddress string address of Safe
userOptions.to string forwarded address (from is the relayer)
userOptions.gasToken string address of ERC20 token
userOptions.txData Object encoded transaction data
userOptions.value number value in Wei
Returns
BN: estimated gas fees