{"id":25293566,"url":"https://github.com/convex-dev/tokengine","last_synced_at":"2025-10-18T03:22:39.207Z","repository":{"id":276951578,"uuid":"924082363","full_name":"Convex-Dev/tokengine","owner":"Convex-Dev","description":"Token exchange for lattice ecosystems","archived":false,"fork":false,"pushed_at":"2025-04-02T12:15:30.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-02T13:23:08.732Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Convex-Dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-29T11:38:44.000Z","updated_at":"2025-04-02T12:15:41.000Z","dependencies_parsed_at":"2025-03-07T12:23:35.522Z","dependency_job_id":"dac7596f-1fd5-4ad0-b49f-eadf3f6159b0","html_url":"https://github.com/Convex-Dev/tokengine","commit_stats":null,"previous_names":["convex-dev/tokengine"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Ftokengine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Ftokengine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Ftokengine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Convex-Dev%2Ftokengine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Convex-Dev","download_url":"https://codeload.github.com/Convex-Dev/tokengine/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247543606,"owners_count":20955865,"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-13T01:54:45.575Z","updated_at":"2025-10-18T03:22:39.202Z","avatar_url":"https://github.com/Convex-Dev.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TokEngine\n\nTokEngine implements Cross-DLT Token exchange using Lattice Technology and [Convex](https://convex.world)\n\nThe official [TokEngine repository](https://github.com/Convex-Dev/tokengine) is hosted on GitHub\n\n## Fundamentals:  Atomic Exchange\n\nThe core of TokEngine is an atomic state machine that verifies incoming payments and produces outgoing transactions.\n\nKey features:\n- High performance asynchronous API server\n- Connectivity to multiple source DLTs\n- Use of CAIP standards to allow specification of token assets on any DLT \n- Supports any fungible tokens that can be transferred using verifiable DLT transactions\n- Verification of incoming payments on source DLTs, according to operator-defined security levels\n- Atomic update of user balance + record of incoming transaction. This gets logged (once) if successful\n- Atomic decrement of user balance for outgoing transaction\n\nTokEngine is designed to never create and store an inconsistent state, regardless of external failures.\n\n### Basic Operator usage\n\n1. Download or build `tokengine.jar` ([snapshots available here](https://drive.google.com/drive/folders/1AZdyuZOmC70i_TtuEW3uEKvjYLOqIMiv))\n2. Place a config file in your home directory at `~/.tokengine/config.json`\n3. Run using Java 21+ with `java -jar tokengine.jar`\n\nThis should launch the TokEngine server. By default, a simple web interface and API definitions are available on [localhost:8080](http://localhost:8080)\n\n### CAIP Definitions\n\n#### Chain ID\n\nA [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) Chain ID identifies a unique DLT network used by TokEngine\n\nExamples:\n\n- `convex:test` - Local Convex testnet\n- `eip155:11155111` - Ethereum Sepolia TestNet\n- `eip155:1` - Ethereum Mainnet\n\n#### Account ID\n\nA [CAIP-10](https://chainagnostic.org/CAIPs/caip-10) Account ID identifies a unique account on a DLT. It may be prefixed with the chain ID to specify which DLT the account is located on.\n\n- `eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb` - Account on Ethereum Mainnet\n- `convex:main:56756` - Account `#56756` on Convex main network\n- `bip122:000000000019d6689c085ae165831e93:128Lkh3S7CkDTBZ8W7BbpsN3YYizJMp8p6` - Bitcoin account\n\n#### Asset Type\n\nA [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) Asset Type identifies a token on a specific DLT\n\n- `eip155:1/slip44:60` - ETH on Ethereum Mainnet\n- `convex:main/slip44:864` - CVM on Convex main network\n- `eip155:11155111/erc20:0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` - USDC ERC20 Stablecoin on Sepolia Testnet\n\nNote use of SLIP-44 to define native tokens\n\n### Deposit\n\n0. User sends deposit on source DLT (client app)\n    - User sends tokens on source DLT to TokEngine operator receiver account\n    - User gets confirmed transaction ID (from source DLT)\n\n1. Validation (async)\n    - Validate API inputs for validity / correct format\n    - Validate that the asset specified is configured to receive deposits by the operator\n    - Validate that a deposit transaction has been correctly identified\n    - Log valid API request\n\n2. Verification stage (async)\n    - Verify transaction has been confirmed on source DLT\n    - If pending can wait for finality (optional)\n    - Verify transaction had triggered a deposit to the operator's receiver account\n\n3. Atomic update (sync)\n    - Check transaction has not already been atomically registered\n    - Perform atomic balance update\n    - Perform atomic registration of transaction as received\n    - Write state\n    - Create and write audit trail (if this fails, warning is logged but update is still safe)\n\n4. Confirmation (async)\n    - Return confirmation to API user\n\n### Withdraw\n\n1. Validation (async)\n    - Validate API inputs for validity / correct format\n    - Validate that the asset specified is configured to allow payouts by the operator\n    - Validate destination DLT address / specification\n    - Log valid API request\n\n2. Verification (async)\n    - Verify user has sufficient balance for payout (plus any fees)\n    - Verify signature on payout request\n    - Construct payout transaction (on dest DLT)\n\n3. Atomic prepare (sync)\n    - Record payout transaction (with ID for dest DLT)\n    - Lock payout amount from user\n    - Write state\n\n4. Transaction execution (async)\n    - Submit transaction to target DLT\n    - Return transaction ID to API caller\n    - Confirm completion of DLT payout transaction\n\n5. Atomic commit (sync, idempotent, can be retried)\n    - Check transaction not yet recorded as confirmed / failed\n    - Mark payout transaction as confirmed\n    - Decrement user balance (payout plus fees)\n    - Increment operator fee balance\n    - Write state\n    - Create and write audit trail (if this fails, warning is logged but update is still safe)\n\n6. Atomic rollback (sync, if transaction fails, idempotent, can be retired)\n    - Check transaction not yet recorded as confirmed / failed\n    - Record transaction as failed\n    - Decrement user balance (if any failure fees due)\n    - Increment operator fee balance (if any failure fees due)\n    - Unlock user funds\n    - Write state\n    - Create and write audit trail (if this fails, warning is logged but update is still safe)\n\n7. Confirmation (async polling by client app)\n    - Return confirmation / failure status to API user when polled\n\n### Transfer\n\nA transfer is a deposit plus withdraw flow in a single API call. All state updates are identical to a deposit+withdraw.\n\n## Tech notes\n\nThe design is intended to support high throughput concurrent usage:\n- Atomic sections are free of external interactions and generally run in-memory, completed in less than 1ms\n- All external operations are executed on lightweight virtual threads\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconvex-dev%2Ftokengine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconvex-dev%2Ftokengine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconvex-dev%2Ftokengine/lists"}