{"id":25249547,"url":"https://github.com/provable-things/ptokens-core","last_synced_at":"2025-10-26T22:31:18.304Z","repository":{"id":45353592,"uuid":"245261271","full_name":"provable-things/ptokens-core","owner":"provable-things","description":"The core component which makes pTokens bridges work","archived":false,"fork":false,"pushed_at":"2022-04-30T21:46:28.000Z","size":6534,"stargazers_count":18,"open_issues_count":1,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-08T22:21:12.137Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/provable-things.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-05T20:29:11.000Z","updated_at":"2024-03-21T19:52:21.000Z","dependencies_parsed_at":"2022-07-20T15:32:32.498Z","dependency_job_id":null,"html_url":"https://github.com/provable-things/ptokens-core","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provable-things%2Fptokens-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provable-things%2Fptokens-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provable-things%2Fptokens-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provable-things%2Fptokens-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/provable-things","download_url":"https://codeload.github.com/provable-things/ptokens-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238405182,"owners_count":19466450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-12T03:22:29.254Z","updated_at":"2025-10-26T22:31:12.309Z","avatar_url":"https://github.com/provable-things.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :closed_lock_with_key: pTokens Core\n\nThe Provable __pTokens__ core which manages the cross-chain conversions between a host and a native blockchain.\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n## :earth_africa: Core Overview\n\nThe __pToken__ core is a library implementing light-clients for various block-chains. The initial release involves __ETH__ as the host chain on which the __pTokens__ are manifest, and uses __BTC__ as the native chain and underlying asset.\n\nThe core library has zero network connectivity and makes no network requests. It is a push-only model, requiring external tools to gather \u0026 feed it the blocks from the chains with which the core is to interact.\n\nIn order to initialize the light-clients inside the core, an initial block from each desired chain is required. These will be the only trusted blocks in the system. Thereafter, subsequent blocks pushed to the core will undergo all the usual validation checks w/r/t to that block's veracity before appending it to the small piece of chain the light client holds.\n\nThe length of these small pieces of chain held by the core is governed by its __`canon-to-tip`__ length, which length can also be thought of as the number of __`confirmations + 1`__ required before the core will sign a transaction.\n\nOnce a block reaches __`canon-to-tip`__ number of blocks away from the tip of the chain, it becomes the __`canon-block`__. At this point, it is searched for any relevant deposit or redemption events and any required transactions are then signed and returned from the core in __`JSON`__ format.\n\nIn order to keep the light-clients thin, blocks behind the __`canon-block`__  are removed. In order to do that whilst retaining the integrity of the chain, the block to be removed is first _linked_ to the initial trusted block (the __`anchor-block`__) by hashing it together with the so-called __`linker-hash`__ (where an arbitrary constant is used for the first linkage) and the block to be removed. This way the small piece of chain inside then core can always be proven to have originated from the original trusted block.\n\nAnd so thusly the core remains synced with the each blockchain, writing relevant transactions as it does so.\n\n## :lock_with_ink_pen: Security:\n\nThe library herein is designed to be imported by an application that leverages an HSM in order to implement a secure database that adheres to the interface as defined in __`./src/traits.rs`__.\n\nThis library itself implements no such protections, except those afforded by the protected runtime of an __SGX__ environment if an __`app`__ were to leverage such technology.\n\nNote the library can be built in __`debug`__ mode via setting the feature flag when building thusly: __`cargo build --release --features=debug`__.  If built in __`debug`__ mode, all security of the app/core combination are waived entirely, the database is entirely accessible including the private keys!\n\n#### :warning: The core should NOT be used in `debug` mode in production! :warning:\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n\n## :point_right: API:\n\n### submit_eth_block_to_enclave\n\n```\n\npub fn submit_eth_block_to_enclave\u003cD\u003e(\n    db: D,\n    block_json_string: String\n) -\u003e Result\u003cString\u003e\n\n```\n\n❍ Submit an ETH block (\u0026 its receipts) to the enclave.  NOTE: The enclave must first have been initialized!\n\n➔ `blockJson` Format:\n\nA valid JSON string of an object containing the fields:\n\n`Block`    ➔ The block header itself.\n\n`Receipts` ➔ An array containing the block's receipts.\n\n***\n\n### submit_btc_block_to_enclave\n\n```\n\npub fn submit_btc_block_to_enclave\u003cD\u003e(\n    db: D,\n    block_json_string: String\n) -\u003e Result\u003cString\u003e\n\n```\n\n__Action:__\n\nSubmit a BTC block to the core.  The submission material must also include an array of deposit information for `p2sh` addresses.  NOTE: The core must first have been initialized!\n\n➔ `block_json_string` Format:\n\nA valid `JSON` string of an object containing the fields:\n\n`block`        ➔ The BTC block in `JSON` format.\n\n`transactions` ➔ The transactions in HEX format.\n\n`deposit_address_list` ➔ An array of objects:\n\n```\n\n  {\n    `nonce`: An integer nonce.\n    `eth_address`: The destination ETH address in hex.\n    `btc_deposit_address`: The `p2sh` BTC deposit address.\n    `eth_address_and_nonce_hash`: The `sha256d` of `eth_address + nonce`\n  }\n\n```\n\n***\n\n### maybe_initialize_eth_enclave\n\n```\n\npub fn maybe_initialize_eth_enclave\u003cD\u003e(\n    db: D,\n    block_json_string: String,\n    chain_id: u8,\n    gas_price: u64,\n    canon_to_tip_length: u64,\n) -\u003e Result\u003cString\u003e\n\n```\n\n__Action:__\n\nInitializes the core with the first trusted ETH block. Ensure the block has NO transactions relevant to the pToken in it, because they'll be ignored by the core. Transactions are not verified so you may omit them and include an empty array in their place if needs be. The core will initialize its ETH-related database from this trusted block, create the ETH private-key and seal it into the database. This command will return a signed transaction to broadcast, which transaction will deploy the pToken contract to the ETH network. The core's ETH address will first need to be funded with ETH before broadcasting the deployment transaction.\n\n➔ blocksJson Format:\n\nA valid `JSON` string of an object containing the fields:\n\n`block_json_string` ➔ A valid `JSON` string of and ETH block \u0026 receipts. See `submit_eth_block_to_enclave` for `JSON` format.\n\n***\n\n### maybe_initialize_btc_enclave\n\n```\n\npub fn maybe_initialize_btc_enclave\u003cD\u003e(\n    db: D,\n    block_json_string: String,\n    fee: u64,\n    difficulty: u64,\n    network: String,\n    canon_to_tip_length: u64,\n) -\u003e Result\u003cString\u003e\n\n```\n\n__Action:__\n\nInitializes the core with the first trusted BTC block. Ensure the block has NO transactions relevant to the pToken in it, because they'll be ignored by the core. Transactions are not verified so you may omit them and include an empty array in their place. The core will initialize its BTC related database from this trusted block, create the BTC private-key and seal it into the database.\n\n➔ blocksJson Format:\n\nA valid `JSON` string of an object containing the fields:\n\n`block_json_string` ➔ A valid `JSON` string of the BTC block \u0026 transactions. See `submit_btc_block_to_enclave` for `JSON` format.\n\n***\n\n### get_enclave_state\n\n```\n\npub fn get_enclave_state\u003cD\u003e(db: D) -\u003e Result\u003cString\u003e where D: DatabaseInterface\n\n```\n\nReturns the current state of the core as pulled from the database, omitting sensitive fields such as private-keys etc.\n\n***\n\n\n### debug_get_all_utxos\n\n```\n\npub fn debug_get_all_utxos\u003cD\u003e(db: D) -\u003e Result\u003cString\u003e\n\n```\n\nReturns `JSON` formatted report of all the `UTXO`s currently held in the database. This function can only be called if the core is build in `debug` mode.\n\n***\n\n### debug_get_key_from_db\n\n```\n\npub fn debug_get_key_from_db\u003cD\u003e(db: D, key: String) -\u003e Result\u003cString\u003e\n\n```\n\nGet a given \u003ckey\u003e from the database. This function can only be called if the core is built in `debug` mode.\n\n***\n\n### debug_get_key_from_db\n\n```\n\npub fn get_latest_block_numbers\u003cD\u003e(db: D) -\u003e Result\u003cString\u003e\n\n```\n\nReturns the current latest ETH \u0026 BTC block numbers seen by the core.\n\n***\n\n### debug_set_key_in_db_to_value\n\n```\n\npub fn debug_set_key_in_db_to_value\u003cD\u003e(db: D, key: String, value: String) -\u003e Result\u003cString\u003e\n\n```\n\nSet a given \u003ckey\u003e in the database to a given \u003cvalue\u003e. This function can only be called if the core is build in `debug` mode. Note there there are __NO__ checks on the what is passed in to the database. Use at own risk!\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n### :wrench: Build\n\n\nYou need to ensure you have both __`clang`__ \u0026 __`llvm`__ (or later versions) installed on your system. Then enter the __`./app`__ directory and run:\n\n__`❍ cargo build --release`__\n\n#### Versions\n\n - __`llvm:`__ version 6.0.0 or later.\n - __`clang:`__ version 6.0.0-1ubuntu2 or later.\n - __`rustc \u0026 cargo:`__ version 1.46.0 or later.\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n### :floppy_disk: Database Interface\n\nThe `core` implements a generic database whose interface follows:\n\n```\npub trait DatabaseInterface {\n    fn end_transaction(\u0026self) -\u003e Result\u003c()\u003e;\n    fn start_transaction(\u0026self) -\u003e Result\u003c()\u003e;\n    fn delete(\u0026self, key: Bytes) -\u003e Result\u003c()\u003e;\n    fn get(\u0026self, key: Bytes, data_sensitivity: Option\u003cu8\u003e) -\u003e Result\u003cBytes\u003e;\n    fn put(\u0026self, key: Bytes, value: Bytes, data_sensitivity: Option\u003cu8\u003e) -\u003e Result\u003c()\u003e;\n}\n\n```\n\nThe `start_transaction` and `end_transaction` are used by the core algorithms to signal when databasing actions begin and end, allowing a consumer of the `core` to implement atomic databasing however they wish.\n\nFurther, the `sensitivity` parameter provides a way for the `core` to signal to the consumer how sensitive the data being transmitted is, giving flexibility for the `core` consumer to handle different levels of sensitive data in different ways, where `0` signifies the _least_ sensitive data, and `255` the _most_.\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n### :black_nib: Notes\n\n- The eth ptoken smart-contract bytecode needs to be in the root of the directory of the binary when you run the ETH initialization step, as a file called: __`ptoken-erc777-bytecode`__.\n\n- The maximum __`confs`__ possible during initialization is 255.\n\n- There are hardcoded \"safe\" __ETH__ \u0026 __BTC__ addresses which are used as destinations for transactions whose actual destinations are absent or malformed when being parsed from their originating transactions.\n\n- When initializing the core, the merkle-roots inside the __ETH__ and __BTC__ blocks are __NOT__ verified - only the block headers are checked. For smaller initialiazation material, feel free to provide empty arrays for the transactions. Ensure not relevant transactions took place in the blocks used to initialize the core.\n\n- The light __BTC__ client implemented herein currently accepts only _two_ deposit types:\n\n1) `p2sh` deposits made to addresses generated via the __`deposit-address-generator`__ run with the private-key emitted by the core upon BTC initialization.\n2) `P2PKH` deposits that include in the transaction a UTXO to the `p2pkh` of the aforementioned private-key.\n\n:warning: Neither `p2pk` nor `segwit` transactions are currently supported. Deposits made via such transactions will result in lost funds! :warning:\n\n- The library follows semantic versioning specification ([SemVer](https://semver.org)).\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n### :mag: Features\n\nWhen importing this core library into your app, enable features in your __`Cargo.toml`__ like so:\n\n__`pbtc_core = { version = \"0.1.0\", features = [\"btc-on-eth\"] }`__.\n\nCurrently supported features include:\n\n - __`debug`__ To enable debug mode.\n\n - __`btc-on-eth`__ For the pBTC, BTC on ETH implementation.\n\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n### :guardsman: Tests\n\nTo run the tests simply run:\n\n__`❍ cargo test --features='\u003cchosen-feature\u003e'`__\n\n\u0026nbsp;\n\n***\n\n\u0026nbsp;\n\n### :black_nib: To Do:\n\n- [ ] Use enum for trie node types.\n- [ ] Needs method to adjust difficulty in future.\n- [ ] Pass in path of bytecode as arg to the initter.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprovable-things%2Fptokens-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprovable-things%2Fptokens-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprovable-things%2Fptokens-core/lists"}