Session

class session.Session()

CoinShuffle session.

CashShuffle is an extension to CoinShuffle. The CoinShuffle session is the core of the CashShuffle logic. Executes a CoinShuffle session.

Defaults:

• Network operation attempts: 5.
• Network operation timeout: 30 seconds.

session.Session.AnnounceParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• attempts (number) – Maximum gather attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signingKeyPair (Signing) – Participant signing key pair. Assumed ready for use.
• amount (number) – Amount to shuffle in satoshis.
• fee (number) – Participant fee amount in satoshis. The produced transaction will charge this fee to each participant.
• coin (Coin) – Bitcoin Cash network interface.
• outchan (Outchan) – Output message channel.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• log (Logchan) – Logging channel.
• network (bitcore.Network) – Bitcoin Cash network.

session.Session.AnnounceReturn()

Arguments:

• encryptionKeyPair (Crypto) – Own encryption key pair.
• encryptionPublicKeys (Map.<HexString-HexString>) – Other participant encryption public keys. Index participant signing public key. Value participant encryption public key.

session.Session.EquivocationCheckParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• attempts (number) – Maximum gather attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signingKeyPair (Signing) – Participant signing key pair. Assumed ready for use.
• encryptionPublicKeys (Iterable.<HexString>) – Encryption public keys for participants 2 through last ascending in shuffle order.
• outputList (Iterable.<CashAddr>) – Final output list in broadcast message order.
• crypto (Crypto) – Message encryptor. Assumed ready for use.
• outchan (Outchan) – Output message channel.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• log (Logchan) – Logging channel.

session.Session.GatherAnnounceParams()

Arguments:

• attempts (number) – Maximum attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• signingPublicKey (HexString) – Participant signing public key.
• amount (number) – Amount to shuffle in satoshis.
• fee (number) – Participant fee amount in satoshis. The produced transaction will charge this fee to each participant.
• coin (Coin) – Bitcoin Cash network interface.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• network (bitcore.Network) – Bitcoin Cash network.

session.Session.GatherDigestParams()

Arguments:

• attempts (number) – Maximum attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• signingPublicKey (HexString) – Participant signing public key.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.

session.Session.GatherFinalOutputParams()

Arguments:

• attempts (number) – Maximum attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• lastParticipant (HexString) – Signing public key of last participant.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.

session.Session.GatherOutputListParams()

Arguments:

• attempts (number) – Maximum attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• priorParticipant (HexString) – Signing public key of prior participant.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.

session.Session.GatherSignatureParams()

Arguments:

• attempts (number) – Maximum attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• signingPublicKey (HexString) – Participant signing public key.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.

session.Session.MessageAnnounceParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• signingPublicKey (HexString) – Signing public key.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• encryptionPublicKey (HexString) – Public key of encryption key pair.

session.Session.MessageDigestParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• signingPublicKey (HexString) – Signing public key.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• digest (ArrayBuffer) – Digest.

session.Session.MessageFinalOutputParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• signingPublicKey (HexString) – Signing public key.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• outputList (Iterable.<CashAddr>) – List of output addresses.

session.Session.MessageOutputListParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• signingPublicKey (HexString) – Signing public key.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• outputList (Iterable.<Base64>) – List of output address layered encryptions.
• nextParticipant (HexString) – Signing public key of next participant.

session.Session.MessageSignatureParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• signingPublicKey (HexString) – Signing public key.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signatures (Iterable.<Coin~InputSignature>) – Signatures. Map instances work well. Key input index. Value signature.

session.Session.OutputParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• attempts (number) – Maximum gather attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signingKeyPair (Signing) – Participant signing key pair. Assumed ready for use.
• last (boolean) – Whether own client is last in shuffle order.
• priorParticipant (HexString) – Signing public key of prior participant.
• lastParticipant (HexString) – Signing public key of last participant.
• outputAddress (CashAddr) – Own output address.
• crypto (Crypto) – Message encryptor. Assumed ready for use.
• outchan (Outchan) – Output message channel.
• receiver (PhaseReceiver) – Phase message receiver.
• priorReceiver (PhaseReceiver) – Prior phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• log (Logchan) – Logging channel.

session.Session.OutputReturn()

Arguments:

• outputList (Array.<CashAddr>) – Final output list.

session.Session.RunParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• attempts (number) – Maximum gather attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signingKeyPair (Signing) – Participant signing key pair. Assumed ready for use.
• participants (Iterable.<HexString>) – Participant signing public keys. Will be deduplicated and ordered lexicographically by address.
• changeAddresses (Map.<HexString-CashAddr>) – Change addresses. Key participant signing public key. Value change address.
• amount (number) – Amount to shuffle in satoshis.
• fee (number) – Participant fee amount in satoshis. The produced transaction will charge this fee to each participant.
• coin (Coin) – Bitcoin Cash network interface.
• outchan (Outchan) – Output message channel.
• receiver (SessionReceiver) – Session message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• log (Logchan) – Logging channel.
• network (bitcore.Network) – Bitcoin Cash network.

session.Session.RunReturn()

Arguments:

• outputKeyPair (Signing) – Own output key pair.
• transaction (module:cashshuffle/coin~Transaction) – The submitted Bitcoin Cash transaction.

session.Session.ShuffleParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• attempts (number) – Maximum gather attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signingKeyPair (Signing) – Participant signing key pair. Assumed ready for use.
• first (boolean) – Whether own client is first in shuffle order.
• last (boolean) – Whether own client is last in shuffle order.
• priorParticipant (HexString) – Signing public key of prior participant. null for none.
• nextParticipant (HexString) – Signing public key of next participant. null for none.
• encryptionPublicKeys (Iterable.<HexString>) – Subsequent participant encryption public keys in shuffle order. Empty Iterable for none.
• crypto (Crypto) – Message encryptor. Assumed ready for use.
• outchan (Outchan) – Output message channel.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• log (Logchan) – Logging channel.
• network (bitcore.Network) – Bitcoin Cash network to generate output key pair for.

session.Session.ShuffleReturn()

Arguments:

• outputKeyPair (Signing) – Own output key pair.

session.Session.SubmitParams()

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• attempts (number) – Maximum gather attempts. Positive integer.
• timeout (number) – Network operation timeout in milliseconds.
• sessionId (ArrayBuffer) – Session identifier.
• poolNumber (number) – Participant pool number.
• signingKeyPair (Signing) – Participant signing key pair. Assumed ready for use.
• amount (number) – Amount to shuffle in satoshis.
• fee (number) – Participant fee amount in satoshis. The produced transaction will charge this fee to each participant.
• inputAddresses (Map.<HexString-CashAddr>) – Input addresses. Key participant signing public key. Value input address.
• outputAddresses (Iterable.<CashAddr>) – Output addresses.
• changeAddresses (Map.<HexString-CashAddr>) – Change addresses. Key participant signing public key. Value change address.
• coin (Coin) – Bitcoin Cash network interface.
• outchan (Outchan) – Output message channel.
• receiver (PhaseReceiver) – Phase message receiver.
• discarder (Receiver) – Receiver to discard messages to.
• log (Logchan) – Logging channel.
• network (bitcore.Network) – Bitcoin Cash network.

session.Session.SubmitReturn()

Arguments:

• transaction (module:cashshuffle/coin~Transaction) – The submitted Bitcoin Cash transaction.

session.Session.affix(packet, signature, protocol)

Affix signature to packet.

Arguments:

• packet (protocol.Packet) – Packet to affix signature to.
• signature (Base64) – Detached signature.
• protocol (protobufjs.Root) – Protocol definition.

Returns:

protocol.Signed – The signed packet.

session.Session.announce(params)

Arguments:

• params (AnnounceParams) –

Throws:

InadequateError – If any participant has insufficient funds. Message ‘insufficient funds’.

Returns:

AnnounceReturn –

session.Session.broadcastOutput(params)

Arguments:

• params (OutputParams) –

Throws:

• ValueError – If any output list item decryption fails. Message ‘decryption failure’.
• ValueError – If output list contains duplicates. Message ‘output list duplicates’.
• ValueError – If own output address not in final output list. Message ‘output missing’.

Returns:

OutputReturn –

session.Session.checkEquivocation(params)

Arguments:

• params (EquivocationCheckParams) –

Throws:

ValueError – If equivocation is detected. Message ‘equivocation’.

session.Session.decryptOutputList(encryptedOutputList, crypto)

Decrypt output list.

Arguments:

• encryptedOutputList (Array.<Base64>) – List of output address layered encryptions.
• crypto (Crypto) – Message encryptor. Assumed ready for use.

Throws:

• ValueError – If any item decryption fails. Message ‘decryption failure’.
• ValueError – If output list contains duplicates. Message ‘output list duplicates’.

Returns:

Array.<string> – Decrypted output list in same order.

session.Session.encryptLayered(crypto, message, encryptionPublicKeys, network=<mainnet>)

Perform layered encryption of message.

Encrypts recursively for the provided public keys in the provided order. Each cryptogram is encrypted as a Base64 value. Final result is a Base64 value.

Arguments:

• crypto (Crypto) – Message encryptor. Assumed ready for use.
• message (string) – Message to encrypt.
• encryptionPublicKeys (Iterable.<HexString>) – Public keys to encrypt for in encryption order. Minimum 1 item.
• network (bitcore.Network) – Bitcoin Cash network.

Throws:

MissingValueError – If encryption public keys is empty.

Returns:

Base64 – The final cryptogram.

session.Session.gatherAnnounce(params)

Gather announce messages from other participants.

Validates each received message. Verifies sufficient funds for each valid message.

Makes repeated attempts until max attempts exhausted or a network timeout expires. An invalid message causes an additional attempt for a message from that participant. Insufficient funds for any participant fails the entire process.

Arguments:

• params (GatherAnnounceParams) –

Throws:

• ExhaustionError – If attempts are exhausted without success.
• TimeoutError – If wait for message times out.
• InadequateError – If any participant has insufficient funds.

Returns:

Map.<HexString, object> – Announce messages from all other participants. Index participant public key. Value packet as object.

session.Session.gatherDigest(params)

Gather digest messages from other participants.

Validates each received message.

Arguments:

• params (GatherDigestParams) –

Throws:

• ExhaustionError – If attempts are exhausted without success.
• TimeoutError – If wait for message times out.

Returns:

Map.<HexString, object> – Digest messages from all other participants. Index participant public key. Value packet as object.

session.Session.gatherFinalOutput(params)

Gather final output list message from last participant.

Arguments:

• params (GatherFinalOutputParams) –

Throws:

• ExhaustionError – If attempts are exhausted without success.
• TimeoutError – If wait for message times out.

Returns:

object – protocol.Packet portion of final output list message as object.

session.Session.gatherOutputList(params)

Gather output list message from prior participant.

Arguments:

• params (GatherOutputListParams) –

Throws:

• ExhaustionError – If attempts are exhausted without success.
• TimeoutError – If wait for message times out.

Returns:

object – protocol.Packet portion of output list message as object.

session.Session.gatherSignature(params)

Gather signature messages from other participants.

Validates each received message.

Arguments:

• params (GatherDigestParams) –

Throws:

• ExhaustionError – If attempts are exhausted without success.
• TimeoutError – If wait for message times out.

Returns:

Map.<HexString, object> – Signature messages from all other participants. Index participant public key. Value packet as object.

session.Session.messageAnnounce(params)

Construct announce message.

Arguments:

• params (MessageAnnounceParams) –

Returns:

protocol.Packet – Unsigned announce message.

session.Session.messageDigest(params)

Construct digest message.

Digest is in the packet.message.hash.hash field.

Arguments:

• params (MessageDigestParams) –

Returns:

protocol.Packet – Unsigned digest message.

session.Session.messageFinalOutput(params)

Construct final output list message.

Output list is encoded in a single string. Items are delimited with ampersand &. Encoded value is in the packet.message.str field.

Arguments:

• params (MessageFinalOutputParams) –

Returns:

protocol.Packet – Unsigned final output list message.

session.Session.messageOutputList(params)

Construct output list message.

Output list is encoded in a single string. Items are delimited with ampersand &. Encoded value is in the packet.message.str field.

Arguments:

• params (MessageOutputListParams) –

Returns:

protocol.Packet – Unsigned output list message.

session.Session.messageSignature(params)

Construct signature message.

Signatures are in the packet.message.signatures repeated field.

Arguments:

• params (MessageSignatureParams) –

Returns:

protocol.Packet – Unisnged signature message.

session.Session.orderParticipants(participants, network=<mainnet>)

Order participants.

Deduplicates provided participants list. Orders list lexicographically by address.

Arguments:

• participants (Iterable.<HexString>) – Participant signing public keys.
• network (bitcore.Network) – Bitcoin Cash network.

Returns:

Array.<HexString> – Ordered participants list.

session.Session.packageSignedPacket(protocol, signedPacket)

Package a protocol.Signed into a unary protocol.Packets.

Arguments:

• protocol (protobufjs.Root) – Protocol definition.
• signedPacket (protocol.Signed) – Signed packet instance.

Returns:

protocol.Packets – Unary packets list containing the signed packet.

session.Session.run(params)

Arguments:

• params (RunParams) –

Throws:

• NotImplementedError – For any event that should enter blame phase. Message ‘blame’.
• MissingValueError – If participants list does not contain own signing public key. Message ‘own key in participants list’.

Returns:

RunReturn –

session.Session.shuffle(params)

Arguments:

• params (ShuffleParams) –

Throws:

• ValueError – If any output list item decryption fails. Message ‘decryption failure’.
• ValueError – If output list contains duplicates. Message ‘output list duplicates’.

Returns:

ShuffleReturn –

session.Session.sign(signingKeyPair, message, type)

Sign a protocol message.

Arguments:

• signingKeyPair (Signing) – Key pair to sign with. Assumed ready for use.
• message (protobufjs.Message) – Protocol message. Any message type from protocol definition.
• type (protobufjs.Type) – Protocol message type. Used to encode.

Returns:

Base64 – Detached message signature.

session.Session.submit(params)

Arguments:

• params (SubmitParams) –

Throws:

• ValueError – If any received signature is invalid. Message ‘invalid signature’.
• InadequateError – If any other participant input now shows insufficient funds. Message ‘insufficient funds’.

Returns:

SubmitReturn –