Re: implementations of "XML Voucher: Generic Voucher Language" ?

[Ko Fujimura <fujimura@isl.ntt.co.jp>]

Ian Grigg wrote:
> ...
> > I think some of properties of the contract do not have to be interpreted
> > by the program and they are defined only for clarifying its legal meaning.
> > In case of bond, for example, bond_face, bond_currency, and
> > bond_maturity_date are needed to be processed especially when it is
> > redeemed. But, bond_issue_date and bond_total_issue_number seem to be
> > defined only for clarifying its legal meaning, am I right?
> 
> That's correct - the intention is to let a bond
> writer put in the fields he wants, and guide the important
> fields with conventions.  Obviously, things like face and
> maturity are needed so that calculations can be done.  The
> addition of the issue_date, etc, is simply there to complete
> the full set of data, not because a program can use them.
> 

Thank you very much for information. It's really helpful for considering the properties
of value (or voucher). 

> IMHO, there is no useful meaning to a Ricardian contract
> "conforming" to a particular layout such as that described
> for bonds.  Every bond is different, and there is no good
> reason to make them all the same.  What will happen over
> time is that new bonds will introduce new tags, and software
> vendors will be encouraged to interpret these extra fields
> according to their usefulness.

I agree. It is impossible to develop a specification that covers all types of 
vouchers in the world. I think that the goal of XML voucher is to cover 90%(?)
of vouchers without introducing implementation difficulties.

> 
> (Another thing to bear in mind is that the bonds area, whilst
> the original genesis of the Ricardo project, has not been
> used since the early days.  We've done most of the last 3
> years doing commodity currencies (precious metals) and are
> currently experimenting with shares and national currencies.)
> 
> > I think that we do not have to introduce specific tags for these
> > properties which are not interpreted by the software, since it is
> > sufficient to write them in a plain text in "one" XML element such as
> > <Contract>...</Contract>. I think it can be used as a criteria whether we
> > introduce as an element in XML voucher or not.
> > How do you think this approach?
> 
> Initially that would be fine - experience would guide us as to
> how to develop the inner parts.
> 
> One thing that happened with currency contracts that I didn't
> predict was that a currency issuer added a complete section
> called [conditions] and a lot of fields like conditions_backing,
> conditions_reserves, conditions_audit...  which all specified
> the terms of the contract in those particular areas.

It's good suggestion. I think we should introduce the <Conditions> element for 
that purpose.

> 
> Likewise, a new contract that is being worked on by an issuer
> has added a complete [definitions] section at the very beginning.
> If we were to translate his contract to an XML format, it would
> look like:
> 
> <contract>
>  <definitions>
>   <dollars>
>    [ivan's] dollars are ...
>   </dollars>
>   ...
>  </definitions>

In the current voucher draft, there is a <Description> element. I think the purpose
of <definitions> seems to be similar...

> 
>  <entity>
>   <shortname>...</shortname>
>  </entity>
> 
>  <issue>
>   ...
>  </issue>
> 
>  <currency>
>   <name>[ivan's] dollars</name>
>   <tla>USD</tla>
>   <type>decimal</type>
>   <decimal_power>2</decimal_power>
>   <fraction>c</fraction>
>  </currency>
>  ...
> </contract>
> 

In the current voucher draft, <Title> is introduced for describing the name of the
voucher (incl. currency).

I'm not sure whether <type> is really needed, since other standards, e.g., IOTP, ECML,
FTSC, X9.59, ..., does not has the property, and there is no modern currency that are 
not decimal.

I understand that you introduced <decimal_power> to give the mapping information 
between the amount managed by the account (or SOX protocol) and the unit of the 
currency displayed. This is good idea since underlying system such as VTS does not 
have to care about the unit. Using this mapping information, a wallet system can 
transform it in a human readable form.

In the current voucher draft, I introduced <Value ratio="nnnn"/> syntax for similar
purpose. Using this syntax, Ivan's dollar can be defined as follows:

<Voucher>
  ...
  <Promise>
    <Title>Ivan's dollars</Title>
    <Description>
      Ivan's dollars are ...
    </Description>
    ...
    <Value ratio="0.01" currency="USD" amount="1"/>
    <Conditions>Only valid in Ivan's shops</Conditions>
    ...
  </Promise>
  ...
</Voucher>

I found currency_factor parameter in the Ricardian Contract. I think it is the same 
as the ratio attribute above. By the way, I think that either currency_factor or 
currency_decimal_power is enough for defining the mapping, am I right? If so, why 
you choose currency_decimal_power? I think currency_factor is more flexible.
Sorry for asking a lot. But, your experiences are really helpful for developping the
specification.

I didn't introduce <fraction> in the above. Because, "$0.01" seems to be ok instead of 
"1c" in many cases, and the translation is quite easy in XML using the style sheet. 

> (for example ...)  One thing I'm unsure of is the appropriate form,
> should it be tags everwhere or fields?  E.g., would the following
> be more appropriate:
> 
>  ...
>  <currency name="ivan's dollars" type="decimal" power=2 fraction="c">
>   Ivan's dollars are denominated in dollar units, with a fractional
>   unit of contract of a cent.
>  </currency>

That's fine. But I'm not sure whether the meaning should be written in natural 
language for monetary value, since its semantics is strictly defined using the 
attributes. But, non monetary value this syntax might be more appropriate...

<Voucher>
  ...
  <Promise>
    <Title>Ivan's gold voucher (1mg)</Title>
    <Description>
      This voucher can be exchanged for 1mg of gold.
    </Description>
    ...
    <Merchandise ratio="0.001" unit="g" amount="1">  [or ratio="1" unit="mg"]
      Ivan's gold vouchers are denominated in gram of gold, with a fractional
      unit of a milligram.
    </Merchandise>
    <Conditions>...</Conditions>
    ...
  </Promise>
  ...
</Voucher>

By the way, I'm not sure gold is currency or merchandise :-)

Thank you!!

Ko