diff --git a/establishing.tex b/establishing.tex new file mode 100644 index 0000000..a07a771 --- /dev/null +++ b/establishing.tex @@ -0,0 +1,57 @@ +\subsection{Establishing relationships} +When Alice first introduced Bob to circulex, +she recommended an app, which he downloaded to his phone. +Bob told the app the name he wanted +to be identfied by to his friends, +and the app generated the necessary secrets for +making secure DTLS connections. + +Alice got her computer to display her \emph{participant identity} +as a two-dimensional barcode, +which Bob scanned with his phone's camera. +Bob confirmed to the app that +the particpant identity belonged to Alice, as it purported to do. +Likewise, Bob got his app to +display his participant identity to Alice's webcam, +so that Alice's circulex application knew Bob's identity. + +Alice and Bob then separately instructed their applications that +they trusted each other for up to \num{1000} \nzd. + +Without further intervention from Alice or Bob, +their applications automatically sent a number of messages, +establishing relationships between each other and their relays. + +Alice's participant identity included +Alice's IP address and circulex port, +but Bob was connecting to the internet via +network address translation, +so his app didn't yet know its own public IP address and port. +Bob's app initiated a connection to Alice's computer, +which verified the authenticity of the connection, +thus learning Bob's public IP address and circulex port. +Bob's app then sent a \emph{location request} to Alice's computer, +requesting that it +share that information via a \emph{location report}, which it did. + +The applications then sent each other \emph{invitations}, +informing each other of +their current medium-term circulex public keys, +their requested bandwidth limits (if any), and +their lists of chosen relays. +They also sent each other \emph{statements}, which +informed each other of the credit limits set by their owners, +and any other requested limits on the sizes of transactions. + +Because Bob has only just started using circulex, +his app lists itself as its only relay. +At least three relays are required in order to +participate in transactions, so +Alice's computer sends a \emph{relay offer}, +offering to act as one of Bob's relays +for a certain length of time. +Bob's app assumes that because +Bob trusts Alice with a substantial sum of money, +he also trusts her computer to act as a relay, +so it adds Alice's computer to its internal list of relays, +and will include it in future invitations. diff --git a/operation.tex b/operation.tex index 25fc2f6..28345a1 100644 --- a/operation.tex +++ b/operation.tex @@ -1,11 +1,13 @@ \section{Typical operation} Before going on to the fine details, it's worth getting an overview of the typical operation of the protocol --- which messages are sent, in what order, and what they mean. In the circulex protocol, this can be roughly divided into three phases: establishing relationships, pathfinding for a transaction, and executing the transaction. + +\input{establishing}