Syscoin Core Developer Portal

Comprehensive guides and documentation to help you start working with Syscoin as quickly as possible, and support if you get stuck.

Get Started

HOWTO: Provision the Bridge for Your ERC-20

This guide is for adding a token to the Syscoin Bridge. Reach out to us via the Syscoin Community Wiki if you need assistance or further information during this process.

This is a full walk-through for provisioning Syscoin Bridge to operate with any particular Standard ERC-20. At the end of this walk-through you will have established the necessary components to enable sending your chosen ERC-20 from Ethereum to Syscoin Platform in order to leverage benefits like scalable microtransactions and Bitcoin-core-compliant security. You will also be able to move them back to Ethereum as needed. You can also keep a quantity of tokens present on both sides for maximum convenience.


You are encouraged to use the Syscoin 4.x Testnet prior to Mainnet implementation of your ERC-20 bridge.

Syscoin Bridge is fully functional between the Syscoin Testnet and the Ethereum Rinkeby Testnet.

Follow these instructions to get started with the Syscoin Testnet.
Read the Testnet FAQ.
A Testnet implementation of the Sysethereum Dapp is available at

Follow each step closely.
These instructions apply to both mainnet and testnet implementations.

1. Assess the ERC-20 token spec and note the relevant attributes

Use to view the token spec of your ERC-20.

Note the following.

  • Max supply (if specified - otherwise total circulating supply)
  • Precision
  • Token contract address

These will be used when creating your Syscoin Platform Token. In most cases the SPT max supply and precision attributes should be equal or as close as possible to those of the ERC-20 spec. An SPT with a max of 8 decimals of precision can have a max supply of up to 9,999,999,999 tokens. Your bridge will still work if these attributes cannot be configured identically, but it is best to be as close as possible to the ERC-20, especially if your are planning this token bridge for public use.

Make sure the ERC-20 conforms to the ERC-20 Standard, evidenced by the following functions being present in the smart contract: approve, transferFrom, allowance, balanceOf. The vast majority of tokens do conform. However, tokens such as KuCoin Shares and a limited number of older ERC-20s which do not conform, might not work properly with Syscoin Bridge. Tether USD is one exception of an older non-Standard token which does work.

2. Generate a new Syscoin address and send funds to it

Open your Syscoin console and issue the following command
getnewaddress "Enter your address label here"

This will output your new Syscoin address. Note it for later use.

Now use your wallet to send at least 502 SYS to this new address. The cost of creating a new SPT as of the date of this document is 500 SYS, plus 2 because we will need a little extra to fund some additional transactions. Wait until your transaction of 502 SYS has at least one confirmation, then proceed to the next step.

3. Define and create your Syscoin Platform Token (SPT)

We will now define then create the SPT using the assetnew command.


Create a new asset

1. address                  (string, required) An address that you own.
2. symbol                   (string, required) Asset symbol (1-8 characters)
3. description              (string, required) Public description of the token.
4. contract                 (string, required) Ethereum token contract for SyscoinX bridge. Must be in hex and not include the '0x' format tag. For example contract '0xb060ddb93707d2bc2f8bcc39451a5a28852f8d1d' should be set as 'b060ddb93707d2bc2f8bcc39451a5a28852f8d1d'. Leave empty for no smart contract bridge.
5. precision                (numeric, required) Precision of balances. Must be between 0 and 8. The lower it is the higher possible max_supply is available since the supply is represented as a 64 bit integer. With a precision of 8 the max supply is 10 billion.
6. total_supply             (numeric or string, required) Initial supply of asset. Can mint more supply up to total_supply amount or if total_supply is -1 then minting is uncapped.
7. max_supply               (numeric or string, required) Maximum supply of this asset. Set to -1 for uncapped. Depends on the precision value that is set, the lower the precision the higher max_supply can be.
8. update_flags             (numeric, required) Ability to update certain fields. Must be decimal value which is a bitmask for certain rights to update. The bitmask represents 0x01(1) to give admin status (needed to update flags), 0x10(2) for updating public data field, 0x100(4) for updating the smart contract field, 0x1000(8) for updating supply, 0x10000(16) for being able to update flags (need admin access to update flags as well). 0x11111(31) for all.
9. aux_fees                 (json object, required) Auxiliary fee structure
       "address": "str",    (string, required) Address to pay auxiliary fees to
       "fee_struct": [      (json array, required) Auxiliary fee structure
         "",                (string) Bound (in amount) for for the fee level based on total transaction amount
         "",                (string) Percentage of total transaction amount applied as a fee
10. witness                 (string, required) Witness address that will sign for web-of-trust notarization of this transaction.

The primary attributes related to Syscoin Bridge functionality are [contract], [precision], [total_supply] and [max_supply].

[contract] should be set to the ERC-20 token contract address, omitting the leading '0x' (e.g. '0xb060ddb93707d2bc2f8bcc39451a5a28852f8d1d' should be set as 'b060ddb93707d2bc2f8bcc39451a5a28852f8d1d').

[precision] should be set identical to that of the ERC-20, or as close as possible.

[total_supply] should be set identical to the max supply of the ERC-20, or as close as possible. Yes, the ERC-20 max supply, not the circulating supply.

[max_supply] should likewise be set identical to the max supply of the ERC-20, or as close as possible.



You can define a custom fee structure for your token. Learn about aux_fees and how to implement them.

In our assetnew example below we are making an SPT for the FunFair ERC-20 token.

  • The supply and precision attributes are set as close as possible to the ERC-20.
  • [address] is the Syscoin address from Step 2 that will own the token spec.
  • For now we are setting [update_flags] to 31 (fully update-able token spec). This can be changed later to "lock-down" or trust-minimize the token spec prior to public use. This will be covered later in this guide.
  • [aux_fees] and [witness] (the two arguments at the end) are left blank in this example. These are optional.
> assetnew sys1qn5ls49y3lsglzzu2m4dmdprny0zx4s228ewq4n "FUNx" "FunFair Interchain Token" 419D0d8BdD9aF5e606Ae2232ed285Aff190E711b 8 9999999999 9999999999 31 {} ""

Once you have defined your assetnew command and checked it thoroughly, you may execute the command.

After executing, the output will consist of a raw unsigned transaction (hex), and the [asset_guid] of your soon-to-be SPT. Note [asset_guid] for later use.

Now unlock your wallet in order to sign and send this raw transaction. Unlocking is done by using the command walletpassphrase YOUR_PASSPHRASE_HERE 600. The 600 is how many seconds the wallet will remain unlocked. Set as needed but be conservative for security sake. You can reissue this command if walletpassphrase expires, and you can manually re-lock your wallet using walletlock.

Now copy the raw unsigned transaction (hex) from the assetnew output (omitting quotes) and paste into the following command.
signrawtransactionwithwallet PASTE_HERE

Execute the command. The signrawtransactionwithwallet command will output the signed transaction (hex). Copy this (again, omitting quotes) and paste into the following command.
sendrawtransaction PASTE_HERE

Execute the command to send your transaction across the network. The output presented here should be your transaction id. Note this transaction id for later use.

After this transaction has at least one confirmation you can execute the following command to review your SPT spec as it is present on the Syscoin blockchain.
assetinfo [asset_guid]

It should look similar to this and reflect the attributes you set in assetnew:

> assetinfo 490411102
  "asset_guid": 490411102,
  "symbol": "FUNx",
  "txid": "341af480b61361386a8b63edabc5cecbbc16799c043ca15058eb654bb07dcf74",
  "public_value": "{\"description\":\"FunFair Interchain Token\"}",
  "address": "sys1qn5ls49y3lsglzzu2m4dmdprny0zx4s228ewq4n",
  "contract": "0x419d0d8bdd9af5e606ae2232ed285aff190e711b",
  "balance": 0.00000000,
  "total_supply": 9999999999.00000000,
  "max_supply": 9999999999.00000000,
  "update_flags": 31,
  "precision": 8

4. Mint and burn the entire SPT supply

The entire SPT supply needs to be minted and burned by you, the owner, as part of securing the supply characteristics of this SPT that will be used with Syscoin Bridge. After this, only the bridge process will handle minting the SPT (based on burn proofs), not the SPT spec owner.

4.a. First, we need to mint the entire supply using assetsend.

Specify your new [asset_guid] which you noted in Step 3. For [address], enter the address you noted from Step 2 which is the address that owns the SPT spec you just created. For [amount], enter the same value used for max_supply.

> assetsend 490411102 sys1qn5ls49y3lsglzzu2m4dmdprny0zx4s228ewq4n 9999999999

Once you have double-checked and executed the command, the output will once again be your raw unsigned transaction (hex). Now once again make sure your wallet is unlocked so you can sign and send the transaction. Paste the hex (omitting quotes) into the following command.
signrawtransactionwithwallet PASTE_HERE

Then copy and paste the new hex output of signrawtransactionwithwallet into
sendrawtransaction PASTE_HERE

Once executed, your transaction is sent and you should have your transaction id. Wait for this transaction to have at least one confirmation, then proceed.

4.b. Second, we need to burn the entire minted supply using assetallocationburn

Specify the same [asset_guid], Syscoin [address] and [amount] specified in Step 4.a.. For the Ethereum address, specify your own Ethereum address or the address of the ERC-20 contract you are bridging with (in the context of provisioning, the Ethereum address used here is arbitrary but must be populated to execute the command), but omit the leading '0x'.

> assetallocationburn 490411102 sys1qn5ls49y3lsglzzu2m4dmdprny0zx4s228ewq4n 9999999999 0763e1D872f2D72dD75F1ea1630DDa726aCa3FAB

Once you have double-checked and executed the command, the output will once again be your raw unsigned transaction (hex). Now once again make sure your wallet is unlocked so you can sign and send the transaction. Paste the hex (omitting quotes) into the following command.
signrawtransactionwithwallet PASTE_HERE

Then copy and paste the new hex output of signrawtransactionwithwallet into
sendrawtransaction PASTE_HERE

Once executed, your transaction is sent and you should have your transaction id. Wait for this transaction to have at least one confirmation, then proceed to Step 5.

5. Add your SPT to the Syscoin Bridge Asset Registry

In order to use the bridge from ETH->SYS, the SPT needs to be registered in the ERC20Manager contract so it knows the relationship between the SPT and the ERC-20 token contract. Using Asset Registry accomplishes this. This process requires an Ethereum web wallet such as Metamask. We recommend Metamask.

Head to the Sysethereum Dapp and click the 'Asset Registry' button.

The contract must receive a valid Syscoin transaction id representing when the SPT was created or when the [contract] field was last changed - whichever is most recent.

In our case this is the transaction id of our assetnew transaction sent in Step 3. Paste it into the Transaction ID field, then click 'Update Registry'.


"Superblock has not been stored in local database yet" or "Superblock has not been approved yet"

New Syscoin superblocks settle on Ethereum about every three hours. During that time Agents are building, submitting and challenging other pending superblocks to secure the bridge. This means to Register the SPT you need to wait at least three hours from the time your SPT was created (or from the time that the SPT's contract field was last updated), then try again.

Once your superblock is available and you submit the transaction id, your Ethereum web wallet will present you with transaction authorization requests. Review and confirm/authorize these requests.

Wait for these contract transactions to confirm on the Ethereum network. Then you should be able to perform a look-up of your SPT's registry entry by entering the Asset GUID in the search box. Verify the correct ERC20 Token Contract address is shown. In which case, congratulations! Your SPT is registered for use with Syscoin Bridge!

You may now proceed to and click the 'ETH -> SYS' button to send your ERC-20 across Syscoin Bridge for the first time!


What if I update my SPT with a different ERC-20 contract address?

In this case you should re-register the asset using the transaction id of your assetupdate, following the same process above.

6. Trust-minimize the SPT


Exercise diligence before locking-down any attribute(s) of your SPT spec

Changing [update_flags] can be irreversible depending on the value set. Prior to doing this, make sure your SPT is fully configured as it should be, including [aux_fees] and other attributes. Make sure you understand the implications for your SPT, and the bitmask values, what they represent, and how to use them before doing this. Refer to help assetupdate in the console for further information. You can also reach out to the Syscoin Community at the Syscoin Community Wiki for information and/or assistance.

Technically this step is optional. However, you should consider making your SPT trust-reduced before you make your bridge available to others as a service. Trust reduction can be done by issuing an assetupdate transaction to change the [update_flags] attribute of your SPT. The most important aspect of this is rendering your SPT's total_supply immutable. At your discretion you might choose to likewise lock-down the [contract] field for maximum trust-minimization. Refer to help assetupdate for further information.

Using any of the following values in update_flags values will result in a locked total_supply and will also lock update_flags to prevent the token spec update privilege from being added again in the future:


Setting update_flags to any of the following values is irreversible.

0 - No part of the token spec can updated. Entire token spec is immutable.
2 - Only public_value (description, aux_fees) can be updated
4 - Only contract can be updated
6 - Only public_value (description, aux_fees) and contract can be updated

Updated 7 months ago

HOWTO: Provision the Bridge for Your ERC-20

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.