Plasma bridge

Note

Just in case you wanna do it: you can adjust used client implementations.

from matic import utils
from myimpl import MyOtherWeb3ClientClass

utils.Web3Client = MyOtherWeb3ClientClass

This client must conform with existing BaseWeb3Client (and use implementations of other abstracts from that file).

Note

You can also adjust ABI url used by this library. You can do it in any of two ways:

Set environmental variable (export MATIC_ABI_STORE=... or via .env file, if you load it);

Set value in python code directly:

from matic import services
services.DEFAULT_ABI_STORE_URL = '...'
# See .env.example for one of possible URLs

Warning

In order to use methods of withdraw_exit_faster family, you need to set default proof API URI. You can do it in any of two ways:

Set environmental variable (export MATIC_PROOF_API=... or via .env file, if you load it);

Set value in python code directly:

from matic import services
services.DEFAULT_PROOF_API_URL = '...'
# See .env.example for one of possible URLs

Bridge

Classes:

`PlasmaClient`	Plasma bridge client.
`ERC20`	ERC-20-compliant token on plasma bridge.
`ERC721`	ERC-721-compliant token on plasma bridge.

class matic.plasma.PlasmaClient(config: matic.json_types.IPlasmaClientConfig)[source]

Bases: matic.utils.bridge_client.BridgeClient[matic.json_types.IPlasmaClientConfig]

Plasma bridge client.

Used to manage instantiation of matic.plasma.erc_20.ERC20 and matic.plasma.erc_721.ERC721 and perform some common operations.

Attributes:

`registry`	Registry contract instance.
`deposit_manager`	Deposit manager instance.
`withdraw_manager`	Withdraw manager instance.

Methods:

`erc_20`	Instantiate `ERC20` for token address.
`erc_721`	Instantiate `ERC721` for token address.
`withdraw_exit`	Perform withdraw exit.
`deposit_ether`	Deposit given amount of ether to polygon chain.

registry: RegistryContract: Registry contract instance.

deposit_manager: DepositManager: Deposit manager instance.

exit_util: ExitUtil[_C]

Helper class for exit data building.

Should be set after instantiation to prevent cycles.

withdraw_manager: WithdrawManager: Withdraw manager instance.

client: Web3SideChainClient[_C]: Actual connecting client.

erc_20(token_address: Optional[eth_typing.evm.HexAddress], is_parent: bool = False) → matic.plasma.erc_20.ERC20[source]

Instantiate ERC20 for token address.

Parameters

token_address – address where token contract is deployed.
is_parent – Whether this belongs to parent or child chain.

erc_721(token_address: eth_typing.evm.HexAddress, is_parent: bool = False) → matic.plasma.erc_721.ERC721[source]

Instantiate ERC721 for token address.

Parameters

token_address – address where token contract is deployed.
is_parent – Whether this belongs to parent or child chain.

withdraw_exit(tokens: Union[eth_typing.evm.HexAddress, Iterable[eth_typing.evm.HexAddress]], private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Perform withdraw exit.

deposit_ether(amount: int, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Deposit given amount of ether to polygon chain.

class matic.plasma.ERC20(token_address: eth_typing.evm.HexAddress, is_parent: bool, client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], contracts: Callable[[], matic.json_types.IPlasmaContracts])[source]

Bases: matic.plasma.plasma_token.PlasmaToken

ERC-20-compliant token on plasma bridge.

Attributes:

`WITHDRAW_EXIT_SIGNATURE`	Withdraw event signature, used for exit methods.
`predicate`	Get predicate contract for token.

Methods:

`get_balance`	Get user balance.
`get_allowance`	Get allowance for the user.
`approve`	Approve spender to spend some tokens.
`approve_max`	Approve spender to spend all tokens.
`deposit`	Deposit amount of token for user.
`withdraw_start`	Initialize withdrawal process.
`transfer`	Transfer given amount of token to another user.

WITHDRAW_EXIT_SIGNATURE: bytes = b'\xeb\xff&\x02\xb3\xf4h%\x9e\x1e\x99\xf6\x13\xfe\xd6i\x1f:e&\xef\xfen\xf3\xe7h\xbaz\xe7\xa3lO': Withdraw event signature, used for exit methods.

property predicate: matic.abstracts.BaseContract: Get predicate contract for token.

get_balance(user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.ITransactionOption] = None) → int[source]: Get user balance.

get_allowance(user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.IAllowanceTransactionOption] = None) → int[source]: Get allowance for the user.

approve(amount: int, private_key: Optional[str] = None, option: Optional[matic.json_types.IAllowanceTransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Approve spender to spend some tokens.

approve_max(private_key: Optional[str] = None, option: Optional[matic.json_types.IAllowanceTransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Approve spender to spend all tokens.

deposit(amount: int, user_address: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Deposit amount of token for user.

withdraw_start(amount: int, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Initialize withdrawal process.

transfer(amount: int, to: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Transfer given amount of token to another user.

class matic.plasma.ERC721(token_address: eth_typing.evm.HexAddress, is_parent: bool, client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], contracts: Callable[[], matic.json_types.IPlasmaContracts])[source]

Bases: matic.plasma.plasma_token.PlasmaToken

ERC-721-compliant token on plasma bridge.

Attributes:

`WITHDRAW_EXIT_SIGNATURE`	Withdraw event signature, used for exit methods.
`predicate`	Get predicate contract for token.

Methods:

`get_tokens_count`	Get tokens count for the user.
`get_token_id_at_index_for_user`	Returns token id on supplied index for user.
`safe_deposit`	Perform safeTransferFrom.
`withdraw_start`	Initialize withdrawal process.
`transfer`	Perform transfer to another address.
`get_all_tokens`	Get all token ids that belong to the given user.

WITHDRAW_EXIT_SIGNATURE: bytes = b'\x9b\x1b\xfa\x7f\xa9\xeeB\n\x16\xe1$\xf7\x94\xc3Z\xc9\xf9\x04r\xac\xc9\x91@\xeb/dG\xc7\x14\xca\xd8\xeb': Withdraw event signature, used for exit methods.

property predicate: matic.abstracts.BaseContract: Get predicate contract for token.

get_tokens_count(user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.ITransactionOption] = None) → int[source]: Get tokens count for the user.

get_token_id_at_index_for_user(index: int, user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.ITransactionOption] = None) → int[source]: Returns token id on supplied index for user.

safe_deposit(token_id: int, user_address: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Perform safeTransferFrom.

withdraw_start(token_id: int, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Initialize withdrawal process.

transfer(token_id: int, from_: eth_typing.evm.HexAddress, to: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Perform transfer to another address.

get_all_tokens(user_address: eth_typing.evm.HexAddress, limit: Optional[int] = None) → list[int][source]: Get all token ids that belong to the given user.

ERC 20 tokens

Classes:

ERC20

ERC-20-compliant token on plasma bridge.

class matic.plasma.erc_20.ERC20(token_address: eth_typing.evm.HexAddress, is_parent: bool, client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], contracts: Callable[[], matic.json_types.IPlasmaContracts])[source]

Bases: matic.plasma.plasma_token.PlasmaToken

ERC-20-compliant token on plasma bridge.

Attributes:

`WITHDRAW_EXIT_SIGNATURE`	Withdraw event signature, used for exit methods.
`predicate`	Get predicate contract for token.

Methods:

`get_balance`	Get user balance.
`get_allowance`	Get allowance for the user.
`approve`	Approve spender to spend some tokens.
`approve_max`	Approve spender to spend all tokens.
`deposit`	Deposit amount of token for user.
`withdraw_start`	Initialize withdrawal process.
`transfer`	Transfer given amount of token to another user.

WITHDRAW_EXIT_SIGNATURE: bytes = b'\xeb\xff&\x02\xb3\xf4h%\x9e\x1e\x99\xf6\x13\xfe\xd6i\x1f:e&\xef\xfen\xf3\xe7h\xbaz\xe7\xa3lO': Withdraw event signature, used for exit methods.

property predicate: matic.abstracts.BaseContract: Get predicate contract for token.

get_balance(user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.ITransactionOption] = None) → int[source]: Get user balance.

get_allowance(user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.IAllowanceTransactionOption] = None) → int[source]: Get allowance for the user.

approve(amount: int, private_key: Optional[str] = None, option: Optional[matic.json_types.IAllowanceTransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Approve spender to spend some tokens.

approve_max(private_key: Optional[str] = None, option: Optional[matic.json_types.IAllowanceTransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Approve spender to spend all tokens.

deposit(amount: int, user_address: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Deposit amount of token for user.

withdraw_start(amount: int, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Initialize withdrawal process.

transfer(amount: int, to: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Transfer given amount of token to another user.

ERC 721 tokens

Warning

Please don’t feel upset if you cannot withdraw ERC-721 from Mumbai to Goerli. I cannot too.

ERC721PredicateBurnOnly contract was deployed with wrong (?) WithdrawManager address (see on etherscan), so all transactions with WithdrawManager for ERC721 fail.

I tried deploying separate contract with this fixed (just a copy via Remix), and everything is OK until checkPredicateAndTokenMapping modifier check fires on WithdrawManager (and this failure is 100% valid, since my contract is not acknowledged as proper ERC721 predicate). Proper addresses are DepositManagerProxy and WithdrawManagerProxy values from ABI index.

For further investigation, contracts can be found in this repo.

Classes:

ERC721

ERC-721-compliant token on plasma bridge.

class matic.plasma.erc_721.ERC721(token_address: eth_typing.evm.HexAddress, is_parent: bool, client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], contracts: Callable[[], matic.json_types.IPlasmaContracts])[source]

Bases: matic.plasma.plasma_token.PlasmaToken

ERC-721-compliant token on plasma bridge.

Attributes:

`WITHDRAW_EXIT_SIGNATURE`	Withdraw event signature, used for exit methods.
`predicate`	Get predicate contract for token.

Methods:

`get_tokens_count`	Get tokens count for the user.
`get_token_id_at_index_for_user`	Returns token id on supplied index for user.
`safe_deposit`	Perform safeTransferFrom.
`withdraw_start`	Initialize withdrawal process.
`transfer`	Perform transfer to another address.
`get_all_tokens`	Get all token ids that belong to the given user.

WITHDRAW_EXIT_SIGNATURE: bytes = b'\x9b\x1b\xfa\x7f\xa9\xeeB\n\x16\xe1$\xf7\x94\xc3Z\xc9\xf9\x04r\xac\xc9\x91@\xeb/dG\xc7\x14\xca\xd8\xeb': Withdraw event signature, used for exit methods.

property predicate: matic.abstracts.BaseContract: Get predicate contract for token.

get_tokens_count(user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.ITransactionOption] = None) → int[source]: Get tokens count for the user.

get_token_id_at_index_for_user(index: int, user_address: eth_typing.evm.HexAddress, option: Optional[matic.json_types.ITransactionOption] = None) → int[source]: Returns token id on supplied index for user.

safe_deposit(token_id: int, user_address: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Perform safeTransferFrom.

withdraw_start(token_id: int, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Initialize withdrawal process.

transfer(token_id: int, from_: eth_typing.evm.HexAddress, to: eth_typing.evm.HexAddress, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Perform transfer to another address.

get_all_tokens(user_address: eth_typing.evm.HexAddress, limit: Optional[int] = None) → list[int][source]: Get all token ids that belong to the given user.

Helper contracts interaction

Classes:

`DepositManager`	Deposit manager for plasma bridge.
`ErcPredicate`	ERC predicate contract for plasma bridge.
`RegistryContract`	Registry contract for plasma bridge.
`WithdrawManager`	Withdraw manager for plasma bridge.

class matic.plasma.contracts.DepositManager(client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], address: eth_typing.evm.HexAddress)[source]

Bases: matic.utils.base_token.BaseToken[matic.json_types.IPlasmaClientConfig]

Deposit manager for plasma bridge.

class matic.plasma.contracts.ErcPredicate(client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], address: eth_typing.evm.HexAddress, contract_name: str)[source]

Bases: matic.utils.base_token.BaseToken[matic.json_types.IPlasmaClientConfig]

ERC predicate contract for plasma bridge.

class matic.plasma.contracts.RegistryContract(client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], address: eth_typing.evm.HexAddress)[source]

Bases: matic.utils.base_token.BaseToken[matic.json_types.IPlasmaClientConfig]

Registry contract for plasma bridge.

class matic.plasma.contracts.WithdrawManager(client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], address: eth_typing.evm.HexAddress)[source]

Bases: matic.utils.base_token.BaseToken[matic.json_types.IPlasmaClientConfig]

Withdraw manager for plasma bridge.

Methods:

withdraw_exit

Finish withdrawal process for given token(s).

withdraw_exit(tokens: Union[eth_typing.evm.HexAddress, Iterable[eth_typing.evm.HexAddress]], private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Finish withdrawal process for given token(s).

Base plasma token

Classes:

PlasmaToken

Base class for all tokens based on plasma bridge protocol.

class matic.plasma.plasma_token.PlasmaToken(address: eth_typing.evm.HexAddress, is_parent: bool, name: str, client: matic.utils.web3_side_chain_client.Web3SideChainClient[matic.json_types.IPlasmaClientConfig], get_helper_contracts: Callable[[], matic.json_types.IPlasmaContracts])[source]

Bases: abc.ABC, matic.utils.base_token.BaseToken[matic.json_types.IPlasmaClientConfig]

Base class for all tokens based on plasma bridge protocol.

Attributes:

`WITHDRAW_EXIT_SIGNATURE`	Withdraw event signature, used for exit methods.
`predicate`	Get predicate contract for token.

Methods:

`withdraw_exit`	Complete withdraw process.
`withdraw_confirm`	Continue withdraw process.
`withdraw_confirm_faster`	Continue withdraw process with fast proof.

WITHDRAW_EXIT_SIGNATURE: bytes: Withdraw event signature, used for exit methods.

withdraw_exit(private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Complete withdraw process.

abstract property predicate: matic.abstracts.BaseContract: Get predicate contract for token.

withdraw_confirm(burn_tx_hash: bytes, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Continue withdraw process.

withdraw_confirm_faster(burn_tx_hash: bytes, private_key: Optional[str] = None, option: Optional[matic.json_types.ITransactionOption] = None) → matic.json_types.ITransactionWriteResult[source]: Continue withdraw process with fast proof.