#!/usr/bin/perl
#############################################################################
#
# instruct.cgi -- Instructions on how to play FX.
#
#############################################################################

use strict;
use CGI;
require "Common.pl";

my (@content,$data);
my $query = new CGI;
print $query->header;

my $title = "Foresight Exchange Instructions";
my $header = "<A NAME=instruct>Instructions</A>";
$data = <<EOT;
<P>This page describes the general theoretical and operating principles of FX and its interface. We also recommend the <A HREF="tutorial.html#Tutorial">tutorial</A> by Ken Fishkin (fishkin\@parc.xerox.com).</P>
<UL>
<LI><A HREF="#instructgen">General Principles</A></LI>
<LI><A HREF="#instructtrade">Trading Principles</A></LI>
<LI><A HREF="#instructinterface">The Interface</A></LI>
<UL>
<LI><A HREF="#interfacedescribe">Description</A></LI>
</UL>
<LI><A HREF="#instructtrading">Trading</A></LI>
<LI><A HREF="#score">Scoring</A></LI>
<UL>
<LI><A HREF="#networth">Net Worth</A></LI>
<LI><A HREF="#scoreformula">Score</A></LI>
</UL>
<LI><A HREF="#Capitalization">Capitalization</A></LI>
<UL>
<LI><A HREF="#couponvaluation">Value of coupons</A></LI>
</UL>
</UL>
<HR>
<H2><A NAME="instructgen">General Principles</A></H2>
<UL>
<LI>The unit of currency is the 'credibill' (represented by the \$ symbol).</LI>
<LI>Prices are shown as a percentage of the coupon's face value (e.g., 60 = 0.60 credibills = $0.60)</LI>
<LI>For any given claim, the value of a YES coupon plus a NO coupon is always 1.00 credibills. (v(YES) + v(NO) = 1.00)</LI>
<LI>During the course of trading, you will acquire YES or NO coupons (on any given claim in which you have invested).</LI>
<LI>When a claim is closed, the judge determines the value of the coupons and the bank buys back your coupons and pays you according to their judged worth.</LI>
</UL>
<H2><A NAME="instructtrade">Trading Principles</A></H2>
<P>For the examples that follow, assume that for a certain claim the market price on YES coupons is:</P>
<UL>
<LI>Bid (buy) price: $0.20</LI>
<LI>Ask (sell) price: $0.25</LI>
</UL>
<P>The "Ask" price is the current lowest "offer-to-sell" price.<br>
The "Bid" price is the current highest "offer-to-buy" price.</P>
<P>Coupons, like light, have a dual nature. In some cases it is more convenient to talk about YES and NO coupons; in others it is easier just to talk about buying and selling YES coupons.</P>
<P>The two are equivalent, however. Buying NO coupons is exactly like selling YES coupons. Thus, $1.00 - Ask(YES) ($0.75) is the Bid price for NO coupons. Similarly, $0.80 is the Ask price for NO coupons.</P>
<P>The example is typical in that the Bid price is lower than the Ask price. In other words, there is a "spread" -- a gap between the highest Bid and lowest Ask prices. In this example the spread is $0.05. Having a wide spread discourages trading, since orders to buy or sell cannot be fulfilled. It is in the players' interest to narrow it -- doing so also tends to increase a player's net worth.</P>
<P>Narrowing the spread can be done in two ways: a player may submit a higher Bid price; e.g. $0.21. This increases the value of YES coupons, but leaves the values of NO coupons unchanged. Alternately, the player can submit a lower Ask price; e.g. $0.24. This would increase the value of NO coupons from $0.75 to $0.76, but leave the value of YES coupons unchanged.</P>
<P>If a user submits a Bid with a price that matches an Ask order (or an Ask with a price that matches a Bid) a transaction is performed. The server will exchange coupons until there are no more matching Bids and Asks.</P>
<H2><A NAME="instructinterface">The Interface</A></H2>
<H3><A NAME="interfacedescribe">Description</A></H3>
<P>The FX transaction form contains the following information:</P>
<UL>
<LI>A statement of your current financial situation, including your available cash, your net worth, and your score.</LI>
<LI>A user-selected listing of FX claims with their current state information. Each line is composed of:</LI>
<UL>
<LI>The claim symbol. Clicking on the symbol will take you to the claim description.</LI>
<LI>Your current holdings of coupons for that claim. Negative numbers indicate NO coupons.</LI>
<LI>The current Bid price (the highest price at which anyone is willing to buy YES coupons).</LI>
<LI>The current Ask price (the lowest price at which anyone is willing to sell YES coupons).</LI>
<LI>A space to place bid and ask orders (see below).</LI>
<LI>The claim's short description.</LI>
</UL>
<LI>Links to other information sources.</LI>
<LI>A button to create a new claim.</LI>
</UL>
<H2><A NAME="instructtrading">Trading</A></H2>
<P>You can submit orders for more than one claim's coupons at a time. Type your order(s) in the Orders column of the transaction form on the appropriate line(s) and click the 'Submit' button.</P>
<P>FX will update your transaction page when it has registered your orders. If FX trades coupons for you, you will receive e-mail notification.</P>
<P>Order Syntax: <B>(B|S)&lt;quantity&gt;[Y|N][\@&lt;price&gt;][, ...]</B></P>
<P>e.g.</P>
<UL>
<LI>B50\@12 = "Buy 50 YES coupons at $0.12, when available" (immediate if available).</LI>
<LI>B50Y\@12 = "Buy 50 YES coupons at $0.12, when available" (immediate if available).</LI>
<LI>S50N = "Sell 50 NO coupons at best price" (immediate) [BEST PRICE NOT IMPLEMENTED]</LI>
</UL>
<P>As explained in Trading Principles, selling YES coupons is equivalent to buying NO. Thus, s20\@20 = b20N\@80.</P>
<P>Orders are case insensitive.</P>
<P>Multiple orders on a claim must be separated by a comma (and optional whitespace) e.g. "B50\@12, S50".</P>
<P>You may edit existing orders by changing the orders in the Orders column and re-submitting. When you do so you all your existing orders are replaced with the new set. You can cancel an order simply by erasing it from the form and re-submitting (on some browsers you may have change the quantity ordered to zero).</P>
<H2><A NAME="score">Scoring</A></H2>
<H3><A NAME="networth">Net Worth</A></H3>
<P>A player's net worth is defined as the value of all their coupons plus their cash reserves.</P>
<P>The value of YES coupons is assessed at the last trade price for the claim. For example, if a player held 4 YES coupons in a
claim that last traded at a price of \$0.20, her net worth would be \$0.80.</P>
<P>The value of a NO coupon is (1 - last trade price). For example, if a player held 6 NO coupons in the same claim, his net
worth would be \$4.80 (6 * (1 - 0.20)). 
<H3><A NAME="scoreformula">Score</A></H3>
<P>As of December 4, 2005, the score algorithm is:
<pre>
   (Net Worth + Grants Out - Grants In) / Allowance
where:
   Net Worth: is sum of player's cash and value of claim holdings
   Grants Out: is sum of fees paid to create claims
   Grants In: is sum of fees received for judging claims
   Allowance: is sum of allowance payments received.
</pre>
This replaces the old algorithm:
<pre>
   (Net Worth + Grants Out) / (Allowance + Grants In)
</pre>
which had the side-effect of making the score drift to 1.0 if the player created or judged a lot of claims.</P>
<H2><A NAME="Capitalization">Capitalization</A></H2>
<P>The capitalization is the value of the coupons held by various players.
<H3><A NAME="couponvaluation">Value of coupons</A></H3>
<P>YES coupons are worth what the last trade price was. If the last trade price was 80, then that's the
value of YES coupons. This is fair assumption in a "thick" market, in which most traders are "price takers",
placing orders that do not (usually) push the price up or down.  This isn't really true of FX, however;
in thinly-traded claims, the most eligible bid and ask orders may diverge significantly from the
last trade price. But we had to choose some valuation method...
<P>Some claims mention the value of NO coupons, while others do not. NO coupons always pay $1 less whatever the YES coupons were paid. Usually, if the NO coupon redemption value is specifically stated, it is because the claim is not a simple 0 or \$1 payment
<P><A HREF="tutorial.html"><IMG SRC="/\L${FXTP::T_ACRONYM}\E/images/PREVBUT.GIF" ALT="[Previous]" border=0></A> <A HREF="index.html"><IMG SRC="/\L${FXTP::T_ACRONYM}\E/images/TOPBUT.GIF" ALT="[Top]" border=0></A> <A HREF="tips.html"><IMG SRC="/\L${FXTP::T_ACRONYM}\E/images/NEXTBUT.GIF" ALT="[Next]" border=0></A></P>
EOT
push(@content,$data);
&showHtml(8,$title,$header,undef,undef,@content);

#############################################################################
#
# $License:
#
# Copyright (C) Kenneth A. Kittlitz, All Rights Reserved.
# 
# Unless explicitly acquired and licensed from Licensor under a
# separate arrangement, the contents of this file are subject to the 
# Idea Futures Public License ("IFPL") Version 1.0, or subsequent
# versions as allowed by the IFPL, and You may not copy or use this file
# in either source code or executable form, except in compliance with the
# terms and conditions of the IFPL.
# 
# The IFPL V1.0 is identical to the Reciprocal Public License V1.1 as
# published at <http://www.opensource.org/licenses/rpl.php>, with the
# following two changes to term 13.8:
# 
# [start of changes]
# Change 1) Replace:
#    "This License shall be governed by Colorado law provisions..." 
# with:
#    "This License shall be governed by Alberta law provisions...".
# 
# Change 2) Replace:
#    "You further agree that Adams County, Colorado USA is proper venue..."
# with:
#    "You further agree that Alberta, Canada is proper venue...".
# [end of changes]
# 
# All software distributed under the License is provided strictly on
# an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
# IMPLIED, AND KENNETH A. KITTLITZ HEREBY DISCLAIMS ALL SUCH
# WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT,
# OR NON-INFRINGEMENT. See the License for specific language
# governing rights and limitations under the License.
#
# :License$
#
#############################################################################