Install Virtual App Protocol

Last updated 6 days ago

This is the Install Virtual App Protocol.

Roles

Three users run the protocol. They are designated as initiating, responding, and intermediary. The first two parties are the users wishing to interact together in a virtual app, who do not necessarily have a ledger channel between them. It is required that initiating and intermediary have a ledger channel together, and that responding and intermediary have a ledger channel together.

The InstallVirtualAppParams type

Field

type

description

initiatingXpub

xpub

xpub of initiating

respondingXpub

xpub

xpub of responding

intermediaryXpub

xpub

xpub of intermediary

defaultTimeout

uint256

appInterface

AppInterface

initialState

JSON

Encoded initial app state

initiatingBalanceDecrement

uint256

initiating's deposit into the installed application

respondingBalanceDecrement

uint256

responding's deposit into the installed application

expiry

uint256

Not implemented in machine yet

Derived fields

These fields are not included in InstallVirtualAppParams but are computed from existing information known to a user.

Field

type

description

multisig1Address

address

State deposit holder for the channel between initiating and intermediary

multisig2Address

address

State deposit holder for the channel between intermediary and responding

signingKeys

address[]

See below

{initiating,responding,intermediary}, together with the target app sequence number, are used to derive the app-specific signing keys. signingKeys[0] is the intermediary signing key, while signingKeys[1:2] are the signing keys used by initiating and responding, sorted lexicographically by public key.

Commitments

leftETHVirtualAppAgreement

A commitment to call ETHVirtualAppAgreement::delegateTarget with an Agreement argument with the following fields

Field

type

description

registry

address

From network context

terms

Terms

See below

expiry

address

expiry

appIdentityHash

bytes32

Hash of appIdentity of target virtual app

capitalProvided

uint256

aliceBalanceDecrement + bobBalanceDecrement

beneficiaries

address[2]

[initiatingAddress, intermediaryAddress]

rightETHVirtualAppAgreement

A commitment to call ETHVirtualAppAgreement::delegateTarget

Field

type

description

registry

address

From network context

terms

Terms

See below

expiry

address

expiry

appIdentityHash

bytes32

Hash of appIdentity of target virtual app

capitalProvided

uint256

aliceBalanceDecrement + bobBalanceDecrement

beneficiaries

address[2]

[intermediaryAddress, respondingAddress]

terms:

Field

type

description

assetType

uint8

0

token

address

address(0)

limit

uint256

0

limit is explicitly ignored by the contract, while assetType, token == 0, 0 means ETH.

targetVirtualAppSetState

The protocol produces a commitment to call virtualAppSetState with the initial state. Note that intermediary produces a "type 2" signature while the others produce a "type 1" signature. This ensures that the intermediary's signature can be reused for calling virtualAppSetState with other app state hash values, i.e., that the intermediary does not need to be part of the update-virtual-app protocol.

d1 = keccak256(
["bytes1", "bytes32", "bytes32", "uint256",
[
0x19,
keccak256(identity),
0,
TIMEOUT
]
);
d2 = keccak256(
["bytes1", "bytes32", "uint256", "uint256", "bytes1"],
[
0x19,
keccak256(identity),
65536,
TIMEOUT,
byte(0x01)
);

The signatures s5 and s7 are the signatures of initiating and responding respectively on d1 while the signature s6 is the signature of intermediary on d2.

Messages

M1

Field

Type

Description

protocol

string

"install-virtual-app"

multisig

address

multisig1Address

params

InstallVirtualAppParams

fromAddress

address

initiatingAddress

toAddress

address

intermediaryAddress

seq

number

1

signature1

signature

The S1 signature

signature2

signature

The S5 signature

M2

Field

Description

protocol

"install-virtual-app"

multisig

multisig2Address

params

InstallVirtualAppParams

fromAddress

intermediaryAddress

toAddress

respondingAddress

seq

2

signature1

The S5 signature (forwarded).

signature2

The S3 signature

M3

Field

Description

protocol

"install-virtual-app"

multisig

multisig2Address

fromAddress

respondingAddress

toAddress

intermediaryAddress

seq

3

signature1

The S4 signature.

signature2

The S7 signature.

M4

Field

Description

protocol

"install-virtual-app"

multisig

multisig2Address

fromAddress

intermediaryAddress

toAddress

respondingAddress

seq

4

signature1

The S6 signature.

M5

Field

Description

protocol

"install-virtual-app"

multisig

multisig1Address

fromAddress

intermediaryAddress

toAddress

initiatingAddress

seq

5

signature1

The S6 signature.

signature2

The S2 signature.

signature3

The S7 signature.

Summary

Signature

Commitment

Signed By

s1

leftETHVirtualAppAgreement

A

s2

leftETHVirtualAppAgreement

I

s3

rightETHVirtualAppAgreement

I

s4

rightETHVirtualAppAgreement

B

s5

targetVirtualAppSetState

A

s6

targetVirtualAppSetState

I

s7

targetVirtualAppSetState

B

Message

Signatures

m1

s1, s5

m2

s5, s3

m3

s4, s7

m4

s6

m5

s6, s2, s7