polytone 1.0.0

Core interfaces for Polytone Interchain accounts and queries.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

## The Polytone Handshake

## Background

Polytone is a protocol that gives every smart contract an account on
every IBC blockchain. It has two modules, note and voice. Note
modules receive instructions on local chains, and tell voice
modules on remote chains to execute them.

There are two things to be negotiated during the handshake.

1. What is the message encoding? For example: JSON or Protobuf.
2. What type of messages are being sent? For example: Cosmos SDK with
   the Osmosis extension.

## Requirements

We'd like the following to be true:

1. A note should only connect to a voice of the same polytone version.
2. A note should only connect to a voice who's supported extensions
   and encodings are a superset of their own.
3. A channel can be opened from either the note or voice side of the
   connection.

The first requrement ensures that a note never connects to a different
IBC protocol or another note module. The second, that every message
sent could be executed. The third is good relayer UX.

## Design

There are four steps to the IBC handshake, init, try, ack, and
confirm. These alternate between the two chains, for example, for a
connection between A and B, init would be called on A, try on B, ack
on A, and confirm on B.

During a handshake, the modules involved can pass around a version
datastructure. For the init phase, this is set by the initializer of
the handshake, afterwards it is set by the modules.

### Init

```
def init(version):
    if version == "polytone":
        if note:
            return "polytone-note-1"
        if voice:
            return "polytone-voice-1"
    return error
```

During initialization, it is checked that the initiator means to
create a Polytone channel (satisfying requirement (1)), and the
version of the module is sent to the counterparty.

### Try

First, we defined `supported` as the set of encodings and extensions
supported by a module. For example, a CosmWasm voice module for
Osmosis might have:

```
supported = ["JSON-CosmosMsg", "JSON-OsmosisExtension"]
```

The logic for try then verifies that the counterparty module satisfies
requirement (2) and returns the supported set.

```
def try(version):
    if note && version == "polytone-voice-1" ||
       voice && version == "polytone-note-1":
        return supported
    return error
```

### ACK

```
def ack(version):
    if note && supported.subseteq(version) ||
       voice && version.subseteq(supported):
        return selection(version)
```

The `selection` function selects from any mutually exclusive
options. For example, for a version like:

```
["proto3-CosmosMsg", "JSON-CosmosMsg"]
```

A selection method that prefered JSON would return:

```
["JSON-CosmosMsg"]
```

## Confirm

```
def confirm(version):
    return version
```

Once the selection is done, there is nothing to do but accept it on
the confirm step. Implementors will likely add additional logic here
for checking the final version, and configuring the state machine for
the selected version.