Welcome to the documentation of plasma-utils!¶
Hello and welcome to the documentation of Plasma Group’s plasma-utils!
plasma-utils is the set of core utilities used in the rest of the Plasma Group repositories.
Utilities¶
plasma-utils.utils provides miscellaneous utilities often used when interacting with plasma chains.
const utils = require('plasma-utils').utils
int32ToHex¶
utils.int32ToHex(x)
Converts a 32 byte integer to a hex string.
Parameters¶
x-number: A 32 byte integer.
Returns¶
string: The integer represented as a hex string.
sleep¶
utils.sleep(ms)
Sleeps for a number of milliseconds.
Parameters¶
ms-number: Number of milliseconds to sleep.
Returns¶
Promise: A promise that resolves after the given number of ms.
remove0x¶
utils.remove0x(str)
Removes “0x” from the start of a string, if it’s present.
Parameters¶
str-string: String to modify.
Returns¶
string: The string without a leading “0x”.
add0x¶
utils.add0x(x)
Adds “0x” to the start of a string, if not already present.
Parameters¶
str-string: String to modify.
Returns¶
string: The string with “0x”.
isString¶
utils.isString(str)
Checks if the input value is a string.
Parameters¶
str-any: The thing that might be a string.
Returns¶
boolean: true if the input is a string, false otherwise.
getRandomElement¶
utils.getRandomElement(arr)
Returns a random element from an array.
Parameters¶
arr-Array: An array.
Returns¶
any: A random element from that array.
getRandomAccount¶
utils.getRandomAccount()
Returns a random Ethereum account.
Returns¶
any: The Ethereum account.
sign¶
utils.sign(data, key)
Signs a message with a private key.
Parameters¶
data-string: Message to sign.key-string: Private key to sign with.
Returns¶
string: The signature.
signatureToString¶
utils.signatureToString(signature)
Converts a signature with v,r,s Buffers to a single hex string.
Parameters¶
signature-Object: A signature object.
Returns¶
string: The signature as a hex string.
stringToSignature¶
utils.stringToSignature(signature)
Converts a hex string signature into an object with v,r,s Buffers.
Parameters¶
signature-string: A signature string.
Returns¶
Object: A signature object with v,r,s as Buffers.
getSequentialTxs¶
utils.getSequentialTxs(n, blockNum)
Generates sequential transactions in the same block. Usually used for testing with mass amounts of transactions.
Parameters¶
n-number: Number of transactions to generate.blockNum-number: Block in which the transactions will be included.
Returns¶
Array<SignedTransaction>: An array of SignedTransaction objects.
getRandomTx¶
utils.getRandomTx(blockNum, sender, recipient, numTransfers)
Generates a random transaction. Usually used for testing.
Parameters¶
blockNum-number: Block in which this transaction will be included.sender-string: Address of the sender.recipient-string: Address of the recipient.numTransfers-number: Number of transfers to generate.
Returns¶
UnsignedTransaction: An UnsignedTransaction object.
Logging¶
plasma-utils.logging exposes a few logging helpers.
These helpers make it possible to log messages in different contexts, e.g. in development or production.
API¶
ConsoleLogger¶
Creates a new ConsoleLogger, which simply wraps console.log.
Parameters¶
N/A
Parameters¶
message-String: The message to be logged.
Serialization¶
plasma-utils.serialization provides utilities for encoding and decoding transactions.
It also provides tools for defining your own custom schemas using our encoding scheme.
TransferSchema¶
const TransferSchema = new Schema({
token: {
type: ByteArray,
length: 4,
required: true
},
start: {
type: ByteArray,
length: 12,
required: true
},
end: {
type: ByteArray,
length: 12,
required: true
},
sender: {
type: Address,
required: true
},
recipient: {
type: Address,
required: true
}
})
A Transfer represents a portion of a transaction. Each transaction is composed of one or more Transfer. By allowing a transaction to support more than one transfer, we enable atomic swaps.
SignatureSchema¶
const SignatureSchema = new Schema({
v: {
type: ByteArray,
length: 1,
required: true
},
r: {
type: ByteArray,
length: 32,
required: true
},
s: {
type: ByteArray,
length: 32,
required: true
}
})
A Signature is a simple representation of an ECDSA signature.
UnsignedTransactionSchema¶
const UnsignedTransactionSchema = new Schema({
block: {
type: Number,
length: 4,
required: true
},
transfers: {
type: [TransferSchema]
}
})
An UnsignedTransactionSchema is composed of one or more Transfer objects.
SignedTransactionSchema¶
const SignedTransactionSchema = new Schema({
block: {
type: Number,
length: 4,
required: true
},
transfers: {
type: [TransferSchema]
},
signatures: {
type: [SignatureSchema]
}
})
A SignedTransactionSchema is composed of one or more Transfer objects and a Signature for each Transfer.
Models¶
plasma-utils provides several different “models” that represent the various common data structures we use.
These models implement the schemas that we use in serialization.
It’s pretty simple to import all of the available models:
const utils = require('plasma-utils')
const models = utils.serialization.models
Transfer¶
A Transfer is the basic component of every transaction.
Every transaction has one or more transfers.
const Transfer = models.Transfer
const transfer = new Transfer({
token: 0,
start: 0,
end: 100,
sender: '0x1E3a4a2edec2b3568B5Ad0656ec3b48d9C699dB6',
recipient: '0x8508c8aCA521512D4695eCF6976d2e8D2666a46d'
})
Properties¶
typedStart¶
transfer.typedStart
The “typed” start of the range being transferred.
Calculated by concatenating token and start.
Primarily used for calculating state updates in plasma-core.
Returns¶
BigNum: The typed start.
typedEnd¶
transfer.typedEnd
The “typed” end of the range being transferred.
Calculated by concatenating token and end.
Primarily used for calculating state updates in plasma-core.
Returns¶
BigNum: The typed end.
recipient¶
transfer.recipient
Address of the user receiving the transfer.
Returns¶
string: Recipient address.
UnsignedTransaction¶
An UnsignedTransaction contains transfers and a block number, but no signatures.
const UnsignedTransaction = models.UnsignedTransaction
const unsigned = new UnsignedTransaction({
block: 123,
transfers: [
{
token: 0,
start: 0,
end: 100,
sender: '0x1E3a4a2edec2b3568B5Ad0656ec3b48d9C699dB6',
recipient: '0x8508c8aCA521512D4695eCF6976d2e8D2666a46d'
}
]
})
Properties¶
block¶
unsigned.block
The block in which this transaction was included.
Returns¶
BigNum: The transaction block number.
transfers¶
unsigned.transfers
A list of Transfers that make up this transaction.
Returns¶
Array<Transfer>: A list of transfers.
encoded¶
unsigned.encoded
The hex-encoded version of this transaction.
Returns¶
string: Encoded transaction.
SignedTransaction¶
An SignedTransaction contains transfers, and a block number, and a signature for each transfer.
const SignedTransaction = models.SignedTransaction
const signed = new SignedTransaction({
block: 123,
transfers: [
{
token: 0,
start: 0,
end: 100,
sender: '0x1E3a4a2edec2b3568B5Ad0656ec3b48d9C699dB6',
recipient: '0x8508c8aCA521512D4695eCF6976d2e8D2666a46d'
}
],
signatures: [
{
v: '0x1b',
r: '0xd693b532a80fed6392b428604171fb32fdbf953728a3a7ecc7d4062b1652c042',
s: '0x24e9c602ac800b983b035700a14b23f78a253ab762deab5dc27e3555a750b354'
}
]
})
Properties¶
block¶
signed.block
The block in which this transaction was included.
Returns¶
BigNum: The transaction block number.
transfers¶
signed.transfers
A list of Transfers that make up this transaction.
Returns¶
Array<Transfer>: A list of transfers.
signatures¶
signed.signatures
A list of Signatures on this transaction.
There should be one signature for each transfer, where the signature is from the sender of the transfer.
Returns¶
Array<Signature>: A list of signatures.
encoded¶
signed.encoded
The hex-encoded version of this transaction.
Returns¶
string: Encoded transaction.