stellar / starbridge

Software that facilitates bridge builders who are connecting the Stellar network to other blockchains.

Creating equitable access to the global financial system

Starbridge

Starbridge is software that facilitates bridge builders who are connecting the Stellar network to other blockchains.

Starbridge is in early development.

Get involved

• Docs
• Discussions
• More to come...

starbridge's Issues

FPP: Orchestrator API

What problem does your feature solve?

This connects the various components behind an API

What would you like to see?

TBD

What alternatives are there?

None

Implement ingestion backfill

The validator requires that all Stellar payments originating from the bridge multisig account are ingested into the validator database. When the validator starts up and detects the database is empty it should start ingesting payments from the moment the bridge multisig account was created.

Include json response for error responses in validator API

Currently all error responses do not include any structured response which means that no details about the failure are included in the response besides the http status code

Ensure the safety of allowing multiple backend / controller workers

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.

FPP: Deploy Ethereum Smart-Contract on Ropsten Test network

What problem does your feature solve?

We want to deploy a smart contract on the Ethereum test network (Ropsten). This will perform the functionalities of a multisig escrow account

What would you like to see?

We would ideally like to use an off-the-shelf smart contract from something like OpenZepplin, or it's primitives. We would ideally not like to write our own smart contract from scratch since an escrow account contract seems like it can be available in the open-source community

Other resources we can use:

• OpenZepplin
• Rari-Capital
• BitGo Multisig Wallet

The smart contract should support the following:

1. any user on Ethereum network locks up funds in the smart contract (to be subsequently minted on Stellar by Starbridge).
   • These can be any native ETH or ERC-20 tokens.
   • The send() or pay() function should take in the Stellar address (56 string characters; base-32 encoded) as data or a memo of some sort.
2. multisig (2 of 3) accounts can invoke a _wrapPay() operation on the smart contract. This function will wrap an asset from a remote chain (relevant data passed in as arguments to the function call) and send it to the ethereum user (address sent to function as an argument). Note that this wraps an asset such as XLM into a wrapped asset like WXLM and these wrapped tokens are issued by the smart contract, similar to how it works on Stellar with escrow accounts.
3. multisig (2 of 3) accounts can invoke an _unwrapPay() operation on the smart contract. This function will unwrap an asset sent from a remote chain where the underlying asset is locked in the smart contract itself (relevant data passed in as arguments to the function call). The smart contract will then send it to the ethereum user (address sent to function as an argument). Note that this unwraps an asset such as WETH into the underlying asset ETH asset from the locked balances in the smart contract.

What alternatives are there?

TBD

Replace all context.TODO() to correct request or background context

FPP: dAPP for Ethereum and Stellar to trigger smart contract invocations

What problem does your feature solve?

We will need a dApp web page for both Stellar and Ethereum. These will construct the transactions for both chains as needed. This does not need to be very fancy but just a way by which we can interact with the bridge and not have to manually trigger smart contract calls (or Stellar tx constructions).

What would you like to see?

single web page that has two sections: Stellar and Ethereum. These will trigger the Freighter/Stellarterm wallet on Stellar and the Metamask wallet for Ethereum

it has a form like so (Stellar):

• send tokens from Stellar to Ethereum (wrap): stellar_asset_code, stellar_asset_issuer, amount_with_decimals, destination_ethereum_address
• send tokens from Stellar to Ethereum (unwrap): ethereum_token_contract_address, amount_with_decimals, destination_ethereum_address

it has a form like so (Ethereum):

• send tokens from Ethereum to Stellar (wrap): ethereum_token_contract_address, amount_with_decimals, destination_stellar_address
• send tokens from Ethereum to Stellar (unwrap): stellar_asset_code, stellar_asset_issuer, amount_with_decimals, destination_stellar_address

What alternatives are there?

v1.0 can be a more aesthetic version of this.

Generate validator tests using Ivy

add Stellar destination address to Ethereum tx

What problem does your feature solve?

This will allow us to let the Ethereum user specify what their destination Stellar address is

What would you like to see?

• update Test Ethereum smart contract
• update Starbridge logic to read the new Event API

op_malformed when submitting transaction

horizon error: "Transaction Failed" (tx_failed, op_malformed) - check horizon.Error.Problem for more information pid=33006 tx=266fd1ab915aae2c24e7dd4d966f7a4bcbaa219b742beced0becb568f79121b6

the tx that is constructed should be correct. things to look out for: issues constructing claimable balance ops, sponsorship, 0 value asset payments

FPP: Validation of transactions

*** 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

Add restrictions on withdrawal amounts

In ethereum 256 bits of precision are used to represent ether / erc20 token amounts. However, Stellar can only support 64 bits of precision. We will need to add restrictions on withdrawal amounts so that if someone deposits an amount of ether / erc20 tokens which is not representable in stellar the validator will reject Stellar withdrawal attempts for that deposit. The only action allowed for such deposits is ethereum refunds (after the withdrawal window). The restrictions on withdrawal amounts should be configured on a per token basis and these restrictions should be configured in the validator toml file.

An example of a restriction could be:

every ether deposit must be a multiple of 1 gwei (10^9 wei) and the maximum amount of eth that could be deposited is (2^64 / 10^9 )

FPP: Transform Ethereum tx to Stellar tx

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.

Add minimum value for Stellar deposits

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 #86 (comment)

Add end to end integration tests for all user flows

Scenarios which should be covered:

• eth -> stellar withdrawal
• erc20 -> stellar withdrawal
• eth -> stellar refund
• erc20 -> stellar refund
• xlm -> ethereum withdrawal
• stellar asset -> ethereum withdrawal
• xlm -> ethereum refund
• stelalr asset -> ethereum refund

We should test both the happy path and error conditions

FPP: Multisig coordination of Stellar tx signing

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

Implement Stellar -> Ethereum withdrawal endpoint

If a user initiates a bridge transfer from stellar to ethereum there should be an endpoint to withdraw the wrapped assets from the ethereum bridge smart contract

Implement bridge UI

Implement Ethereum -> Stellar refund endpoint

If a user initiates a bridge transfer from ethereum to stellar there should be an endpoint to refund the Ethereum deposit

Write a blog post about intent and high-level design

Add unit tests for validator

Components that should be unit tested:

• stellar observer
• stellar signer
• backend worker
• db store
• ethereum observer
• ethereum signer
• all controllers

FPP: Transactions component

What problem does your feature solve?

Starbridge should be able to interact with transactions on each connected blockchain (Stellar and Ethereum).

You can think of this as the piece that is responsible for doing the actual interactions with the connected blockchains. These can be expanded into separate components in the future as complexity increases, however they have been clubbed together at the early stage of this project for simplicity.

What would you like to see?

Monitoring Service

The Monitoring service will be run in the background constantly monitoring for transfer requests (payments) from each connected network. It will trigger a registered handler with the transaction data and hash when it receives a payment.

Submission

The Submission logic will submit a provided transaction to the destination network
We are skipping this step here since it is handled by the multisig component (#7) for now

TxStatus

The TxStatus logic will fetch the status of a given transaction hash on a network in a synchronous manner

What alternatives are there?

Put this inside the orchestrator code and bloat that component.

Possible DoS for Stellar withdrawals

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 #68 (comment)

Implement Stellar -> Ethereum refund endpoint

If a user initiates a bridge transfer from stellar to ethereum there should be an endpoint to refund the Stellar deposit

SeqNum for Stellar should be stored rather than pulled from Horizon

💭 I think the sequence number should be stored rather than pulled from Horizon. I'm a little worried we're relying on submission to have taken place for this seq num to be correct, since it will only be updated on Horizon if the last one was submitted.

I was thinking we could specify a starting sequence number as a parameter on boot and the service could work out, somehow, what sequence number it should be up to based on the next message it sees. Is there anything in the Ethereum message/event that we could use for that?

Originally posted by @leighmcculloch in #30 (comment)