Programming Languages

Setting up the Test Network

By default, Glow will use the Cardano EVM Devnet (“ced”)—a public network on which you can interact with other users. You may experience a short delay of a minute or so when confirming each step of the interaction.

For faster local-only tests with confirmations in a couple of seconds, you can instead run your own private Ethereum test network (“pet”) on your computer with the instructions as follows. You should then add the flags --evm-network pet to your invocations of glow that talk to the network.

run-ethereum-test-net

You can use the help command of the run-ethereum-test-net executable to explore some options offered. Note that this will create data files under ~/.local/share/gerbil-ethereum/ and log files under ~/.local/share/log/gerbil-ethereum/, though this can be redirected via the XDG_DATA_HOME environment variable as per the XDG Base Directory Specification.

Creating Keys

Each participant must first generate their own identity on their own machine, with their own secret key, as follows:

Alice:

glow generate-identity --nickname Alice

Bob:

glow generate-identity --nickname Bob

Sharing Contact Information

After creating your key, you must share it with the other participant in the interaction (for example, using a chat application such as Slack).

First, each participant lists their address using:

glow list-identities

The listed addresses will appear in the following format (these are examples):

Alice [ 0xa71CEb0990dD1f29C2a064c29392Fe66baf05aE1 ]
Bob [ 0xb0bb1ed229f5Ed588495AC9739eD1555f5c3aabD ]

Each participant then uses a copy and paste function to share their address with the other participant, who will register it as follows, where each participant should replace the addresses below by the actual address generated by the other participant and communicated to them via chat.

Alice would add Bob’s address to her contact list with a command as follows:

bobs_address=0xb0bb1ed229f5Ed588495AC9739eD1555f5c3aabD
glow add-contact --nickname Bob --address ${bobs_address}

Alice would add Alice’s address to her contact list with a command as follows:

alices_address=0xa71CEb0990dD1f29C2a064c29392Fe66baf05aE1
glow add-contact --nickname Alice --address ${alices_address}

After adding a contact, you can see it in you list of contacts:

glow list-contacts
Alice [ 0xa71CEb0990dD1f29C2a064c29392Fe66baf05aE1 ]
Bob [ 0xb0bb1ed229f5Ed588495AC9739eD1555f5c3aabD ]

Getting Tokens from the Faucet:

As your address is a new address it does not have any tokens to spend, or to use to pay for gas. To get some tokens for your address you can use the test network’s faucet, as follows:

Alice runs:

glow faucet --to Alice

Bob runs:

glow faucet --to Bob

If you are using a local test blockchain, you would add --evm-network pet to the two commands above, such as in: glow faucet --to Alice --evm-network pet. You would also add it to every command below except for the digest command. Note however that you can only do that if the two participants are on the same machine and have access to the same local test blockchain (or you otherwise setup a tunnel proxy so they behave as if). Otherwise, you will want to keep using the default shared network ced though it may be slightly slower.

Configuring the Interactions

This section outlines how you should configure the contract interactions of Alice and Bob.

Setting up Alice’s Interaction

One of the two participants writes a document for the other to sign. For example, Alice prepares the following document and sends it to Bob for review:

$ echo "This is a test. Bob sells, Alice buys." > document.txt

When both agree on the document, they should each compute its digest with:

$ glow digest document.txt
0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe

Now, Alice can sign the interaction. In the scenario where you are running the interactions on the same machine, you should specify a database so the two users will not conflict with each other’s data; the extra database specification is not necessary if the users are running on different machines or even in different directories on the same machine (different $HOME or at least different $XDG_CONFIG_HOME).

$ glow start-interaction --database Alice
Connecting to the Cardano EVM Devnet at https://rpc-evm.portal.dev.cardano.org/ ...
Choose application:

The CLI will then prompt Alice to select an application, choose which identity to use for the interaction, which role they will play in it, assign addresses to roles of the other identities, enter the interaction parameters, and finally, print the interaction agreement for Alice to send to Bob, so that he can configure his side of the interaction with the same parameters.

Here is an example of what the setup should look like from Alice’s side:

Choose application:
1) coin_flip
2) buy_sig
3) rps_simple
Enter number
> 2
Choose your identity:
1) alice - 0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c
2) bob - 0x04F0B988FE46E83D74336e370E1f24B975019868
Enter number
> 1
Choose your role:
1) Buyer
2) Seller
Enter number
> 1
Assign roles
Select address for Seller:
1) alice - 0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c
2) bob - 0x04F0B988FE46E83D74336e370E1f24B975019868
Enter number
> 2
Define parameters
Enter digest
> 0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe
Enter price
> 987654321

Note that the price here was in test tokens. This will probably change in the near future, with an amended interface.

Max initial block [ Current block number is 36074 ]
> 36100

Alice will start

One line command for other participants to generate the same agreement:

$ glow start-interaction --agreement '{"glow-version":"Glow v0.1.0","interaction":"mukn/glow/dapps/buy_sig#payForSignature","participants":{"Buyer":"0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c","Seller":"0x04F0B988FE46E83D74336e370E1f24B975019868"},"parameters":{"digest":"0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe","price":"0x3ade68b1"},"reference":{},"options":{"blockchain":"Cardano EVM Devnet","timeoutInBlocks":"0x3e8","maxInitialBlock":"0x8d04"},"code-digest":"0x16c5659f6e3c70f0c53ac5abf3977e658093f1f5880bd478de8d3a87c92d9607"}'
Executing code block begin0 ...
(add-to-deposit price)
(@debug-label dlb1)

And will send Bob the command to start-interaction

Setting up Bob’s Interaction

Bob’s interaction does not require as many steps since the agreement contains all of the parameters already. He just needs to verify and accept the agreement, then specify which identity and role he is going to use in the interaction. Note also the database option that was appended to separate Bob’s database from Alice’s, when running both participants on the same machine with the same $HOME.

$ glow start-interaction --agreement '{"glow-version":"Glow v0.1.0","interaction":"mukn/glow/dapps/buy_sig#payForSignature","participants":{"Buyer":"0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c","Seller":"0x04F0B988FE46E83D74336e370E1f24B975019868"},"parameters":{"digest":"0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe","price":"0x3ade68b1"},"reference":{},"options":{"blockchain":"Cardano EVM Devnet","timeoutInBlocks":"0x3e8","maxInitialBlock":"0x8d04"},"code-digest":"0x16c5659f6e3c70f0c53ac5abf3977e658093f1f5880bd478de8d3a87c92d9607"}' --database Bob
Connecting to the Cardano EVM Devnet at https://rpc-evm.portal.dev.cardano.org/ ...
Choose your identity:
1) alice - 0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c
2) bob - 0x04F0B988FE46E83D74336e370E1f24B975019868
Enter number
> 2
Choose your role:
1) Buyer
2) Seller
Enter number
> 2

Alice generates the handshake

After setting up the interaction, the Glow runtime component will deploy an EVM smart contract to the configured network and generate a handshake to send to Bob. The handshake is for Bob to verify that the on-chain contract corresponds to everything that is specified in the agreement.

Send the handshake below to the other participant:

{"agreement":{"glow-version":"Glow v0.1.0","interaction":"mukn/glow/dapps/buy_sig#payForSignature","participants":{"Buyer":"0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c","Seller":"0x04F0B988FE46E83D74336e370E1f24B975019868"},"parameters":{"digest":"0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe","price":"0x3ade68b1"},"reference":{},"options":{"blockchain":"Cardano EVM Devnet","timeoutInBlocks":"0x3e8","maxInitialBlock":"0x8d04"},"code-digest":"0x16c5659f6e3c70f0c53ac5abf3977e658093f1f5880bd478de8d3a87c92d9607"},"contract-config":{"contract-address":"0x5Cf4788Beb41B737bd86BFA34a013df05640c1Ce","code-hash":"0xb891d1c6c8b794c6b64094a16c3f6ed7b916602e42e8a05c6c4ad172fb0941a4","creation-hash":"0xe6fb35787bf51e9bc3cb255ef717791127724819db32ea835a4340d7b22d24e2","creation-block":"0x8ceb"},"published-data":"0x"}

Waiting for Seller to make a move ...

Alice sends Bob the handshake via email/messenger/etc

Bob captures the handshake

All Bob has left to do is paste the handshake when prompted and the runtime will handle everything from there. First by generating a signature of the digest and then publishing it on-chain. Alice’s runtime will then watch the network for transactions against the contract to see Bob’s move, and both runtimes should run to completion without requiring any more user input.

{"agreement":{"glow-version":"Glow v0.1.0","interaction":"mukn/glow/dapps/buy_sig#payForSignature","participants":{"Buyer":"0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c","Seller":"0x04F0B988FE46E83D74336e370E1f24B975019868"},"parameters":{"digest":"0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe","price":"0x3ade68b1"},"reference":{},"options":{"blockchain":"Cardano EVM Devnet","timeoutInBlocks":"0x3e8","maxInitialBlock":"0x8d04"},"code-digest":"0x16c5659f6e3c70f0c53ac5abf3977e658093f1f5880bd478de8d3a87c92d9607"},"contract-config":{"contract-address":"0x5Cf4788Beb41B737bd86BFA34a013df05640c1Ce","code-hash":"0xb891d1c6c8b794c6b64094a16c3f6ed7b916602e42e8a05c6c4ad172fb0941a4","creation-hash":"0xe6fb35787bf51e9bc3cb255ef717791127724819db32ea835a4340d7b22d24e2","creation-block":"0x8ceb"},"published-data":"0x"}
# CONTRACT executes
Executing code block begin0 ...
(expect-deposited price)
(@debug-label dlb1)
Executing code block cp0 ...
(set-participant Seller)
(def signature (sign digest0))
(add-to-publish 'signature signature)
(def tmp (@app isValidSignature Seller digest0 signature))
(require! tmp)
(@debug-label dlb2)
(participant:withdraw Seller price)
(return (@tuple))
(@label end0)

Bob receives confirmation that contract has finished

The last thing the runtime does is print all the variables that were bound during execution of the contract, with the signature being purchased highlighted for both participants.

mukn/glow/dapps/buy_sig#payForSignature interaction finished
Final environment:
Buyer => (address<-0x "0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c")
Seller => (address<-0x "0x04F0B988FE46E83D74336e370E1f24B975019868")
digest => (bytes<-0x "0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe")
price => 987654321
signature => (<-json Signature "812b6ef8e26e83e9b247ac31c798e5dc50ca102b349d83f16a97d582f1710b711a15125c1b80a081eb670c0552344790d32c207c8be115cd6d59e41a8a6bbdf91b")

Meanwhile Alice waits for Bob to submit the handshake

Executing code block cp0 ...
(set-participant Seller)
(def signature (expect-published 'signature))
(def tmp (@app isValidSignature Seller digest0 signature))
(require! tmp)
(@debug-label dlb2)
(participant:withdraw Seller price)
(return (@tuple))
(@label end0)

Alice receives confirmation that contract has finished

mukn/glow/dapps/buy_sig#payForSignature interaction finished
Final environment:
Buyer => (address<-0x "0x579E786dE324FC811839e9f6959C8d9EaCdEAa0c")
Seller => (address<-0x "0x04F0B988FE46E83D74336e370E1f24B975019868")
digest => (bytes<-0x "0x82082c8c9c193135a1ae6c9d8612682363ca34ba5ce87dd81d92e6e8a75c9dfe")
price => 987654321
signature => (<-json Signature "812b6ef8e26e83e9b247ac31c798e5dc50ca102b349d83f16a97d582f1710b711a15125c1b80a081eb670c0552344790d32c207c8be115cd6d59e41a8a6bbdf91b")

Last updated: March 2, 2021 17:03 UTC