This PR adds the ethereum bridge smart contract. We still need to add many more test cases and optimize the code to reduce ethereum transaction fees. Those two issues will be addressed in future PRs.

What

Add a diagram showing the flow of data with one possible design of how Stellar could integrate with blockchain bridges that run their own validators.

Why

As a starting point for brainstorming, and to help identify gaps in understanding, and problems that need solving.

When a new validator starts (or existing one lost it's DB) it needs to process all withdrawal transactions to prevent double spend. This commit adds this mode that will run on the first call to ProcessNewLedgers.

Close #74.

This will be a fairly involved issue (Epic) so I've not filled it out yet

What problem does your feature solve?

Coordinating signatures for a Stellar tx from m-of-n signers

What would you like to see?

A server that connects to other servers given fixed hostnames or IP addresses. The server initiates the signing of a Stellar tx from these n servers. Note that the starting point is a Stellar tx. Once fully signed it can return it using an API or to keep things simple it can just display it on-screen.

Additionally, there is an API we will need to develop such that the invoking caller can interface with this decentralized service. For example, when we /submit (POST) the stellar tx to be signed, we might get a HTTP 200 response and later need to GET the signed tx fully signed (or partially signed to get the /status).

Non-Goals

This is a single-responsibility component. This will be invoked by a higher-level orchestrator. We don't need to worry about validation of the Stellar tx, or the question of whether this Stellar tx has been submitted previously or not since that is validated by the Validation component (see other issues in this milestone)

What alternatives are there?

A lot of this is outlined in the multisig federation SEP protocol doc here that we can look at: https://docs.google.com/document/d/1mBxYsyuEj7j3fqMdvcJHZ5REZZpz3yjBe3OGjS13zoA/edit We can look at satoshipay's reference implementation for this here: https://github.com/satoshipay/signature-coordinator

There's also Refactor from Stellar-Expert: https://github.com/stellar-expert/refractor

What problem does your feature solve?

Converting from Ethereum transactions to Stellar transactions

What would you like to see?

An equivalent Stellar tx for a given Ethereum tx

• The input is an Ethereum transaction hash
• The output has the correct "escrow account" address as an issue of the asset on the Stellar network.
• The output is the Ethereum Transaction along with the transformed Stellar tx and hash
• This only needs to work for simple payment transactions of any native or non-native Ethereum tokens. If the input Ethereum transaction is more complex then we can print a message to indicate that the operation is not supported.

The main program that runs this conversion is primarily used to demonstrate this component. We will be plugging this component into the rest of the system via it's exported methods so we need to ensure the exported methods returns the correct values or errors so it can be used directly by the calling code.

What alternatives are there?

This will plug into our MVP starbridge solution

Decimal Incompatibility Problem

Stellar supports up to 7 decimals, whereas many assets on the Ethereum network are specified with 18 decimals. This can be a problem because it can result in a loss of precision and therefore a loss of funds. We need to handle this conversion correctly such that there is no loss of funds. We should also try and ensure there is no loss of precision however that may not be possible.

Proposed solution

We can issue microassets on the Stellar network to make up the different in precision. A microasset is an issuance of a smaller denomination of a given asset. For example, 1 ETH = 10^3 milli ETH = 10^6 micro ETH = 10^9 nano ETH = 10^12 pico assets.

That is, when converting 1 ETH from Ethereum to Stellar we can convert it to 10^12 pETH, where 1 pETH represents 10^-12 ETH.

We can do something in-between where we check the precision of the asset value locked in the ETH transaction and if it makes uses of more than 7 decimals (i.e has a value like 1.12345678 ETH instead of 1.1234567 ETH) then we can issue pETH otherwise we can issue ETH to the destination account. Therefore, we will have two assets issued for each ETH asset, the asset code and one prefixed with "p" to represent a pico asset.

Alternatives

• we could consider dropping down to a 7-decimal precision, and returning any extra funds beyond 7-decimals in a refund transaction on the Ethereum network (although the value of the returned funds may be smaller than the amount we pay in fees to reutrn those funds).
• we can suggest that we don't support such a high precision value and we can truncate the value up to 7-decimals, thereby consuming the dust amount as a fees (since it's locked in the Starbridge Smart Contract deployed on Ethereum). Note that this is not a loss of funds but is a voluntary donation to the bridge in the form of fees.

This PR implements getStellarDeposit() which is a helper function to extract and validate a deposit to the Stellar bridge account from an http request. getStellarDeposit() will be used by the HTTP handlers for the Stellar -> Ethereum withdrawal and refund endpoints.

A stellar deposit is valid if:

• the transaction is successful
• the transaction contains only one operation which is a payment to the bridge account

Note that we do not validate the Stellar asset or the ethereum address of the recipient (which is encoded in the transaction memo). Validation of those fields should only be implemented in the HTTP handler for the withdrawal endpoint. If a user does not set the memo correctly on their payment to the bridge then the withdrawal should fail, however, it should still be possible to refund the payment.

This commit implements changes connected to cancellation flow suggested by @nano-o specifically, expire transactions which are irrevocably invalid (ie. sequence number bumped) and use ledger close time to calculate timebounds of transactions generated by Starbridge. Additionally, it moves responsibility to set timebounds to the client because different Starbridge servers can process a signing request at different moments in time.

This commit adds initial versions of different services of Starbridge server. In general the server is currenly divided into two parts: frontend and backend. Frontend handles HTTP requests and allows users to create SignatureRequest's (requests to sign an inverse transaction) and send it to a backend server via a queue (or a DB). Backend server is responsible for streaming blockchain data, handling SignatureRequest's and finally creating and signing transactions. This separation was made to allow more secure architectures in which frontend server does not have access to signing part of the app.

In the backend server, transaction builder and transaction signer are separate entities. This is done to (maybe) support using secure enclaves (like AWS Nitro Enclaves) that will store the secret key and sign transactions.

List of services:

• backend/Worker - Main backend worker handling SignatureRequest
• stellar/controllers/StellarGetInverseTransactionForEthereum - Controller responsible for building inverse transactions, contains simple logic for checking if a new SignatureRequest should be created or if the inverse transaction should be returned to the user
• stellar/signer/Signer - Stellar transaction signer
• stellar/txbuilder/Builder - Stellar transaction builder, currently ETH tx hardcoded
• stellar/txobserver/Observer - Observer of Stellar transactions, currently using testnet.
• store/Memory - Storage system implemented in memory, in the future: Postgres DB.

The current version contains at least one race condition because UpsertOutgoingStellarTransaction is called concurrently from two different services. This should be solved by SELECT ... FOR UPDATE in Postgres but I wonder if we should allow just one DB transaction at a time for security reasons (to decrease number of synchronization issues).

What

Change license of contracts to Apache 2.0.

Why

The code in this repository is intended to be licensed only with the Apache License 2.0, as is most software products produced by @stellar. Looks like we accidentally committed contracts with a combination of ISC and MIT licensing.

What

Enable mDNS always, not only when no peers are specified.

Why

mDNS is only enabled when no peers are specified, but this is inconvenient when running local tests where I want the app to connect to a specific remote peer and serve up mDNS discoverability locally.

*** This issue is not up-to-date as it has been simplified *** @nikhilsaraf to update

What problem does your feature solve?

Validate transactions so that only those transactions that are eligible to be submitted to the Stellar network will be sent for signature collection (multisig) by the orchestrator

What would you like to see?

Given an Ethereum transaction, validate the following:

• This Ethereum transaction has not previously been submitted to the Stellar network successfully (suggestion: can use db with eth tx as primary key and status field with values ETH_UNSUPPORTED, STELLAR_INVALID, STELLAR_OUT_FOR_SIGNATURE, STELLAR_EXPIRED, STELLAR_SUCCESS, STELLAR_FAILED)
• This Ethereum tx is eligible to be submitted (use ETH_UNSUPPORTED to denote that it is unsupported)

Given an unsigned Stellar transaction, validate the following:

• The token used in the Stellar transaction is what we expect from the db as issued by the "bridge account" (same as "escrow account" -- see Note below). For now, there will only ever be 1 bridge account for each token.
• Source account is NOT one of the signers for the escrow account
• Tx has an end time bound of no more than 720 ledgers (1 hour)

Given a signed Stellar tx, validate the following:

• all previous validations of an unsigned tx
• we are still within the time bounds of the tx
• we have exactly m of n signatures for the escrow account

three exposed endpoints (or functions):

• Is Ethereum tx valid
• Is unsigned Stellar tx valid
• Is signed Stellar tx valid

Note: we will likely need a database or in-memory representation of the status of each Ethereum tx and corresponding Stellar transactions (foreign key reference). We will also need to sync up with the Stellar network to fill in the STELLAR_SUCCESS status in the case where a transaction has been successfully processed by the Stellar network so that we don't re-process it. The db will also need to maintain the list of "escrow" accounts and the associated signers. Anytime there is a tx that modifies the signers (currently out of scope) this db entry will also need to be updated. Lastly we will also need to maintain a mapping of crypto token to "escrow" accounts so we know which "bridge account" to work with when validating that the Stellar tx has been created correctly.

What alternatives are there?

None

Starbridge - Frontend

The objective of this project is to transfer assets between wallets from different networks. Currently, the available flows are from Stellar to Ethereum and vice versa, being able to send only ETH from one to the other. With some initial setup, you will be able to connect your wallets using Freighter for Stellar and Metamask for Ethereum and start the transfer flow.

⚠️ Remember that the refund flow was not implemented in both transfer flows!

Project Architecture

Front: React, Typescript using the Atomic Design

You can check the project architecture here

Environment Variables

The environment variables are in src/config. You can use the .env.example as a base to create your .env.local config file

Run Locally

Install dependencies

  npm install

Start the server

  npm run start:dev

The project will be running at http://localhost:3000/

If you want you can run it on Docker too.

  docker build -t starbridge-front .   
  docker run -dp 3000:3000 starbridge-front

Using the ngrok

To make transactions on your wallets, you must have a secure connection locally. With ngrok it is possible to create an SSL certificate to be able to continue in the flow without problems.

You need to register, to generate a token and then continue configuring ngrok.

  ngrok config add-authtoken <token>
  ngrok http 3000

FAQ

I disconnected my account through the page, but when I connect again it automatically connects.

You must disconnect from the page through your Wallet as well, so you can connect to another account again.

I'm trying to do the withdraw action on the Ethereum -> Stellar flow but the error "retry later once the transaction has more confirmations" appears.

Confirmations are required to verify and legitimize information that will be recorded in the blockchain and cannot be changed afterward. If some information is assumed fraudulent, it will not get any confirmation. Without a single transaction confirmation Ethereum, the transaction won’t be considered valid by the network. Each confirmation takes less than one minute. Just wait a bit and try to perform the withdraw action again.

Demo

This PR implements fixes for "SBR-1 Replay attacks between chains" and "SBR-2 Deposited funds potentially locked in contract" from the security audit report:

https://drive.google.com/file/d/1f_IqUB3k3Q9XjLhG38zK5XWRF43tLZ_t/view

SBR1 is addressed by including adomainSeparator in the hash which is signed by the validators. The domainSeparator consists of the validator set version, the network chain id, and the bridge smart contract address. Including those components ensures that signatures cannot be replayed on bridge contracts deployed on multiple chains (e.g. testnet and mainnet).

SBR-2 is addressed by ~having a restricted list of all supported ERC20 tokens which can be deposited to the bridge contract. It is up to the validators to ensure that this allow list will contain only standard ERC20 tokens which do not subtract fees in tokens from the transferred value.~ [Edit: I removed the deposit token allow list and instead explicitly checked the amount of tokens transferred to the bridge as suggested by the security audit]

Note that "SBR-3 Possible name or symbol collisions for Stellar assets" is not addressed because I think the validators can agree to not reuse symbols or names when registering Stellar assets. I think this behavior can be enforced through validator behavior and I don't think it's necessary to enforce name collision prevention in the smart contract logic. If the validators were compromised then there would be attacks of greater impact than just registering stellar assets with duplicate names.

Can be done later (after MVP) but we should probably add a config value for minimum deposit. Otherwise it's possible to add thousands of rows in Starbridge DB quite easily.

Originally posted by @bartekn in https://github.com/stellar/starbridge/pull/86#discussion_r915288407

I realized that sourceAccount.LastModifiedLedger is updated also when the account receives the deposit not only when the sequence is bumped. With the current single condition I think it's possible to block the withdrawal of any account by sending 1 stroop every ledger. I wonder how and if we can solve this.

EDIT: Looks like we could use CAP-21 and it's seqLedger which equals to "ledger number at which seqNum took on its present value". In Horizon it's Account.SequenceLedger but can be empty if not set in extension.

Originally posted by @bartekn in https://github.com/stellar/starbridge/pull/68#discussion_r912921050

Currently we assume a singleton deployment of validator backend worker and validator http controller. We should determine if the validator can still run safely with multiple instances of a backend worker or http controller.