\chapter{Implementation}
The Free Haven Trust Module is a library of code accessed by the Haven
Module.  Because it acts as the information repository for the Haven
module, it makes sense to offload its logging and querying needs to a
relational database backend.  Such a backend can be easily shared with
the Communications Module, ensuring coordination of keys and reply
blocks.  It also makes sense to store metadata about shares in the
database, while leaving the shares themselves in a traditional
file-system.  Appropriate tables for the trust portion can be described
in SQL as shown in Figure \ref{fig:sql}.

\begin{figure}
\begin{verbatim}
create table nodes (
    id              integer unique,
    key             varchar(4000),
    replyblock      varchar(8000),
    trust           integer,
    confidence      integer,
    metatrust       integer,
    metaconfidence  integer
)

create table trades (
    source_node     integer references nodes,
    dest_node       integer references nodes,
    receipt         varchar(4000),
    given_keyhash   varchar(512) primary key,
    given_size_k    integer,
    given_exp       date,
    taken_keyhash   varchar(512) primary key,
    taken_size_k    integer,
    taken_exp       date,
    timestamp       date,
    expired         integer
)	

create table referrals (
    target_id       integer references nodes,
    referrer_id     integer references nodes,
    trust           integer,
    confidence      integer,
    metatrust       integer,
    metaconfidence  integer
)

\end{verbatim}
\caption{SQL Table Descriptions}
\label{fig:sql}
\end{figure}

Of particular note, the \texttt{trades.receipt} data is duplicated in
the other fields.  The receipt itself needs to be there for
rebroadcast in case of betrayal, and for its signature.  The other
fields have been extracted from it for quick and easy access.

Based on user configuration and the above-mentioned database, the
trust module supports the following API:

\begin{description}
\item[\texttt{inform\_trustdb(struct tag\_t *tag\_list)}]{Takes in a
parsed XML referral and adds it to the \texttt{referrals} database.
See the ``Interpreting Referrals'' section below for more
information.}

\item[\texttt{trust\_find\_trade\_host(char *target\_host, char
*desc)}]{This call gives the trust db great freedom of action: the
result should be to find a host we wish to trade with, then write its
key into \texttt{target\_host} and a description of a share it might
want into \texttt{desc}.  This last is obtained from the sharedb once
we have selected a host.  In the initial implementation, the choice of
host is random, but weighted towards those with low confidence.}

\item[\texttt{trust\_find\_trade\_host\_by\_share(char *target\_host, const
char *share)}]{Given a share description \texttt{share}, we find all
the hosts which we'd trust to hold it, then select randomly among
them, weighted towards those with high confidence.}

\item[\texttt{trust\_find\_desc\_for\_host(char *desc, char *target\_host,
char *share)}]{This call writes a share description into \texttt{desc}
which we are willing to receive from \texttt{target\_host}.  In the
initial implementation, this simply describes the limits of our trust
of them.}

\item[\texttt{trust\_accept\_share\_phase\_one(struct tag\_t *tag\_list)
}]{In the initial implementation, this call checks on the trust of the
offering node, to see if we're likely to be comfortable trading an
equivalent share to them.}

\item[\texttt{initialize\_trust\_module(), close\_trustdb()}]{These are
simple initializers which deal with opening a connection to the
database and reading in the configuration file.}

\end{description}

The two functions \texttt{trust\_find\_trade\_host} and
\texttt{trust\_find\_trade\_host\_by\_share} are biased in different
directions with respect to confidence.  The assumption is that the
haven module will call \texttt{trust\_find\_trade\_host} when it wishes
to do trust-building trades and serve the priorities of the trust
system, and call \texttt{trust\_find\_trade\_host\_by\_share} when it
wishes to do safe trades.  In accordance with this assumption, we
trade with low-confidence hosts when offered the opportunity to do so,
and high-confidence hosts when told it's important.

\section{Interpreting Referrals}
When the Trust Module receives a referral of the form [Trust: $T$,
Confidence: $C$, Metatrust: $M$, Metaconf: $F$] targeted at a node
with characteristics [Trust: $t$, Confidence: $c$, Metatrust: $m$,
Metaconf: $f$], it first checks to make sure it has no other referrals
with the same target and referrer --- if it does, those are backed out of the system and replaced with the new referral.

Then we add $((T-t) \times M \div c)$ to $t$, and move $c$ one notch
in the same direction --- that is, if we have increased a positive $t$
or decreased a negative $t$, we increment $c$, otherwise we decrement
$c$.  Then we add $((M-m) \times M \div f)$ to $m$, and move $f$ one
notch in the same direction, as above.

If we do currently agree with the referral ($T=t, M=m$), we do not
change our trust in the target node at all, but instead increment our
metatrust and metaconfidence in the referrer: if that node agrees with
us, it must be worth listening to.

\subsection{Referrals with receipts}
In the case of a referral with a receipt, we proceed somewhat
differently.  We ignore metatrust issues, and instead proceed as if we
had noticed the lapse ourselves: we decrease our trust in the node
which defaulted by the product of the size and the intended duration
of the trade (that is, the difference between the timestamp on the
trade and the expiration date of the share) and increment our
confidence in that trust.

We take no action with regard to the metatrust of the referrer; it was
acting based on obvious information, so we have no reason to believe
it is particularly wise in other matters..

\section{Gaining Trust Independently}
The trust module periodically scans the database, rebuilding trust
information.  It is in this way that expired shares are noticed.  When
a share expires without any sign of having disappeared early, we
increase our trust in the node we traded it to by the product of the
size and the duration of the trade (that is, the difference between
the timestamp on the trade and the expiration date of the share),
increment our confidence in that trust, and mark that trade receipt as
expired.

\section{Losing Trust Independently}
When the Haven Module fails to verify that a buddy share still exists,
it informs the Trust Module.  The respone is the reverse of a
successful trade, above: we decrease our trust in the node which
defaulted by the product of the size and the intended duration of the
trade (that is, the difference between the timestamp on the trade and
the expiration date of the share), increment our confidence in that
trust, and ``squawk.''  

This ``squawk'' takes the form of a broadcast referral about this new
trust data, including a receipt for the trade which landed that share
at the apparantly corrupt host.

\subsection{Disagreement}
When scanning the database as mentioned above, the trust module
notices when it has referrals for a node which are of the opposite
sign from its current trust.  Such referrers have their metatrust
decreased, to indicate that they are either unwise or untrustworthy.