{"id":13523646,"url":"https://github.com/tuminfei/ic_agent","last_synced_at":"2025-04-01T01:33:07.886Z","repository":{"id":157064853,"uuid":"626259666","full_name":"tuminfei/ic_agent","owner":"tuminfei","description":"Provide IC development tools for all developers of the Ruby programming language.","archived":false,"fork":false,"pushed_at":"2023-09-07T01:42:45.000Z","size":3994,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-20T12:03:14.630Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuminfei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-04-11T05:41:45.000Z","updated_at":"2023-08-10T06:40:10.000Z","dependencies_parsed_at":"2024-01-13T22:25:32.275Z","dependency_job_id":"adf76e0e-3bc4-460e-b5c5-79bf131debdf","html_url":"https://github.com/tuminfei/ic_agent","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuminfei%2Fic_agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuminfei%2Fic_agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuminfei%2Fic_agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuminfei%2Fic_agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuminfei","download_url":"https://codeload.github.com/tuminfei/ic_agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246567131,"owners_count":20798118,"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":"2024-08-01T06:01:02.185Z","updated_at":"2025-04-01T01:33:05.201Z","avatar_url":"https://github.com/tuminfei.png","language":"Ruby","funding_links":[],"categories":["Client Libraries (Agents)"],"sub_categories":["Ruby"],"readme":"# IcAgent\n\n## Ruby Agent Library for the Internet Computer\n\n`ic_agent` provides basic modules to interact with canisters on the DFINITY Internet Computer.\n\n[![Gem Version](https://badge.fury.io/rb/ic_agent.svg)](https://badge.fury.io/rb/ic_agent)[![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)\n\n\n## Installation\n\n```\ngem install ic_agent\n```\n\n### Features\n\n1. principal create and generate\n2. candid types encode \u0026 decode\n3. support secp256k1 \u0026 ed25519 identity\n4. canister DID file parsing\n5. canister class, initialized with canister id and DID file\n6. common canister interfaces: ledger, management, nns, cycles wallet\n7. BLS Verify\n\n### Modules \u0026 Usage\n\n#### 1. Principal\n\nCreate an instance:\n\n```ruby\nrequire \"lib/ic_agent/principal\"\np = IcAgent::Principal.new # default is management canister id `aaaaa-aa`\np1 = IcAgent::Principal.new(bytes: '') # create an instance from bytes\np2 = IcAgent::Principal.anonymous() # create anonymous principal\np3 = IcAgent::Principal.self_authenticating(pubkey) # create a principal from public key\np4 = IcAgent::Principal.from_str('aaaaa-aa') # create an instance from string\np5 = IcAgent::Principal.from_hex('xxx') # create an instance from hex\n```\n\nClass methods:\n\n```ruby\np.bytes # principal bytes\np.len # byte array length\np.to_str() # convert to string\n```\n\n#### 2. Identity\n\nCreate an instance:\n\n```ruby\nrequire \"lib/ic_agent/identity\"\ni = IcAgent::Identity.new # create an identity instance, key is randomly generated\ni1 = IcAgent::Identity.new(privkey = '833fe62409237b9d62ec77587520911e9a759cec1d19755b7da901b96dca3d42') # create an instance from private key\ni2 = IcAgent::Identity.new(privkey = '833fe62409237b9d62ec77587520911e9a759cec1d19755b7da901b96dca3d42', type = 'secp256k1')\n```\n\nSign a message and Verify:\n\n```ruby\nmsg = \"ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f\"\nsig = i.sign(msg) # sig = (der_encoded_pubkey, signature)\nver = i.verify(msg, sig[1])\n```\n\n#### 3. Client\n\nCreate an instance:\n\n```ruby\nclient = IcAgent::Client.new(url = \"https://ic0.app\")\nclient.status\n```\n\n#### 4. Candid\n\nEncode parameters:\n\n```ruby\n# params is an array, return value is encoded bytes\nparams = [{'type': IcAgent::Candid::BaseTypes.nat, 'value': 10}]\ndata = IcAgent::Candid.encode(params)\n\nparams = [{'type': IcAgent::Candid::BaseTypes.null, 'value': nil}]\ndata = IcAgent::Candid.encode(params)\n```\n\nDecode parameters:\n\n```ruby\n# data is bytes, return value is an parameter array\nparams =  IcAgent::Candid.decode(data)\n```\n\n#### 5. Agent\n\nCreate an instance:\n\n```ruby\n# Identity and Client are dependencies of Agent\niden = IcAgent::Identity.new\nclient = IcAgent::Client.new\nagent = IcAgent::Agent.new(iden, client)\n```\n\nQuery call:\n\n```ruby\n# query the name of token canister `gvbup-jyaaa-aaaah-qcdwa-cai`\nname = agent.query_raw(\"gvbup-jyaaa-aaaah-qcdwa-cai\", \"name\", IcAgent::Candid.encode([]))\n```\n\nUpdate call:\n\n```ruby\n# transfer 100 token to blackhole address `aaaaa-aa`\nparams = [\n  { 'type': IcAgent::Candid::BaseTypes.principal, 'value': 'aaaaa-aa' },\n  { 'type': IcAgent::Candid::BaseTypes.nat, 'value': 10000000000 }\n]\nresult = agent.update_raw(\"gvbup-jyaaa-aaaah-qcdwa-cai\", \"transfer\", IcAgent::Candid.encode(params))\n```\n\n#### 6. Read System State\n\nCreate an instance:\n\n```ruby\n# Identity and Client are dependencies of Agent\niden = IcAgent::Identity.new\nclient = IcAgent::Client.new\nagent = IcAgent::Agent.new(iden, client)\n\ntime = IcAgent::SyetemState.time(agent, \"gvbup-jyaaa-aaaah-qcdwa-cai\")\n\nsubnet_public_key = IcAgent::SyetemState.subnet_public_key(agent, \"gvbup-jyaaa-aaaah-qcdwa-cai\", \"pjljw-kztyl-46ud4-ofrj6-nzkhm-3n4nt-wi3jt-ypmav-ijqkt-gjf66-uae\")\n```\n\n#### 7. Canister\n\nCreate a canister instance with candid interface file and canister id, and call canister method with canister instance:\n\n```ruby\nagent = IcAgent::Agent.new(iden, client)\ngov_canister_id = 'rrkah-fqaaa-aaaaa-aaaaq-cai'\ngov_didl = \u003c\u003c~DIDL_DOC\n      // type\n      type AccountIdentifier = record { hash : vec nat8 };\n      type Action = variant {\n        RegisterKnownNeuron : KnownNeuron;\n        ManageNeuron : ManageNeuron;\n        ExecuteNnsFunction : ExecuteNnsFunction;\n        RewardNodeProvider : RewardNodeProvider;\n        SetDefaultFollowees : SetDefaultFollowees;\n        RewardNodeProviders : RewardNodeProviders;\n        ManageNetworkEconomics : NetworkEconomics;\n        ApproveGenesisKyc : ApproveGenesisKyc;\n        AddOrRemoveNodeProvider : AddOrRemoveNodeProvider;\n        Motion : Motion;\n      };\n      ......\nDIDL_DOC\n\ngov_canister = IcAgent::Canister.new(agent, gov_canister_id, gov_didl)\nres = gov_canister.get_neuron_ids()\n```\n\n#### 8. canister: ledger, management, cycles wallet ..\n\ncanister common tools:\n\n```ruby\nledger = IcAgent::Common::Ledger.new\nledger.canister.name()\n```\n\n## UNIT TEST\n\n```\nbundle exec rspec  \n```\n\n## Docker\n\n1. update to latest image\n\n`docker pull tuminfei1981/ruby_ic_agent:latest`\n\n2. Run image:\n\n`docker run -it tuminfei1981/ruby_ic_agent:latest`\n\nThis  will enter the container with a linux shell opened.\n\n```shell\n/usr/src/app # \n```\n\n3. Type `rspec` to run all tests\n\n```shell\n/usr/src/app # bundle exec rspec\n.............................\n\nFinished in 5.56 seconds (files took 0.12067 seconds to load)\n29 examples, 0 failures\n\n```\n\n4. Or, type `./bin/console` to enter the ruby interactive environment and run any ic_agent code\n\n```shell\n/usr/src/app # ./bin/console\n[1] pry(main)\u003e p = IcAgent::Principal.new\n=\u003e #\u003cIcAgent::Principal:0x000000013a54a548 @bytes=\"\", @hex=\"\", @is_principal=true, @len=0\u003e\n[2] pry(main)\u003e p.to_s\n=\u003e \"aaaaa-aa\"\n[3] pry(main)\u003e\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/tuminfei/ic_agent. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/tuminfei/ic_agent/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the IcAgent project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/tuminfei/ic_agent/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuminfei%2Fic_agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuminfei%2Fic_agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuminfei%2Fic_agent/lists"}