webfunds.sox
Class Token

java.lang.Object
  |
  +--webfunds.sox.Encodable
        |
        +--webfunds.sox.Token

Direct Known Subclasses:

RandomToken

public abstract class Token

extends Encodable

This class represents a token (a.k.a. coin). Token objects are usually created by means of a Withdrawal protocol between client and mint-capable SOXServer. They might go through several phases, being potentially: proto signed blinded spent which may or may not be exclusive.

See Also:

Serialized Form

Field Summary
protected  long	expiry           Tokens commonly come from a batch that is identified with a series label or an expiry date.
protected  int	log           The quantity of the item that this token represents.
protected  byte[]	series
protected  byte[]	sig           The signature on the token (generally made by the mint according to the protocol).
protected  int	state           The state that the token is in (generally made by the mint according to the protocol).
protected  int	subversion           The version of the subclass Token.
static int	TOK_PROTO
static int	TOK_RAW
static int	TOK_RECEIVED
static int	TOK_SETTLED
static int	TOK_SIGNED
static int	TOK_SPENT
static int	TOK_UNBLIND
static int	TOK_VALID
protected  int	type           The type of token of this class See TokenFactory for current definitions.
protected  int	version
static int	VERSION           The version number for this structure: 0: current

 

Constructor Summary

Token(byte[] buf)           Construct a token object from a byte array that was previously returned from the encode() method of a token object.

Token(java.io.InputStream is)           Construct a token object from data in an input stream, where the data was previously returned from the encode() method of a token object.

Token(int type, int subversion, int log)           Create an uninitialised token.

 

Method Summary
void	decode(java.io.InputStream is)           Update this token object with the values from a token encoded as a byte array (such as previously returned from the encode() method of a token object).
void	encode(java.io.OutputStream os)           Encode a token as a byte array, suitable for sending to third parties for depositing.
boolean	equals(java.lang.Object obj)
long	getExpiry()
int	getLog()
long	getQty()           Note (1) that this may be derived information, the real token value may be encoded in the signature key or some other way.
byte[]	getSeries()
byte[]	getSignature()
int	getState()
int	getSubVersion()
int	getType()
abstract  byte[]	getUniqueId()           Get the unique identifier that is used for checking against double-spending.
int	getVersion()
boolean	isProto()
boolean	isRaw()
boolean	isReceived()
boolean	isSettled()
boolean	isSigned()
boolean	isSpent()
boolean	isUnblinded()
void	setState(int state)
abstract  void	sign(java.security.PrivateKey key, byte[] series)           Sign a protocoin.
java.lang.String	toString()
abstract  void	unblind()           Unblind the signed coin, revealing the signed, private coin.
abstract  boolean	verify(java.security.PublicKey key)           Sign a protocoin.
java.lang.String	vString()

 

Methods inherited from class webfunds.sox.Encodable

decode, encode, main, readByteArray, readCertificate, readProperties, readString, writeByteArray, writeCertificate, writeProperties, writeString

 

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

 

Field Detail

VERSION

public static final int VERSION

The version number for this structure: 0: current

version

protected int version

type

protected int type

The type of token of this class See TokenFactory for current definitions.

subversion

protected int subversion

The version of the subclass Token.

state

protected int state

The state that the token is in (generally made by the mint according to the protocol). How it is set and advanced is up to the higher layers. May be ignored, may use the following TOK numbers. Only the low-order single unsigned byte is saved & restored.

TOK_RAW

public static final int TOK_RAW

TOK_PROTO

public static final int TOK_PROTO

TOK_SIGNED

public static final int TOK_SIGNED

TOK_UNBLIND

public static final int TOK_UNBLIND

TOK_RECEIVED

public static final int TOK_RECEIVED

TOK_SPENT

public static final int TOK_SPENT

TOK_SETTLED

public static final int TOK_SETTLED

TOK_VALID

public static final int TOK_VALID

log

protected int log

The quantity of the item that this token represents. Encoded in logarithm - base 2 of the quantity. Log Qty 0 0 1 1 2 2 3 4 4 8 and so forth. -1 could be used for "not stated", meaning it is encoded in the magic parts (by use of certain key, for example).

expiry

protected long expiry

Tokens commonly come from a batch that is identified with a series label or an expiry date. These are interpreted by the subclass, may be ignored.

series

protected byte[] series

sig

protected byte[] sig

The signature on the token (generally made by the mint according to the protocol). How it is made and verified is up to the higher layers. May be ignored (for technical reasons, cannot be null).

Token

public Token(int type,
             int subversion,
             int log)

Create an uninitialised token. Call prototype() with some params to make it a real proto-token.

Parameters:

type - of token, being the blinding or coin scheme

subversion - is the version of the parent coin class

log - the coin size, log base 2 of quantity

Token

public Token(byte[] buf)
      throws SOXPacketException

Construct a token object from a byte array that was previously returned from the encode() method of a token object.

Parameters:

token - the previously encoded token

Token

public Token(java.io.InputStream is)
      throws SOXPacketException

Construct a token object from data in an input stream, where the data was previously returned from the encode() method of a token object.

Parameters:

is - the input stream from which to read the token data

getVersion

public final int getVersion()

getType

public int getType()

getSubVersion

public int getSubVersion()

getState

public int getState()

setState

public void setState(int state)

isRaw

public boolean isRaw()

isProto

public boolean isProto()

isSigned

public boolean isSigned()

isUnblinded

public boolean isUnblinded()

isReceived

public boolean isReceived()

isSpent

public boolean isSpent()

isSettled

public boolean isSettled()

getLog

public int getLog()

getQty

public long getQty()

Note (1) that this may be derived information, the real token value may be encoded in the signature key or some other way. Note (2) that the unit of account is not encoded within the token, the higher layer code should remember that. See Payments for the encoded Item (a.k.a. Ricardian Contract).

Returns:

quantity of the item that this token represents, being 0 - n representing which bit, or -1 if "not so encoded"

getExpiry

public long getExpiry()

getSeries

public byte[] getSeries()

getSignature

public byte[] getSignature()

Returns:

the signature on the token (never null)

sign

public abstract void sign(java.security.PrivateKey key,
                          byte[] series)
                   throws java.security.KeyException

Sign a protocoin. Alternative to expressing expiry is to set a series.

Parameters:

series - is a string identifying batch

key - is the signing key of the mint

verify

public abstract boolean verify(java.security.PublicKey key)
                        throws java.security.KeyException

Sign a protocoin. Normally called by client & server to check the coin is signed, matched pair with sign() so it can be a standardised call.

Parameters:

key - is the signer's public key (of the mint)

getUniqueId

public abstract byte[] getUniqueId()

Get the unique identifier that is used for checking against double-spending. Normally called by server on depositing. Only makes sense if in state TOK_SIGNED or later.

Parameters:

key - is the signer's public key (of the mint)

unblind

public abstract void unblind()

Unblind the signed coin, revealing the signed, private coin. Normally called by client, no standard paramaters.

decode

public void decode(java.io.InputStream is)
            throws java.io.IOException,
                   SOXPacketException

Update this token object with the values from a token encoded as a byte array (such as previously returned from the encode() method of a token object).

Overrides:

decode in class Encodable

Parameters:

token - the previosly encoded token

encode

public void encode(java.io.OutputStream os)
            throws java.io.IOException

Encode a token as a byte array, suitable for sending to third parties for depositing. If the signature is not present, an unsigned token will be encoded.

Overrides:

encode in class Encodable

Returns:

byte[] the token in encoded form

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

vString

public java.lang.String vString()

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object