Documentation - AndrewKishino/sotez GitHub Wiki

Table of Contents

Sotez

account

Originate a new account

Parameters

  • paramObject Object The parameters for the origination
    • paramObject.balance number The amount in tez to transfer for the initial balance
    • paramObject.spendable boolean? Whether the keyholder can spend the balance from the new account
    • paramObject.delegatable boolean? Whether the new account is delegatable
    • paramObject.delegate string? The delegate for the new account
    • paramObject.fee number The fee to set for the transaction (optional, default 1420)
    • paramObject.gasLimit number The gas limit to set for the transaction (optional, default 10600)
    • paramObject.storageLimit number The storage limit to set for the transaction (optional, default 257)

Examples

sotez.account({
  balance: 10,
  spendable: true,
  delegatable: true,
  delegate: 'tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4',
}).then(res => console.log(res.operations[0].metadata.operation_result.originated_contracts[0]));

Returns Promise Object containing the injected operation hash

activate

Activate an account

Parameters

  • pkh Object The public key hash of the account
  • secret string The secret to activate the account

Examples

sotez.activate(pkh, secret)
  .then((activateOperation) => console.log(activateOperation));

Returns Promise Object containing the injected operation hash

awaitOperation

Check for the inclusion of an operation in new blocks

Parameters

  • hash string The operation hash to check
  • interval number The interval to check new blocks (optional, default 10)
  • timeout number The time before the operation times out (optional, default 180)

Examples

sotez.awaitOperation('ooYf5iK6EdTx3XfBusgDqS6znACTq5469D1zQSDFNrs5KdTuUGi')
 .then((hash) => console.log(hash));

Returns Promise The hash of the block in which the operation was included

getBaker

Get the baker information for an address

Parameters

  • address string The contract for which to retrieve the baker information

Examples

sotez.getBaker('tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4')
  .then(({
    balance,
    frozen_balance,
    frozen_balance_by_cycle,
    staking_balance,
    delegated_contracts,
    delegated_balance,
    deactivated,
    grace_period,
  }) => console.log(
    balance,
    frozen_balance,
    frozen_balance_by_cycle,
    staking_balance,
    delegated_contracts,
    delegated_balance,
    deactivated,
    grace_period,
  ));

Returns Promise The information of the delegate address

getBalance

Get the balance for a contract

Parameters

  • address string The contract for which to retrieve the balance

Examples

sotez.getBalance('tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4')
  .then(balance => console.log(balance));

Returns Promise The balance of the contract

getBallotList

Ballots casted so far during a voting period

Examples

sotez.getBallotList().then(ballotList => console.log(ballotList));

Returns Promise Ballots casted so far during a voting period

getBallots

Sum of ballots casted so far during a voting period

Examples

sotez.getBallots().then(({ yay, nay, pass }) => console.log(yay, nay, pass));

Returns Promise Sum of ballots casted so far during a voting period

getCounter

Get the counter for an contract

Parameters

  • address string The contract for which to retrieve the counter

Examples

sotez.getCounter('tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4')
  .then(counter => console.log(counter));

Returns Promise The counter of a contract, if any

getCurrentPeriod

Current period kind

Examples

sotez.getCurrentPeriod().then(currentPeriod => console.log(currentPeriod));

Returns Promise Current period kind

getCurrentProposal

Current proposal under evaluation

Examples

sotez.getCurrentProposal().then(currentProposal => console.log(currentProposal));

Returns Promise Current proposal under evaluation

getCurrentQuorum

Current expected quorum

Examples

sotez.getCurrentQuorum().then(currentQuorum => console.log(currentQuorum));

Returns Promise Current expected quorum

getDelegate

Get the delegate for a contract

Parameters

  • address string The contract for which to retrieve the delegate

Examples

sotez.getDelegate('tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4')
  .then(delegate => console.log(delegate));

Returns Promise The delegate of a contract, if any

getHead

Get the current head block of the chain

Examples

sotez.getHead().then(head => console.log(head));

Returns Promise The current head block

getHeader

Get the header of the current head

Examples

sotez.getHeader().then(header => console.log(header));

Returns Promise The whole block header

getHeadHash

Get the current head block hash of the chain

Examples

sotez.getHeadHash().then(headHash => console.log(headHash))

Returns Promise The block's hash, its unique identifier

getHeadMetadata

Get the metadata of the current head

Examples

sotez.getHeadMetadata().then(metadata => console.log(metadata));

Returns Promise The head block metadata

getListings

List of delegates with their voting weight, in number of rolls

Examples

sotez.getListings().then(listings => console.log(listings));

Returns Promise The ballots of the current voting period

getManager

Get the manager for a contract

Parameters

  • address string The contract for which to retrieve the manager

Examples

sotez.getManager('tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4')
  .then(({ manager, key }) => console.log(manager, key));

Returns Promise The manager of a contract

getManagerKey

Get the mananger key from the protocol dependent query

Parameters

  • manager (Object | string) The manager key query response
  • protocol string The protocol of the current block

Returns string If manager exists, returns the manager key

getProposals

List of proposals with number of supporters

Examples

sotez.getProposals().then(proposals => {
  console.log(proposals[0][0], proposals[0][1])
  console.log(proposals[1][0], proposals[1][1])
);

Returns Promise List of proposals with number of supporters

importKey

Import a secret key

Parameters

  • key string The secret key
  • passphrase string? The passphrase of the encrypted key
  • email string? The email associated with the fundraiser account

Examples

await sotez.importKey('edskRv6ZnkLQMVustbYHFPNsABu1Js6pEEWyMUFJQTqEZjVCU2WHh8ckcc7YA4uBzPiJjZCsv3pC1NDdV99AnyLzPjSip4uC3y')

importLedger

Import a ledger public key

Parameters

Examples

import TransportNodeHid from "@ledgerhq/hw-transport-node-hid";
await sotez.importLedger(TransportNodeHid, "44'/1729'/0'/0'");

inject

Inject an operation

Parameters

  • opOb Object The operation object
  • sopbytes string The signed operation bytes

Returns Promise Object containing the injected operation hash

loadContract

Looks up a contract and returns an initialized contract

Parameters

  • address Object The contract address

Examples

// Load contract
const contract = await sotez.loadContract('KT1MKm4ynxPSzRjw26jPSJbaMFTqTc4dVPdK');
// List defined contract methods
const { methods } = contract;
// Retrieve contract storage
const storage = await contract.storage();
// Get big map keys
await storage.ledger.get('tz1P1n8LvweoarK3DTPSnAHtiGVRujhvR2vk');
// Determine method schema
await contract.methods.transfer('tz1P1n8LvweoarK3DTPSnAHtiGVRujhvR2vk', 100).schema();
// Send contract operation
await contract.methods.transfer('tz1P1n8LvweoarK3DTPSnAHtiGVRujhvR2vk', 100).send({
  fee: '100000',
  gasLimit: '800000',
  storageLimit: '60000',
});

Returns Promise An initialized contract class

originate

Originate a new contract

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.balance number The amount in tez to transfer for the initial balance
    • paramObject.code (string | Micheline) The code to deploy for the contract
    • paramObject.init (string | Micheline) The initial storage of the contract
    • paramObject.spendable boolean Whether the keyholder can spend the balance from the new account (optional, default false)
    • paramObject.delegatable boolean Whether the new account is delegatable (optional, default false)
    • paramObject.delegate string? The delegate for the new account
    • paramObject.fee number The fee to set for the transaction (optional, default 1420)
    • paramObject.gasLimit number The gas limit to set for the transaction (optional, default 10600)
    • paramObject.storageLimit number The storage limit to set for the transaction (optional, default 257)

Returns Promise Object containing the injected operation hash

packData

Serializes a piece of data to a binary representation

Parameters

  • data (string | Micheline) The data
  • type (string | Micheline) The data type

Returns Promise Serialized data

prepareOperation

Prepares an operation

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.source string? The source address of the operation
    • paramObject.skipCounter boolean Skip incrementing the counter within sotez
    • paramObject.operation (Object | Array) The operation to include in the transaction

Examples

sotez.prepareOperation({
  operation: {
    kind: 'transaction',
    fee: 1420,
    gas_limit: 10600,
    storage_limit: 300,
    amount: 1000,
    destination: 'tz1RvhdZ5pcjD19vCCK9PgZpnmErTba3dsBs',
  }
}).then(({ opbytes, opOb, counter }) => console.log(opbytes, opOb, counter));

Returns Promise Object containing the prepared operation

registerDelegate

Register an account as a delegate

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.fee number The fee to set for the transaction (optional, default 1420)
    • paramObject.gasLimit number The gas limit to set for the transaction (optional, default 10600)
    • paramObject.storageLimit number The storage limit to set for the transaction (optional, default 0)

Returns Promise Object containing the injected operation hash

runCode

Runs or traces code against an input and storage

Parameters

  • code (string | Micheline) Code to run
  • amount number Amount in tez to send
  • input (string | Micheline) Input to run though code
  • storage (string | Micheline) State of storage
  • trace boolean Whether to trace (optional, default false)

Returns Promise Run results

sendOperation

Send an operation

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.operation (Object | Array) The operation to include in the transaction
    • paramObject.source string? The source address of the operation
    • paramObject.skipSignature boolean Use default signature for specific transactions (optional, default false)
    • paramObject.skipPrevalidation boolean Skip prevalidation before injecting operation (optional, default false)

Examples

const operation = {
  kind: 'transaction',
  fee: 1420,
  gas_limit: 10600,
  storage_limit: 300,
  amount: 1000,
  destination: 'tz1RvhdZ5pcjD19vCCK9PgZpnmErTba3dsBs',
};

sotez.sendOperation({ operation }).then(result => console.log(result));

sotez.sendOperation({ operation: [operation, operation] }).then(result => console.log(result));

Returns Promise Object containing the injected operation hash

setDelegate

Set a delegate for an account

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.delegate string? The delegate for the new account
    • paramObject.fee number The fee to set for the transaction (optional, default 1420)
    • paramObject.gasLimit number The gas limit to set for the transaction (optional, default 10600)
    • paramObject.source string? The source address of the operation
    • paramObject.storageLimit number The storage limit to set for the transaction (optional, default 0)

Returns Promise Object containing the injected operation hash

silentInject

Inject an operation without prevalidation

Parameters

  • sopbytes string The signed operation bytes

Returns Promise Object containing the injected operation hash

simulateOperation

Simulate an operation

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.source string? The source address of the operation
    • paramObject.operation (Object | Array) The operation to include in the transaction

Examples

sotez.simulateOperation({
  operation: {
    kind: 'transaction',
    fee: 1420,
    gas_limit: 10600,
    storage_limit: 300,
    amount: 1000,
    destination: 'tz1RvhdZ5pcjD19vCCK9PgZpnmErTba3dsBs',
  },
}).then(result => console.log(result));

Returns Promise The simulated operation result

transfer

Transfer operation

Parameters

  • paramObject Object The parameters for the operation
    • paramObject.to string The address of the recipient
    • paramObject.amount number The amount in tez to transfer for the initial balance
    • paramObject.source string? The source address of the transfer
    • paramObject.fee number The fee to set for the transaction (optional, default 1420)
    • paramObject.parameters string? The parameter for the transaction
    • paramObject.gasLimit number The gas limit to set for the transaction (optional, default 10600)
    • paramObject.storageLimit number The storage limit to set for the transaction (optional, default 300)

Examples

sotez.transfer({
  to: 'tz1RvhdZ5pcjD19vCCK9PgZpnmErTba3dsBs',
  amount: 1000000,
  fee: 1420,
}).then(result => console.log(result));

Returns Promise Object containing the injected operation hash

typecheckCode

Typechecks the provided code

Parameters

  • code (string | Micheline) The code to typecheck
  • gas number The the gas limit

Returns Promise Typecheck result

typecheckData

Typechecks data against a type

Parameters

  • data (string | Micheline) The data
  • type (string | Micheline) The data type

Returns Promise Typecheck result

Module: Key

Creates a key object from a base58 encoded key.

Parameters

  • KeyConstructor Object
    • KeyConstructor.key string? A public or secret key in base58 encoding, or a 15 word bip39 english mnemonic string. Not providing a key will import a ledger public key.
    • KeyConstructor.passphrase string? The passphrase used if the key provided is an encrypted private key or a fundraiser key
    • KeyConstructor.email string? Email used if a fundraiser key is passed
    • KeyConstructor.ledgerPath string Ledger derivation path (optional, default "44'/1729'/0'/0'")
    • KeyConstructor.ledgerCurve string Ledger curve (optional, default tz1)

Examples

import TransportNodeHid from '@ledgerhq/hw-transport-node-hid';

const key = new Key({ key: 'edskRv6ZnkLQMVustbYHFPNsABu1Js6pEEWyMUFJQTqEZjVCU2WHh8ckcc7YA4uBzPiJjZCsv3pC1NDdV99AnyLzPjSip4uC3y' });
await key.ready;

// OR

const key = new Key({
  ledgerTransport: TransportNodeHid,
  ledgerPath: "44'/1729'/0'/1'",
});
await key.ready;

publicKey

Returns the public key

Returns string The public key associated with the private key

publicKeyHash

Returns public key hash for this key

Returns string The public key hash for this key

secretKey

Returns the secret key

Parameters

  • passphrase string? The password used to encrypt the secret key, if applicable

Returns string The secret key associated with this key, if available

sign

Sign a raw sequence of bytes

Parameters

  • bytes string Sequence of bytes, raw format or hexadecimal notation
  • magicBytes Uint8Array The magic bytes for the operation

Returns Promise The signature object

verify

Verify signature

Parameters

  • bytes string Sequance of bytes, raw format or hexadecimal notation
  • signature string A signature in base58 encoding
  • publicKey string A public key

Returns boolean Whether the signature is valid

Module: CryptoUtils

checkAddress

Check the validity of a tezos implicit address (tz1...)

Parameters

  • address string The address to check

Returns boolean Whether address is valid or not

encryptSecretKey

Encrypts a secret key with a passphrase

Parameters

  • key string The secret key
  • passphrase string The passphrase to encrypt the key
  • salt Uint8Array The salt to apply to the encryption

Examples

const encryptedSecretKey = cryptoUtils.encryptSecretKey(
 'p2sk3T9fYpibobxRr7daoPzywLpLAXJVd3bkXpAaqYVtVB37aAp7bU',
 'password',
);

Returns string The encrypted secret key

extractKeys

Extract key pairs from a secret key

Parameters

  • sk string The secret key to extract key pairs from
  • passphrase string? The password used to encrypt the sk

Examples

cryptoUtils.extractKeys('edskRqAF8s2MKKqRMxq53CYYLMnrqvokMyrtmPRFd5H9osc4bFmqKBY119jiiqKQMti2frLAoKGgZSQN3Lc3ybf5sgPUy38e5A')
  .then(({ sk, pk, pkh }) => console.log(sk, pk, pkh));

Returns Promise The extracted key pairs

generateKeys

Generate a new key pair given a mnemonic and passphrase

Parameters

  • mnemonic string The mnemonic seed
  • passphrase string The passphrase used to encrypt the seed

Examples

cryptoUtils.generateKeys('raw peace visual boil prefer rebel anchor right elegant side gossip enroll force salmon between', 'my_password_123')
  .then(({ mnemonic, passphrase, sk, pk, pkh }) => console.log(mnemonic, passphrase, sk, pk, pkh));

Returns Promise The generated key pair

generateMnemonic

Generate a mnemonic

Returns string The 15 word generated mnemonic

sign

Sign bytes

Parameters

  • bytes string The bytes to sign
  • sk string The secret key to sign the bytes with
  • magicBytes Object The magic bytes for the operation
  • password string? The password used to encrypt the sk

Examples

import { magicBytes as magicBytesMap } from 'sotez';

cryptoUtils.sign(opbytes, keys.sk, magicBytesMap.generic)
  .then(({ bytes, magicBytes, sig, prefixSig, sbytes }) => console.log(bytes, magicBytes, sig, prefixSig, sbytes));

Returns Promise The signed bytes

verify

Verify signed bytes

Parameters

  • bytes string The signed bytes
  • sig string The signature of the signed bytes
  • pk string The public key

Returns boolean Whether the signed bytes are valid

Module: Forge

activateAccount

Forge activate_account operation bytes

Parameters

  • opArg Object Operation to forge

Returns string Forged operation bytes

address

Forge address bytes

Parameters

  • addressArg string Address to forge
  • protocol string Current protocol (optional, default '')

Returns string Forged address bytes

ballot

Forge ballot operation bytes

Parameters

  • opArg Object Operation to forge

Returns string Forged operation bytes

bool

Forge boolean

Parameters

  • boolArg boolean Boolean value to convert

Returns string The converted boolean

decodeRawBytes

Decode raw bytes

Parameters

  • bytes string The bytes to decode

Returns Object Decoded raw bytes

delegation

Forge delegation operation bytes

Parameters

  • opArg Object Operation to forge
  • protocol string Current protocol

Returns string Forged operation bytes

doubleBakingEvidence

Forge double_baking_evidence operation bytes

Returns string Forged operation bytes

doubleEndorsementEvidence

Forge double_endorsement_evidence operation bytes

Returns string Forged operation bytes

encodeRawBytes

Encode raw bytes

Parameters

  • input Object The value to encode

Returns string Encoded value as bytes

endorsement

Forge endorsement operation bytes

Parameters

  • opArg Object Operation to forge

Returns string Forged operation bytes

forge

Forge operation bytes

Parameters

  • opOb Object The operation object(s)
  • counter number The current counter for the account
  • protocol string The current block protocol

Examples

forge.forge({
  branch: head.hash,
  contents: [{
    kind: 'transaction',
    source: 'tz1fXdNLZ4jrkjtgJWMcfeNpFDK9mbCBsaV4',
    fee: '50000',
    counter: '31204',
    gas_limit: '10200',
    storage_limit: '0',
    amount: '100000000',
    destination: 'tz1RvhdZ5pcjD19vCCK9PgZpnmErTba3dsBs',
  }],
}, 32847).then(({ opbytes, opOb }) => console.log(opbytes, opOb));

Returns string Forged operation bytes

op

Forge operation bytes

Parameters

  • opArg Object Operation to forge
  • protocol string Current protocol

Returns string Forged operation bytes

origination

Forge origination operation bytes

Parameters

  • opArg Object Operation to forge
  • protocol string Current protocol

Returns string Forged operation bytes

parameters

Forge parameter bytes

Parameters

  • parameter string Script to forge
  • protocol string The current block protocol

Returns string Forged parameter bytes

proposals

Forge proposals operation bytes

Returns string Forged operation bytes

publicKey

Forge public key bytes

Parameters

  • pk number Public key to forge

Returns string Forged public key bytes

publicKeyHash

Forge public key hash bytes

Parameters

  • pkh string Public key hash to forge

Returns string Forged public key hash bytes

reveal

Forge reveal operation bytes

Parameters

  • opArg Object Operation to forge
  • protocol string Current protocol

Returns string Forged operation bytes

script

Forge script bytes

Parameters

  • scriptArg Object Script to forge
    • scriptArg.code string Script code
    • scriptArg.storage string Script storage

Returns string Forged script bytes

seedNonceRevelation

Forge seed_nonce_revelation operation bytes

Parameters

  • opArg Object Operation to forge

Returns string Forged operation bytes

toBytesInt32

Convert bytes from Int32

Parameters

  • num number Number to convert to bytes

Returns Object The converted number

toBytesInt32Hex

Convert hex from Int32

Parameters

  • num number Number to convert to hex

Returns string The converted number

transaction

Forge transaction operation bytes

Parameters

  • opArg Object Operation to forge
  • protocol string Current protocol

Returns string Forged operation bytes

zarith

Forge zarith bytes

Parameters

Returns string Forged zarith bytes

Module: Ledger

getAddress

Get the public key and public key hash from the ledger

Parameters

  • ledgerParams Object The parameters of the getAddress function
    • ledgerParams.transport Object The ledger transport to interface with
    • ledgerParams.path string The ledger path (optional, default 44'/1729'/0'/0')
    • ledgerParams.displayConfirm boolean Whether to display a confirmation the ledger (optional, default false)
    • ledgerParams.curve string The value which defines the curve (tz1=0x00, tz2=0x01, tz3=0x02) (optional, default tz1)

Examples

ledger.getAddress({
  transport: LedgerTransport,
  path = "44'/1729'/0'/0'",
  displayConfirm = true,
  curve = 'tz1',
}).then(({ address, publicKey }) => console.log(address, publicKey));

Returns Promise The public key and public key hash

getVersion

Show the version of the ledger

Parameters

  • transport LedgerTransport The parameters of the signOperation function

Examples

ledger.getVersion()
  .then(({ major, minor, patch, bakingApp }) => console.log(major, minor, patch, bakingApp));

Returns Promise The version info

signOperation

Sign an operation with the ledger

Parameters

  • ledgerParams Object The parameters of the signOperation function
    • ledgerParams.transport Object The ledger transport to interface with
    • ledgerParams.path string The ledger path (optional, default 44'/1729'/0'/0')
    • ledgerParams.rawTxHex boolean The transaction hex for the ledger to sign
    • ledgerParams.curve string The value which defines the curve (tz1=0x00, tz2=0x01, tz3=0x02) (optional, default tz1)
    • ledgerParams.magicBytes Uint8Array The magic bytes for the operation (optional, default '03')

Examples

ledger.signOperation({
  path = "44'/1729'/0'/0'",
  rawTxHex,
  curve = 'tz1',
}).then((signature) => console.log(signature));

Returns Promise The signed operation

Module: Utility

b582int

Convert from base58 to integer

Parameters

Returns string The converted b58 value

b58cdecode

Base58 decode

Parameters

  • enc string The value to decode
  • prefixArg Object The Uint8Array prefix values

Returns Object The decoded base58 value

b58cencode

Base58 encode

Parameters

Returns string The base58 encoded value

buf2hex

Buffer to hex

Parameters

  • buffer Object The buffer to convert to hex

Returns string Converted hex value

encodeExpr

Encodes an expression

Parameters

  • value string The value to encode

Returns string The base58 encoded expression

hex2buf

Hex to Buffer

Parameters

  • hex string The hex to convert to buffer

Returns Object Converted buffer value

hexNonce

Generate a hex nonce

Parameters

  • length number The length of the nonce

Returns string The nonce of the given length

mergebuf

Merge two buffers together

Parameters

Returns Object The merged buffer

mutez

Convert from tez to mutez

Parameters

  • tez number The amount in tez to convert to mutez

Returns string The tez amount converted to mutez

totez

Convert from mutez to tez

Parameters

  • mutez number The amount in mutez to convert to tez

Returns number The mutez amount converted to tez