Skip to content

Fix README and .env.example accuracy #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gyorgybalazsi wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Fix README and .env.example accuracy #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e537111
Fix README and .env.example accuracy issues
gyorgybalazsi Feb 26, 2026
5b9b643
Add note about bundled DAR packages in setup requirements
gyorgybalazsi Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 64 additions & 23 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,69 @@
# 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)
# =============================================================================

# 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
Expand All @@ -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)
Expand Down
50 changes: 28 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -164,15 +164,22 @@ 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...
DECENTRALIZED_PARTY_ID=cbtc-network::1220... # See environment-specific values below
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
Expand All @@ -182,26 +189,26 @@ 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

```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

```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
```

---
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -421,15 +432,16 @@ 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

#### `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`

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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/)