StarkWare Provider

⚠️ The StarkWare provider is in alpha

Heads up! The StarkWare provider is currently only available for Ropsten testnet and not feature complete yet.

Getting started

Install authereum@next version:

npm install authereum@next

Instantiate the Authereum SDK and get StarkWare provider:

import Authereum from 'authereum'

const authereum = new Authereum('ropsten')
await authereum.login()

const starkProvider = authereum.getStarkProvider()
const starkKey = await starkProvider.getStarkKey()
console.log(starkKey)

Methods

These are the methods available under the Authereum StarkWare provider:

getStarkKey():Promise<string>

Returns the Stark key.

Arguments:

none

Returns:

Promise<string>: Returns a promise with stark key string.

Example:

const starkKey = await starkProvider.getStarkKey()

getPublicKey():Promise<string>

Returns the Stark public key.

Arguments:

none

Returns:

Promise<string>: Returns a promise with stark public key string.

Example:

const starkPublicKey = await starkProvider.getPublicKey()

setContractAddress(contractAddress):Promise<void>

Sets the StarkEx contract address to use for the provider.

Arguments:

Value	Type	Definition
contractAddress	String	StarkEx contract address

Returns:

Promise<void>

Example:

await starkProvider.setContractAddress('0x5FedCE831BD3Bdb71F938EC26f984c84f40dB477')

getContractAddress():Promise<string>

Returns the StarkEx contract address.

Arguments:

none

Returns:

Promise<string> : Returns a promise with contract address.

Example:

const address = await starkProvider.getContractAddress()

registerUser(ethKey, operatorSignature):Promise<string>

Submits a transaction to register the Stark key.

Arguments:

Value	Type	Definition
ethKey	String	Ethereum EOA and account contract address
operatorSignature	String	Operator signature required for registration

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const ethKey = '0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b'
const operatorSignature = '0xae50f29764c96ff5d1554f1d0605bdb992a62700eb8a0b2ffd711da6d6fd90781dbfbb8918c98c15e9fd6251ad89d55e30c20060cf300b51929129726718b6711c'
const txHash = await starkProvider.registerUser(ethKey, operatorSignature)

depositEth(vaultId, amount, quantum):Promise<string>

Submits a transaction to deposit ETH to vault.

Arguments:

Value	Type	Definition
vaultId	String	Vault ID (e.g. 15)
amount	String	ETH amount to deposit in wei (e.g. 1000000000000000)
quantum	String	Quantum value (e.g. 10)

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const amount = '1000000000000000' // wei
const quantum = '10'
const txHash = await starkProvider.depositEth(vaultId, amount, quantum)

depositErc20(vaultId, amount, quantum, token):Promise<string>

Submits a transaction to deposit ERC20 token to vault.

Arguments:

Value	Type	Definition
vaultId	String	Vault ID (e.g. 15)
amount	String	Token amount to deposit (e.g. if decimals is 6, to deposit 0.42 it would be 420000)
quantum	String	Quantum value (e.g. 1000)
token	String	Token contract address

Returns:

Promise<>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const amount = '420000' 
const quantum = '1000'
const token = '0x0d9c8723b343a8368bebe0b5e89273ff8d712e3c'
const txHash = await starkProvider.depositErc20(vaultId, amount, quantum, token)

depositErc721(vaultId, tokenId, token):Promise<string>

Submits a transaction to deposit ERC721 NFT to vault.

Arguments:

Value	Definition
vaultId	Vault ID (e.g. 15)
tokenId	Token ID (e.g. 452)
token	NFT contract address

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const tokenId = '1234'
const token = '0x6B5E013ba22F08ED46d33Fa6d483Fd60e001262e'
const txHash = await starkProvider.depositErc721(vaultId, tokenId, token)

cancelDeposit(vaultId, assetType):Promise<string>

Submits transaction to cancel deposit.

Arguments:

Value	Type	Definition
assetType	String	Asset type hash
vauldId	String	Vault ID (e.g. 15)

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const assetType = '0x4b744eda38322858d42ba43046badd5bd91e94844c0b7c47a4975d8b5b77b5'
const txHash = await starkProvider.cancelDeposit(vaultId, assetType)

reclaimDeposit(vaultId, assetType):Promise<string>

Submits transaction to reclaim deposit after cancelling deposit.

Arguments:

Value	Type	Definition
assetType	String	Asset type hash
vaultId	String	Vault ID (e.g. 15)

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const assetType = '0x4b744eda38322858d42ba43046badd5bd91e94844c0b7c47a4975d8b5b77b5'
const txHash = await starkProvider.relcaimDeposit(vaultId, assetType)

withdrawEth(quantum, recipient?):Promise<string>

Submits transaction to withdraw ETH from vault.

Arguments:

Value	Type	Definition
quantum	String	Quantum value (e.g. 10)
recipient	String	(Optional) Recipient address

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const recipient = '0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b'
const txHash = await starkProvider.withdrawEth(quantum, recipient)

withdrawErc20(quantum, token, recipient?):Promise<string>

Submits transaction to withdraw ERC20 token from vault.

Arguments:

Value	Type	Definition
quantum	String	Quantum value (e.g. 1000)
token	String	Token contract address
recipient	String	(Optional) Recipient address

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const quantum = '1000'
const token = '0x0d9c8723b343a8368bebe0b5e89273ff8d712e3c'
const recipient = '0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b'
const txHash = await starkProvider.withdrawErc20(quantum, token, recipient)

withdrawErc721(tokenId, token, recipient?):Promise<string>

Submits transaction to withdraw ERC721 NFT from vault.

Arguments:

Value	Type	Definition
tokenId	String	Quantum value (e.g. 1000)
token	String	Token ID (e.g. 452)
recipient	String	(Optional) Recipient address

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const tokenId = '1234'
const token = '0x0d9c8723b343a8368bebe0b5e89273ff8d712e3c'
const recipient = '0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b'
const txHash = await starkProvider.withdrawErc721(tokenId, token, recipient)

fullWithdrawalRequest(vaultId):Promise<string>

Submits transaction to do a request to withdraw all tokens from vault.

Arguments:

Value	Type	Definition
vaultId	String	Vault ID (e.g. 15)

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const txHash = await starkProvider.fullWithdrawalRequest(vaultId)

freezeRequest(vaultId):Promise<string>

Submits transaction to freeze vault.

Arguments:

Value	Type	Definition
vaultId	String	Vault ID (e.g. 15)

Returns:

Promise<string>: Returns a promise with transaction hash.

Example:

const vaultId = '10'
const txHash = await starkProvider.freezeRequest(vaultId)

escape(vaultId, assetType, quantizedAmount):Promise<string>

Submits transaction to request escape from frozen contract.

Arguments:

Value	Type	Definition
vaultId	String	Vault ID (e.g. 15)
assetType	String	Asset type hash
quantizedAmount	String	Quantized amount (e.g. amount / quantum)

Returns:

Promise<string>: Returns a promise with object containing transaction hash.

Example:

const vaultId = '10'
const assetType = '0x4b744eda38322858d42ba43046badd5bd91e94844c0b7c47a4975d8b5b77b5'
const quantizedAmount = '8233298795789816600'
const txHash = await starkProvider.escape(vaultId, assetType, quantizedAmount)

transfer({object}):Promise<string>

Transfer ETH, ERC20, or ERC721 to a stark account. Returns signature.

Arguments:

Object parameters:

Value	Type	Definition
from	TransferParams	Transfer sender params.
to	TransferParams	Transfer recipient params.
asset	Asset	Asset to transfer
amount	String	Amount
nonce	String	Nonce
expirationTimestamp	String	Expiration timestamp
condition	String	(optional) Condition hash (encoded hash of transfer address and fact)
conditionalTransferAddress	String	(optional) Conditional transfer address (not needed if condition hash is set)
conditionalTransferFact	String	(optional) Condition transfer fact (not needed if condition hash is set)

Asset

Value	Type	Definition
type	String	Asset standard (e.g. ETH, ERC20, ERC721)
data	AssetData	Asset data object

AssetData

Value	Type	Definition
quantum	String	Quantum value. Required if asset type is ETH or ERC20
tokenAddress	String	Token address. Required if asset type is ERC20 or ERC721
tokenId	String	Token ID. Required if asset type is ERC721

TransferParams

Value	Type	Definition
vaultId	String	Vault ID
starkKey	String	Stark key.

Returns:

Promise<string>: Returns a promise with transfer stark signature.

Example:

const starkSignature = await starkProvider.transfer({
    from: {
        vaultId: '10',
    },
    to: {
        vaultId: '15',
        starkKey: '0x04887f4c82218a6d13c6a0a249413e6e53b6910de5f0e6b5d85cfef1db04553b',
    },
    asset: {
        type: 'ETH',
        data: {
            quantum: '1000'
        }
    },
    amount: '1',
    nonce: '2433',
    expirationTimestamp: '1605826942',
    condition: null,
})

transferEth({object}):Promise<string>

Transfer ETH to a stark account. Returns signature.

Arguments:

Object parameters:

Value	Type	Definition
senderVaultId	String	Sender vault ID
receiverVaultId	String	Receiver vault ID
receiverKey	String	Receiver stark key
nonce	String	Nonce
expirationTimestamp	String	Expiration timestamp
condition	String	Conditional transfer hash
quantum	String	Quantum value
amount	String	Amount

Returns:

Promise<string>: Returns a promise with transfer stark signature.

Example:

const starkSignature = await starkProvider.depositEth({
    senderVaultId: '10',
    receiverVaultId: '15',
    receiverKey: '0x04887f4c82218a6d13c6a0a249413e6e53b6910de5f0e6b5d85cfef1db04553b',
    nonce: '2433',
    expirationTimestamp: '1605826942',
    condition: null,
    quantum: '10',
    amount: '1'
})

transferErc20({object}):Promise<string>

Transfer ERC20 token to a stark account. Returns signature.

Arguments:

Object parameters:

Value	Type	Definition
senderVaultId	String	Sender vault ID
receiverVaultId	String	Receiver vault ID
receiverKey	String	Receiver stark key
nonce	String	Nonce
expirationTimestamp	String	Expiration timestamp
condition	String	Conditional transfer hash
assetContractAddress	String	ERC20 contract address
quantum	String	Quantum value
amount	String	Amount

Returns:

Promise<string>: Returns a promise with transfer stark signature.

Example:

const starkSignature = await starkProvider.depositErc20({
    senderVaultId: '10',
    receiverVaultId: '15',
    receiverKey: '0x04887f4c82218a6d13c6a0a249413e6e53b6910de5f0e6b5d85cfef1db04553b',
    nonce: '2433',
    expirationTimestamp: '1605826942',
    condition: null,
    assetContractAddress: '0x0d9c8723b343a8368bebe0b5e89273ff8d712e3c',
    quantum: '10',
    amount: '1'
})

transferErc721({object}):Promise<string>

Transfer ERC721 token to a stark account. Returns signature.

Arguments:

Object parameters:

Value	Type	Definition
senderVaultId	String	Sender vault ID
receiverVaultId	String	Receiver vault ID
receiverKey	String	Receiver stark key
nonce	String	Nonce
expirationTimestamp	String	Expiration timestamp
condition	String	Conditional transfer hash
assetContractAddress	String	ERC721 contract address
tokenId	String	Token ID

Returns:

Promise<string>: Returns a promise with transfer stark signature.

Example:

const starkSignature = await starkProvider.depositErc721({
    senderVaultId: '10',
    receiverVaultId: '15',
    receiverKey: '0x04887f4c82218a6d13c6a0a249413e6e53b6910de5f0e6b5d85cfef1db04553b',
    nonce: '2433',
    expirationTimestamp: '1605826942',
    condition: null,
    assetContractAddress: '0x6B5E013ba22F08ED46d33Fa6d483Fd60e001262e',
    tokenId: '1234'
})

createOrder({object}):Promise<string>

Create a buy or sell limit order. Returns a signature

Arguments:

Object parameters:

Value	Type	Definition
sell	OrderParams	Sell order params
buy	OrderParams	Buy order params.
nonce	String	Nonce
expirationTimestamp	String	Expiration timestamp

OrderParams

Value	Type	Definition
type	String	Asset standard (e.g. ETH, ERC20, ERC721)
data	AssetData	Asset data object
amount	String	Amount
vaultId	String	Vault ID

AssetData

Value	Type	Definition
quantum	String	Quantum value. Required if asset type is ETH or ERC20
tokenAddress	String	Token address. Required if asset type is ERC20 or ERC721
tokenId	String	Token ID. Required if asset type is ERC721

Returns:

Promise<string>:Returns a promise with transfer stark signature.

Example

const starkSignature = await starkProvider.createOrder({
    sell: {
      type: 'ETH',
      data: {
        quantum: '1000'
      },
      amount: '1',
      vaultId: '10'
    },
    buy: {
      type: 'ERC20',
      data: {
        quantum: '10',
        tokenAddress: '0x0d9c8723b343a8368bebe0b5e89273ff8d712e3c'
      },
      amount: '2',
      vaultId: '15'
    },
    nonce: '2433',
    expirationTimestamp: '1605826942'
})

deserializeSignature(signature)

• Returns the r and s values of serialized signature.

Arguments:

Value	Type	Definition
signature	String	Signature hex string

Returns:

Promise<{r, s, recoveryParam?}>: Returns object

Example:

const {r, s} = starkProvider.deserializeSignature(signature)

serializeSignature({r, s, recoveryParam?}):string

• Returns the serialized signature.

Arguments:

Value	Type	Definition
r	String	Signature r value
v	String	Signature v value
recoveryParam	Number	(optional) Recovery parameter value

Returns:

Promise<string>: Returns serialized signature as hex string.

Example:

const signature = starkProvider.serializeSignature({r, s})

send(method, params):Promise<object>

Call StarkWare JSON RPC method with payload.

Arguments:

Value	Type	Definition
method	String	Method name (e.g. stark_transfer)
params	Object | Array	Object or array containing parameters

Returns:

Promise<{id, result}>: Returns promise with object containing response result.

Example:

const method = 'stark_register'
const params = {ethKey, operatorSignature}
const txHash = starkProvider.send(method, params)

getAssetType({assetStandard, assetContractAddress?, quantum?, amount?}):Promise<string>

Returns asset type hash.

TODO

starkSignMessage(msg):Promise<string>

Signs message with stark key.

TODO

signMessage(msg):Promise<string>

Signs message with ethereum key.

TODO

signPersonalMessage(msg):Promise<string>

Signs personal message with ethereum key.

TODO

signTransaction(tx):Promise<string>

Sign transaction.

TODO

sendTransaction(tx):Promise<string>

Send transaction.

TODO

estimateGas(tx):Promise<string>

Estimate gas.

TODO

Additional information

Please refer to the StarkWare JSON RPC specification for example inputs.

You can test out StarkWare methods in the Authereum Ropsten Kitchen Sink.