• RFC0 documents RFC process
• README mentions the status of an RFC
• Draft RFCs have a discussion issue
• Discussion issues have a list of open questions/problems
• Once they are solved, a finalization PR is made
• This PR modifies the registry + changes status to Final

Currently, RFC-003-SWAP-Basic uses the notion α.
However, while I like the short form of α instead of alpha I think we should use alpha everywhere, because:

• we don't use this notion in any other RFC -> this would keep all RFCs aligned
• alpha is easier to write - I would not know how to write an α on my keyboard without googling it
• I think it is a bit weird to mix alpha and α --> e.g. we have alpha HTLC and α-HTLC

Many things have changed in the implementation since we initially wrote down RFC001, here is an incomplete, to-be-extended list:

• lowercase header names (f.e. "Unsupported-Headers")
• advanced header values
• failure handling: comit-network/comit-rs#603

Currently, there is a lot of talk esp. in RFC1 about the possibility of several encodings with the JSON encoding being the only one defined so far.

I think we should make the JSON encoding the default one and delay it to the future coblox team to deal with other possible encodings and writing the RFCs for it.

This also includes merging the two RFC 002 and 003 from the old repository into one RFC.

Deprecate BAM!, rename the RFC to "COMIT messages" to specify headers, encoding by default using JSON, usage of libp2p and substream management.

Related to #57

DoD:

• RFC001 is re-written
• RFC-001-BAM label on GitHub is renamed
• Check/re-write BAM section in RFC-002
• Check other BAM mentions in README.md and registry.md
• Make sure to mention assumptions about the libp2p-stack (TcpTransport, Yamux multiplexer, Secio encryption)
• Make sure the Error frame was removed as part of this process to align with #117

This is the tracking issue for RFC-004-SWAP-Bitcoin

Use the following text:

** Bitcoin on Bitcoin **
Contract template:
 6382012088a82010000000000000000000000000000000000000000000000000000000000000018876a9143000000000000000000000000000000000000003670420000002b17576a91440000000000000000000000000000000000000046888ac
| Name | Byte Range | Length (bytes) |
|:--- |:--- |:--- |
| `secret_hash` | 7..39 | 32 |
| `redeem_identity` | 43..63 | 20 |
| `refund_timestamp` | 65..69 | 4 |
| `refund_identity` | 74..94 | 20 |

In order to build a 2nd implementation of COMIT that is compatible with the reference implementation, we specify the HTLCs as HEX codes in the RFCs and document the byte ranges which have to be replaced with the respective parameters.

• https://github.com/comit-network/RFCs/blob/master/RFC-005-SWAP-Basic-Bitcoin.md#contract
• https://github.com/comit-network/RFCs/blob/master/RFC-007-SWAP-Basic-Ether.md#contract
• https://github.com/comit-network/RFCs/blob/master/RFC-009-SWAP-Basic-ERC20.md#contract

In order to make sure that OUR implementation does the correct thing and to allow other implementors to have the same confidence, we should add test cases to all of these RFCs that can be taken and directly converted to unit tests:

Given the HTLC hex and concrete parameters, when the HTLC is constructed, should yield the correct hex.

Our test cases will need to provide:

• the HTLC hex
• concrete parameters
• the correct hex

Problem

In our code-base we identify Ethereum networks by the chain_id and not their name anymore. The RFC documents are outdated in that sense.

Goal

Have up-2-date RFC documents.

This ticket is about revising to RFC to match the implementation done in: comit-network/comit-rs#1440

We try to follow some conventions when writing RFCs but currently those are neither documented nor enforced in this repository.

This issue is about collecting the conventions we try to follow and find a way to automatically enforce them.

Conventions:

• RFCs must have a certain layout:

  • must have a status section at the top
  • must have a table of contents
  • must use asciidoc?

• A single sentence per line

  • Makes tracking changes in Git easier because Git works line-based
  • Allows to easily suggest changes to the RFC through GitHub "suggestion" feature in a pull request

Automated checks:

The layout parts can be checked manually rather easily, however the "one-sentence-per-line" thing is trickier. It is also not something that one should focus on while reviewing an RFC (the content is more important).

Create RFC that specifies the following for Ethereum/Ether/ERC20:

• HTLC hex code + contract explanation
• Identity
• Assets

Blocked by comit-network/comit-rs#638

This is a tracking issue for RFC-001 BAM!

Use ascii doc for all templates so that it is default for future spikes and rfcs.
Also, unify spike templates.

• https://github.com/comit-network/spikes/
• https://github.com/comit-network/rfcs/
• https://github.com/coblox/spikes/

The Bitcoin and Ether HTLCs have different functionality. The Bitcoin HTLC lets you specify which identity will finally own the funds upon redeeming while the Ether HTLC makes you specify the final address at contract creation time.

By restructuring the Ether HTLC we may be able to give it this functionality and therefore ease the burden on implementations.

This is the tracking issue for RFC-006-SWAP-Ethereum

Note: Implementation defined behaviour.

This is the discussion issue for RFC-010-Omni-Layer

This is the tracking issue for RFC-005-SWAP-Bitcoin-basic

Now that we have specified two RFCs which use BAM it would be good to investigate how well it solved the problems it was designed to and if are we using it in the right way.

A specific topic that must be addressed the design of and our use of status codes, particularly with regards to the "reason" headers. We had a discussion of this and there were multiple ideas that are simply here as a reminder.

1. We should use different status codes to represent every type of error including those that are related to the swap protocol parameters. e.g. timeouts-too-tight. We could partition them according to the "layer" they occurred to create some separation.
2. We should introduce a new type of status code e.g. NF** "negotiation failed" to indicate the proposed action was understood but was rejected.
3. The scope of RFC01 might be too big. Maybe some stuff should move into a more domain specific RFC.

Note this ticket isn't meant to imply that there is something wrong with the way things are now.

DoD:

• organise discussions around the topic
• organise decision

Blocked by #7

Currently, the comit node only supports the RFC-003 atomic swap protocol.

We should define what this actually means by creating RFC-003!

With PR #90, the Bitcoin HTLC was updated to be constructed from a HEX payload and the parameters to be replaced through byte ranges.

The timestamp is pushed onto the stack using OP_PUSHDATA4, which according to the docs, needs to be little-endian: https://en.bitcoin.it/wiki/Script#Constants

This has to be made LOUD AND CLEAR in the RFC since the HTLC does not work otherwise.

JSON in RFC-002 and RCF-003 does not match the scheme in api_tests/swap.scheme.json. This is a discussion topic because we should decide which is the single point of truth (SPOT).

This is the tracking issue for RFC-002-SWAP

Open questions:

• Define a header for unsupported ledger/asset?
• Enforce the use of thousands separators for quantities?

The following example in RFC002 is missing the contract address (address) in the erc20 asset description:

https://github.com/comit-network/RFCs/blob/master/RFC-002-SWAP.md#42-erc20-pay-tokens-for-10000-satoshis-on-mainnnet-using-rfc-003

This is the tracking issue for: RFC-008-ERC20

This is the tracking issue for RFC-009-SWAP-ERC20-basic

Similarly to RFC-004, we need to write and RFC to update the registry with the Omnilayer Token Asset definition so they can be used with RFC-002 SWAP

Blocks #33
Child of comit-network/comit-rs#663

There is this idea to make the JSON encoding the default and thereby postpone all decisions about other encodings to a later point: #57

If JSON is the default, we might consider using a more JSON-idiomatic naming convention for all fields: camelCase.

Calculate the appropriate alpha_expiry and beta_expiry for each party given the following:

• A function which when given the time since broadcasting a transaction and the transaction fee will return the probability that the transaction has been included in a block.
• A function which when given the time a transaction has been included in a block will return the probability of it being permanently in the blockchain.
• The party's required confidence that they won't lose an asset.

DOD:

• Make a meeting to demonstrate the model
• Give realistic alpha_expiry, beta_expiry values for BTC-ETH and ETH-BTC.
• Include results in relevant RFCs.
• Create issue to default to such realistic values in COMIT-i

Child of comit-network/comit-rs#670

There are two ways of invoking the Ethereum HTLC in an invalid way:

• with the wrong secret
• without the secret but before the expiry

In both cases, we currently return from the contract without doing anything. This makes it hard to observe, whether or not the invocation was actually successful. From an EVM perspective, it executes successfully (i.e. without any errors)
Such an observation would be useful in numerous ways:

1. In our e2e tests to check if the refund actually worked or if we have to invoke it again
2. Metamask may show something different if the user invokes a refund too early. Showing a successful transaction if it actually was not successful is pretty misleading.

Ethereum has the revert instruction to halt execution of a contract and rollback any changes.

This spike is about investigating, what the best way is to fail the invoking transaction of the HTLC.

Correct offsets are:

### RFC003 ###
** Ether on Ethereum **
Contract template:
 6100dc61000f6000396100dc6000f336156051576020361415605c57602060006000376020602160206000600060026048f17f1000000000000000000000000000000000000000000000000000000000000001602151141660625760006000f35b42632000000210609f575b60006000f35b7fb8cac300e37f03ad332e581dea21b2f0b84eaaadc184a295fef71e81f44a741360206000a1733000000000000000000000000000000000000003ff5b7f5d26862916391bf49478b2f5103b0720a842b45ef145a268f2cd1fb2aed5517860006000a1734000000000000000000000000000000000000004ff
| Data | Byte Range | Length (bytes) |
|:--- |:--- |:--- |
| `secret_hash` | 51..83 | 32 |
| `expiry` | 99..103 | 4 |
| `redeem_identity` | 153..173 | 20 |
| `refund_identity` | 214..234 | 20 |
** ERC20 on Ethereum **
Contract template:
 61014461000f6000396101446000f3361561005457602036141561006057602060006000376020602160206000600060026048f17f100000000000000000000000000000000000000000000000000000000000000160215114166100665760006000f35b426320000002106100a9575b60006000f35b7fb8cac300e37f03ad332e581dea21b2f0b84eaaadc184a295fef71e81f44a741360206000a17330000000000000000000000000000000000000036020526100ec565b7f5d26862916391bf49478b2f5103b0720a842b45ef145a268f2cd1fb2aed5517860006000a17340000000000000000000000000000000000000046020526100ec565b63a9059cbb6000527f5000000000000000000000000000000000000000000000000000000000000005604052602060606044601c6000736000000000000000000000000000000000000006620186a05a03f150602051ff
| Data | Byte Range | Length (bytes) |
|:--- |:--- |:--- |
| `secret_hash` | 53..85 | 32 |
| `expiry` | 102..106 | 4 |
| `redeem_identity` | 157..177 | 20 |
| `refund_identity` | 224..244 | 20 |
| `token_quantity` | 261..293 | 32 |
| `token_contract` | 307..327 | 20 |

The hex above contains placeholders (100...001) which we do not have but now want in the RFC.
Hence, update the RFC consequently.
However, the terminal ff is missing from the Ether Basic RFC and should be added.

Currently, the design of the SWAP messages are only in our code base.

We should document them as planned as RFC-002.

RFC to support RFC-003 for custom OmniLayer token assets. Please note that Omnicoins are just special omnilayer tokens with a predefined token id so this RFC could mention them.

Please note that RFC-003 is defined for cross-chain swaps only.

See comit-network/comit-rs#691 and comit-network/comit-rs#772 for the highlight of the findings to know what to write in the RFC.

Child of comit-network/comit-rs#663

Right now our we use the "pubkey hash" as the identity in RFC005. This is the wrong choice for two reasons:

1. In P2SH scripts the public key is already "hashed". We should just lock the branches of the if statement to the public keys themselves. (miniscript for example also generates scripts that use public keys because the witness stacks are smaller and hence cheaper)
2. In the taproot proposal outputs are locked to public keys. So sending to someone's public key will become the standard way of transferring Bitcoin (hopefully).

Related to: comit-network/comit-rs#1296

Recommendation

This is just about updating the RFC.
Note that we still use the hash in the HTLC, however the Identity is now a public key.
Also check the HTLC section as we may need to add a note that we don't use the Identity but the hash of it.

This is a tracking issue for RFC-003-SWAP-basic

This is the tracking issue for RFC-007-SWAP-Basic-Ether

Currently, the registry file is called COMIT-registry.md which is pretty redundant since the whole repository is about COMIT. I think we should rename the file to just registry.md.

RFC-001 contains the following sentence under heading 'Motivation and Requirements' (bold text highlights the terminology in question:

In COMIT, nodes need to exchange all kinds of information in a peer-to-peer manner. As COMIT is an inherently distributed system, the network will eventually become heterogeneous, with an array of implementations, varying in languages and versions. Given that, we need a transport protocol that fulfils the following requirements:

'transport protocol' is defined here as:

A communications protocol responsible for establishing a connection and ensuring that all data has arrived safely. It is defined in layer 4 of the OSI model. Often, the term transport protocol implies transport services, which includes the lower-level data link protocol that moves packets from one node to another.

BAM is not a transport protocol. It is an application layer protocol.

RFC to define new protocol that facilitates the exchange OmniLayer token assets with Bitcoin assets (same chain swap).

Please note that OmniCoins are just special OmniLayer tokens with a predefined token id so this RFC could mention them.
However, OmniLayer specifications already define a protocol for BTC<->OmniCoin.

This is for same chain swaps only. See #33 for cross-chain swaps using RFC-003.

See comit-network/comit-rs#691 and comit-network/comit-rs#772 for the highlight of the findings to know what to write in the RFC.

Child of comit-network/comit-rs#663

To be done when opensourcing the RFCs

DoD

• create tracking issues per RFC to collect the comments

Blocked by #6
Blocked by #7

We use the term expiry for the SWAP REQUEST message but most of the RFCs talk about a refund_timestamp.

This usage should be unified, potentially with a 3rd term if none of the two fit for all the purposes.

• RFC003 defines the parameter as expiry: https://github.com/comit-network/RFCs/blob/master/RFC-003-SWAP-Basic.md#hash-time-lock-contract-htlc
• RFC005 was updated to use refund_timestamp everywhere in this PR: https://github.com/comit-network/RFCs/blob/master/RFC-005-SWAP-Basic-Bitcoin.md#contract
• RFC007 refers to it as expiry and refund_timestamp in different contexts: https://github.com/comit-network/RFCs/blob/master/RFC-007-SWAP-Basic-Ether.md#contract
• RFC009 is the same: https://github.com/comit-network/RFCs/blob/master/RFC-009-SWAP-Basic-ERC20.md#contract

Suggestion:

• Use expiry everywhere as mentioned in @da-kami comment here: #90 (review)
• Update the code in comit-rs for generating the offsets to also use the term expiry. Here for example: https://github.com/comit-network/comit-rs/blob/master/vendor/blockchain_contracts/src/bin/calculate_offsets/ethereum/rfc003/templates/erc20/config.json#L10

Create RFC to specify the following Bitcoin related topics:

• HTLC and explanation
• Identity

Blocked by comit-network/comit-rs#679

As per discussion here:

Blocked by comit-network/comit-rs#665

Child of comit-network/comit-rs#663

DoD:
The following commands return 0 when executed in all coblox & comit-network repositories.

• $ git grep -i 'rfc-00[0-9]' | wc -l

After several discussions with @tcharding on the RFCs I would like to propose some changes to the RFC repository to make COMIT more understandable.

Most important, I'd propose to adapt the README of the RFC repository. This is the first point of entry for people trying to understand COMIT and it does not explain anything.

Currently the RFCs are a flat list and one cannot easily understand what is going on there without having the hierarchy lined out in e.g. the README. The more ledgers we add the more difficult it will get to stay on track with the hierarchy. Especially once adding lightning this will get messy, as we introduce another protocol on hierarchy level 3 and not just ledger-implementations for the existing RFC003 (which is on level 3)
We could think about introducing a folder structure to have more hierarchy.

Proposed structure after discussion with @D4nte:

- Messaging in COMIT (network communication) 
   - RFC-001-BAM.md (might be replaced with libp2p)
- Ledgers & Assets definitions
   - RFC-004-Bitcoin.md
   - RFC-006-Ethereum.md
   - RFC-008-ERC20.md
- Protocol Families
   - RFC-002-SWAP.md
- SWAP Protocols
   - Atomic Swaps using HTLCs ["basic" is still in debate]
      - RFC-003-SWAP-Basic.md
      - Implementation Details for SWAP Basic
         - RFC-005-SWAP-Basic-Bitcoin.md
         - RFC-007-SWAP-Basic-Ether.md
         - RFC-009-SWAP-Basic-ERC20.md

Dropped DoD:

• Introduce structure as folder structure and sort in files: good idea but we may change structure so let's do it once we have more RFCs and the categories are stable.
• Remove protocol specifics from the examples in "Ledger & Asset definitions": real examples are better

Agreed DoD:

• Introduce structure in README