From e5371111288eaa5e2519f62abf3e2cb6d28d1799 Mon Sep 17 00:00:00 2001 From: gyorgybalazsi Date: Thu, 26 Feb 2026 16:30:25 +0100 Subject: [PATCH 1/2] Fix README and .env.example accuracy issues - Fix API Reference: rename cbtc::withdraw to cbtc::cancel_offers, submit_multi to submit_sequential_chained, request_withdraw to submit_withdraw - Fix ATTESTOR_URL and CANTON_NETWORK values to match actual usage (dlc.link URLs, canton-devnet format) - Add missing Keycloak auth vars to Configuration section and .env.example - Remove broken links (context/ files, example_transfer.sh) - Fix cbtc dependency to branch=main, keycloak to tag=v0.3.0 - Add 4 missing examples to Core Operations table - Remove unused client_credentials from API Reference, add note about canton-lib availability - Add ENVIRONMENT, CONSOLIDATION, CONTRACT DELETION sections to .env.example Co-Authored-By: Claude Opus 4.6 --- .env.example | 87 ++++++++++++++++++++++++++++++++++++++-------------- README.md | 48 ++++++++++++++++------------- 2 files changed, 91 insertions(+), 44 deletions(-) diff --git a/.env.example b/.env.example index 71f1ea3..aa4ec68 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,30 @@ # Canton CBTC Library Configuration Example # Copy this file to .env and fill in your values +# ============================================================================= +# ENVIRONMENT +# ============================================================================= +# Which Canton environment to use: devnet, testnet, or mainnet +ENVIRONMENT=devnet + +# ============================================================================= +# KEYCLOAK / OIDC AUTHENTICATION (Required for all operations) +# ============================================================================= +# Your Keycloak/OIDC provider host URL +KEYCLOAK_HOST=https://keycloak.your-host.com + +# The realm name in your Keycloak instance +KEYCLOAK_REALM=your-realm + +# The client ID for your wallet/application +KEYCLOAK_CLIENT_ID=your-client-id + +# Username for password grant authentication +KEYCLOAK_USERNAME=your-username + +# Password for password grant authentication +KEYCLOAK_PASSWORD=your-password + # ============================================================================= # CORE CONFIGURATION (Required for all operations) # ============================================================================= @@ -8,11 +32,38 @@ # CANTON LEDGER # Your Canton participant node's ledger API host LEDGER_HOST=https://participant.example.com + # Your party ID on the Canton network PARTY_ID=your-party::1220abcdef... # ============================================================================= -# MINT & REDEEM OPERATIONS (Required for BTC ↔ CBTC bridging) +# SEND & TRANSFER OPERATIONS (Required for sending CBTC to other parties) +# ============================================================================= + +# CBTC NETWORK CONFIGURATION +# The decentralized party ID for CBTC (environment-specific) +# Devnet: cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff +# Testnet: cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f +# Mainnet: cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262 +DECENTRALIZED_PARTY_ID=cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff + +# Registry URL (environment-specific) +# Devnet: https://api.utilities.digitalasset-dev.com +# Testnet: https://api.utilities.digitalasset-staging.com +# Mainnet: https://api.utilities.digitalasset.com +REGISTRY_URL=https://api.utilities.digitalasset-dev.com + +# Optional: Transfer amount for send examples (default: 0.1) +TRANSFER_AMOUNT=0.1 + +# Optional: Amount per receiver for batch distribution +AMOUNT_PER_RECEIVER=0.00001000 + +# Optional: CSV file path for batch distribution (default: recipients.csv) +RECIPIENTS_CSV=recipients.csv + +# ============================================================================= +# MINT & REDEEM OPERATIONS (Required for BTC <-> CBTC bridging) # ============================================================================= # BITSAFE ATTESTOR NETWORK @@ -36,33 +87,23 @@ CANTON_NETWORK=canton-devnet DESTINATION_BTC_ADDRESS= # ============================================================================= -# SEND & TRANSFER OPERATIONS (Required for sending CBTC to other parties) +# STREAM EXAMPLE (for stream_cbtc example) # ============================================================================= +# RECEIVER_PARTY=receiver-party::1220... +# TRANSFER_COUNT=10 -# CBTC NETWORK CONFIGURATION -# The decentralized party ID for CBTC (environment-specific) -# Devnet: cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff -# Testnet: cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f -# Mainnet: cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262 -DECENTRALIZED_PARTY_ID=cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff - -# Registry URL (environment-specific) -# Devnet: https://api.utilities.digitalasset-dev.com -# Testnet: https://api.utilities.digitalasset-staging.com -# Mainnet: https://api.utilities.digitalasset.com -REGISTRY_URL=https://api.utilities.digitalasset-dev.com - -# Optional: Transfer amount for send examples (default: 0.1) -TRANSFER_AMOUNT=0.1 - -# Optional: CSV file path for batch distribution (default: recipients.csv) -RECIPIENTS_CSV=recipients.csv +# ============================================================================= +# CONTRACT DELETION (for delete_executed_transfers example) +# ============================================================================= +# CHOICE_CONTRACT_TEMPLATE_ID="#cbtc-governance:CBTC.Governance:CBTCGovernanceRules" +# CHOICE_CONTRACT_ID=your-governance-contract-id +# MAX_CONTRACTS=1000 +# KEYCLOAK_CLIENT_SECRET=your-client-secret # ============================================================================= -# STREAM EXAMPLE (for stream_cbtc example) +# CONSOLIDATION # ============================================================================= -# RECEIVER_PARTY=receiver-party::1220... -# TRANSFER_COUNT=10 +# CONSOLIDATION_THRESHOLD=10 # ============================================================================= # TESTING (for running integration tests) diff --git a/README.md b/README.md index fd311c6..fd884b1 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ Add to your `Cargo.toml`: ```toml [dependencies] cbtc = { git = "ssh://git@github.com/DLC-link/cbtc-lib", branch = "main" } -keycloak = { git = "ssh://git@github.com/DLC-link/canton-lib", branch = "main" } +keycloak = { git = "ssh://git@github.com/DLC-link/canton-lib", tag = "v0.3.0" } ``` Or for local development: @@ -164,6 +164,13 @@ cp .env.example .env Edit `.env` with your Canton participant node details: ```bash +# Keycloak / OIDC Authentication +KEYCLOAK_HOST=https://keycloak.your-host.com +KEYCLOAK_REALM=your-realm +KEYCLOAK_CLIENT_ID=your-client-id +KEYCLOAK_USERNAME=your-username +KEYCLOAK_PASSWORD=your-password + # Canton Network LEDGER_HOST=https://participant.example.com PARTY_ID=your-party::1220... @@ -171,8 +178,8 @@ DECENTRALIZED_PARTY_ID=cbtc-network::1220... # See environment-specific values REGISTRY_URL=https://api.utilities.digitalasset-dev.com # See environment-specific values below # CBTC Mint/Redeem (optional - only needed for BTC bridging) -ATTESTOR_URL=https://attestor.bitsafe.dev # See environment-specific values below -CANTON_NETWORK=devnet # or testnet/mainnet +ATTESTOR_URL=https://devnet.dlc.link/attestor-1 # See environment-specific values below +CANTON_NETWORK=canton-devnet # or canton-testnet/canton-mainnet ``` ### Environment-Specific Values @@ -182,8 +189,8 @@ CANTON_NETWORK=devnet # or testnet/mainnet ```bash DECENTRALIZED_PARTY_ID=cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff REGISTRY_URL=https://api.utilities.digitalasset-dev.com -ATTESTOR_URL=https://attestor.bitsafe.dev -CANTON_NETWORK=devnet +ATTESTOR_URL=https://devnet.dlc.link/attestor-1 +CANTON_NETWORK=canton-devnet ``` #### Testnet @@ -191,8 +198,8 @@ CANTON_NETWORK=devnet ```bash DECENTRALIZED_PARTY_ID=cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f REGISTRY_URL=https://api.utilities.digitalasset-staging.com -ATTESTOR_URL=https://attestor.bitsafe.testnet -CANTON_NETWORK=testnet +ATTESTOR_URL=https://testnet.dlc.link/attestor-1 +CANTON_NETWORK=canton-testnet ``` #### Mainnet @@ -200,8 +207,8 @@ CANTON_NETWORK=testnet ```bash DECENTRALIZED_PARTY_ID=cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262 REGISTRY_URL=https://api.utilities.digitalasset.com -ATTESTOR_URL=https://attestor.bitsafe.com -CANTON_NETWORK=mainnet +ATTESTOR_URL=https://mainnet.dlc.link/attestor-1 +CANTON_NETWORK=canton-mainnet ``` --- @@ -245,6 +252,10 @@ This library provides several high-level operations for working with CBTC tokens | **Stream CBTC** | [`stream.rs`](examples/stream.rs) | `cargo run --example stream_cbtc` | Stream CBTC to a single receiver multiple times | | **Batch Distribution** | [`batch_distribute.rs`](examples/batch_distribute.rs) | `cargo run --example batch_distribute` | Distribute to multiple recipients from CSV | | **Consolidate UTXOs** | [`consolidate_utxos.rs`](examples/consolidate_utxos.rs) | `cargo run --example consolidate_utxos` | Merge multiple UTXOs into one | +| **Check Withdrawals** | [`check_withdraw_requests.rs`](examples/check_withdraw_requests.rs)| `cargo run --example check_withdraw_requests`| Monitor pending BTC withdrawal requests | +| **List Deposit Addrs** | [`list_deposit_addresses.rs`](examples/list_deposit_addresses.rs) | `cargo run --example list_deposit_addresses` | List Bitcoin deposit addresses for your accounts | +| **List Contracts** | [`list_contracts.rs`](examples/list_contracts.rs) | `cargo run --example list_contracts` | List all active CBTC contracts | +| **Delete Transfers** | [`delete_executed_transfers.rs`](examples/delete_executed_transfers.rs) | `cargo run --example delete_executed_transfers` | Delete old executed transfer contracts | ### Key Concepts @@ -324,8 +335,8 @@ See [redeem_cbtc_flow.rs](examples/redeem_cbtc_flow.rs) for complete code. To use mint/redeem functionality, add these environment variables: ```bash -ATTESTOR_URL=https://attestor.bitsafe.dev # Bitsafe Attestor API -CANTON_NETWORK=devnet # or testnet/mainnet +ATTESTOR_URL=https://devnet.dlc.link/attestor-1 # Bitsafe Attestor API +CANTON_NETWORK=canton-devnet # or canton-testnet/canton-mainnet ``` ### Understanding UTXO Management @@ -376,13 +387,13 @@ See [batch_distribute.rs](examples/batch_distribute.rs) and [batch_with_callback #### `cbtc::transfer` - `submit(Params)` - Send CBTC to a single recipient -- `submit_multi(MultiParams)` - Send CBTC to multiple recipients in one transaction +- `submit_sequential_chained(SequentialChainedParams)` - Send CBTC to multiple recipients sequentially, chaining change outputs #### `cbtc::accept` - `submit(Params)` - Accept an incoming CBTC transfer -#### `cbtc::withdraw` +#### `cbtc::cancel_offers` - `withdraw_all(WithdrawAllParams)` - Withdraw all pending outgoing transfers - `submit(Params)` - Withdraw a specific transfer offer @@ -421,7 +432,7 @@ See [batch_distribute.rs](examples/batch_distribute.rs) and [batch_with_callback - `list_withdraw_accounts(Params)` - Get all withdraw accounts - `create_withdraw_account(Params)` - Create withdraw account with BTC destination - `list_holdings(Params)` - Get CBTC holdings for burning -- `request_withdraw(Params)` - Burn CBTC and request BTC withdrawal +- `submit_withdraw(SubmitWithdrawParams)` - Burn CBTC and request BTC withdrawal - `list_withdraw_requests(Params)` - Monitor withdrawal status ### Helper Modules @@ -429,7 +440,8 @@ See [batch_distribute.rs](examples/batch_distribute.rs) and [batch_with_callback #### `keycloak::login` - `password(PasswordParams)` - Authenticate with username/password -- `client_credentials(ClientCredentialsParams)` - Service account authentication + +> **Note**: This library uses username/password authentication. The underlying [canton-lib](https://github.com/DLC-link/canton-lib) also provides `client_credentials(ClientCredentialsParams)` for service account authentication if needed. #### `ledger` @@ -514,10 +526,6 @@ curl -X POST $REGISTRY_URL/api/token-standard/v0/registrars/$DECENTRALIZED_PARTY }' | jq ``` -### Submit Transfer - -See [example_transfer.sh](example_transfer.sh) for a complete example. - ### Accept Transfer ```bash @@ -695,7 +703,5 @@ MIT License - see [LICENSE](LICENSE) file for details ## Resources -- [Canton Token Standard (CIP-0056)](context/cip-0056.md) -- [Canton Coin Fee Removal (CIP-0078)](context/cip-0078-canton-coin-fee-removal.md) - [Canton Documentation](https://docs.digitalasset.com/canton) - [Canton Network](https://www.canton.network/) From 5b9b6436f37ab009079bad44112f52aeb191febf Mon Sep 17 00:00:00 2001 From: gyorgybalazsi Date: Thu, 26 Feb 2026 16:38:11 +0100 Subject: [PATCH 2/2] Add note about bundled DAR packages in setup requirements Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fd884b1..8327022 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ A Rust library for interacting with the Canton blockchain to manage CBTC (Canton > **Important Setup Requirements**: > - **For Send/Receive Operations**: The [Digital Asset Registry Utility](https://docs.digitalasset.com/utilities/mainnet/index.html) must be installed on your validator node -> - **For Mint/Redeem Operations**: Review the [CBTC Minting App Installation and User Guide](https://hub.bitsafe.finance/cbtc-minting-app-installation-and-user-guide) to install the required DAR files and configure permissions correctly +> - **For Mint/Redeem Operations**: Review the [CBTC Minting App Installation and User Guide](https://hub.bitsafe.finance/cbtc-minting-app-installation-and-user-guide) to install the required DAR files and configure permissions correctly. The DAR packages are bundled in the [`cbtc-dars/`](cbtc-dars/) directory for convenience — see its [README](cbtc-dars/README.md) for upload instructions. ---