{"id":30703164,"url":"https://github.com/dfinity/cycles-ledger","last_synced_at":"2025-09-02T16:56:37.148Z","repository":{"id":210052110,"uuid":"649807679","full_name":"dfinity/cycles-ledger","owner":"dfinity","description":"The cycles ledger is a global ledger canister that enables principal IDs to hold cycles.","archived":false,"fork":false,"pushed_at":"2025-08-21T14:34:31.000Z","size":869,"stargazers_count":12,"open_issues_count":8,"forks_count":5,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-08-21T17:04:08.997Z","etag":null,"topics":["canister","cycles","icp","internet-computer","ledger","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/dfinity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-06-05T17:21:01.000Z","updated_at":"2025-08-21T08:35:04.000Z","dependencies_parsed_at":"2023-12-20T14:47:38.594Z","dependency_job_id":"459a02bc-7b1a-4664-bb9f-ac48b3a1107f","html_url":"https://github.com/dfinity/cycles-ledger","commit_stats":null,"previous_names":["dfinity/cycles-ledger"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/dfinity/cycles-ledger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fcycles-ledger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fcycles-ledger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fcycles-ledger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fcycles-ledger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dfinity","download_url":"https://codeload.github.com/dfinity/cycles-ledger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fcycles-ledger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273317765,"owners_count":25084037,"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","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["canister","cycles","icp","internet-computer","ledger","rust"],"created_at":"2025-09-02T16:56:34.906Z","updated_at":"2025-09-02T16:56:37.137Z","avatar_url":"https://github.com/dfinity.png","language":"Rust","readme":"# Cycles Ledger\n\nThe cycles ledger is a global ledger canister that enables principal IDs to hold cycles.\n\nThe cycles ledger complies with the [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) and [ICRC-1](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1/README.md) token standards.\nAdditionally, it implements the endpoints defined in the proposed [ICRC-3](https://github.com/dfinity/ICRC-1/pull/128) standard.\n\nThe cycles ledger further provides endpoints to deposit and withdraw cycles, and also\nto create canisters using cycles. The full specification can be found [here](INTERFACE_SPECIFICATION.md).\n\n## Cycles Ledger Canister\n\n### Principal\n```text\num5iw-rqaaa-aaaaq-qaaba-cai\n```\n\n[View on Internet Computer Dashboard](https://dashboard.internetcomputer.org/canister/um5iw-rqaaa-aaaaq-qaaba-cai)\n\n## Depositing Cycles\n\nThe cycles ledger has the following endpoint for other canisters to deposit cycles.\n\n```\ntype DepositArgs = record {\n  to : Account;\n  memo : opt vec nat8;\n};\n\ntype DepositResult = record { balance : nat; block_index : nat };\n\ndeposit : (DepositArgs) -\u003e (DepositResult);\n```\n\nWhen invoked with a particular account (and, optionally, a memo), the balance of the account is incremented by the number of cycles attached to the call, minus the transfer fee of 100M cycles. The number of cycles to deposit must be at least the transfer fee of **100M cycles**.\n\n\u003e NOTE: The deposit is rejected if fewer than 100M cycles are attached to the call.\n\n## Withdrawing Cycles\n\nThe cycles ledger has the following endpoint to withdraw cycles to other canisters.\n\n```\ntype BlockIndex = nat;\n\ntype RejectionCode = variant {\n  NoError;\n  CanisterError;\n  SysTransient;\n  DestinationInvalid;\n  Unknown;\n  SysFatal;\n  CanisterReject;\n};\n\ntype WithdrawArgs = record {\n    amount : nat;\n    from_subaccount : opt vec nat8;\n    to : principal;\n    created_at_time : opt nat64;\n};\n\ntype WithdrawError = variant {\n  GenericError : record { message : text; error_code : nat };\n  TemporarilyUnavailable;\n  FailedToWithdraw : record {\n    fee_block : opt nat;\n    rejection_code : RejectionCode;\n    rejection_reason : text;\n  };\n  Duplicate : record { duplicate_of : nat };\n  BadFee : record { expected_fee : nat };\n  InvalidReceiver : record { receiver : principal };\n  CreatedInFuture : record { ledger_time : nat64 };\n  TooOld;\n  InsufficientFunds : record { balance : nat };\n};\n\nwithdraw : (WithdrawArgs) -\u003e (variant { Ok : BlockIndex; Err : WithdrawError });\n```\n\nThe two required parameters are the amount to be sent and the principal ID of\nthe targeted canister ID. Optionally, the subaccount from which cycles are\ndeducted and the time at which the transaction is created can be set as well.\n\nThere is a fee of **100M cycles** for withdrawing cycles to another canister.\n\n\u003e NOTE: The function returns an error when the parameter `to` is not a valid canister ID.\n\n## Creating Canisters Using Cycles\n\nThe canister creation process via cycles can be triggered from the cycles ledger\nusing the endpoint `create_canister`.\n\n```\ntype CreateCanisterArgs = record {\n  from_subaccount : opt vec nat8;\n  created_at_time : opt nat64;\n  amount : nat;\n  creation_args : opt CmcCreateCanisterArgs;\n};\n\ntype CmcCreateCanisterArgs = record {\n  settings : opt CanisterSettings;\n  subnet_selection : opt SubnetSelection;\n};\n\ntype CanisterSettings = record {\n  controllers : opt vec principal;\n  compute_allocation : opt nat;\n  memory_allocation : opt nat;\n  freezing_threshold : opt nat;\n};\n\ntype SubnetFilter = record {\n  subnet_type : opt text;\n};\n\ntype SubnetSelection = variant {\n  /// Choose a specific subnet\n  Subnet : record {\n    subnet : principal;\n  };\n  Filter : SubnetFilter;\n};\n\ntype CreateCanisterError = variant {\n  InsufficientFunds : record { balance : nat };\n  TooOld;\n  CreatedInFuture : record { ledger_time : nat64 };\n  TemporarilyUnavailable;\n  Duplicate : record { duplicate_of : nat };\n  FailedToCreate : record {\n    fee_block : opt BlockIndex;\n    refund_block : opt BlockIndex;\n    error : text;\n  };\n  GenericError : record { message : text; error_code : nat };\n};\n\ncreate_canister : (CreateCanisterArgs) -\u003e (variant { Ok : CreateCanisterSuccess; Err : CreateCanisterError });\n```\n\nThe only parameter that must be provided is the number of cycles that should\nbe used for the canister creation.\nThe cycles ledger fee of **100M** cycles is deducted from the user's account\ntogether with the specified `amount`. The cycles ledger then sends the request to create a canister\nto the cycles minting canister, attaching `amount` cycles to the call.\nThe cost for the canister creation itself can be found\n[here](https://internetcomputer.org/docs/current/developer-docs/gas-cost).\n\n\u003e NOTE: The canister is created on a **random subnet** unless specified otherwise. `SubnetSelection`\ncan be used to specify a particular subnet or subnet type.\n\n## Build the cycles-ledger\n\nThe cycles-ledger should be built using the script [./scripts/docker-build](./scripts/docker-build). The script will put the `cycles-ledger.wasm.gz` in the directory where it was run.\n\n## Make a new Release\n\nThe CI job [release-with-github.yml](https://github.com/dfinity/cycles-ledger/actions/workflows/release-with-github.yml) is responsible to create a new release. The release job uses [cargo-release](https://github.com/crate-ci/cargo-release/blob/master/docs/reference.md). This project follows [Semantic Versioning 2.0.0](https://semver.org/) (aka semver).\n\nThe release job can be triggered by using [`gh`](https://cli.github.com/) or [directly from github](https://github.com/dfinity/cycles-ledger/actions/workflows/release-with-github.yml):\n\n```\ngh workflow run --repo dfinity/cycles-ledger \"release-with-github.yml\" -f semverBump=(major|minor|patch)\n```\n\nThe job will then bump the version based on the strategy passed via `semverBump`, make the release and make a PR with the version changes and the release linked to the PR. See [this](https://github.com/crate-ci/cargo-release/blob/master/docs/reference.md#bump-level) for valid `semverBump` values and their effect.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfinity%2Fcycles-ledger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdfinity%2Fcycles-ledger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfinity%2Fcycles-ledger/lists"}