Python Agent Library for the Internet Computer

ic-py provides basic modules to interact with canisters on the DFINITY Internet Computer.

Install

pip3 install ic-py

Features

1. candid types encode & decode
2. support secp256k1 & ed25519 identity, pem file import
3. canister DID file parsing
4. canister class, initialized with canister id and DID file
5. common canister interfaces: ledger, management, nns, cycles wallet
6. async support

Modules & Usage

1. Principal

Create an instance:

fromic.principalimportPrincipalp=Principal() # default is management canister id `aaaaa-aa`p1=Principal(bytes=b'') # create an instance from bytesp2=Principal.anonymous() # create anonymous principalp3=Principal.self_authenticating(pubkey) # create a principal from public keyp4=Principal.from_str('aaaaa-aa') # create an instance from stringp5=Principal.from_hex('xxx') # create an instance from hex

Class methods:

p.bytes# principal bytesp.len# byte array lengthp.to_str() # convert to string

2. Identity

Create an instance:

fromic.identityimportIdentityi=Identity() # create an identity instance, key is randomly generatedi1=Identity(privkey="833fe62409237b9d62ec77587520911e9a759cec1d19755b7da901b96dca3d42") # create an instance from private key

Sign a message:

msg=b”ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f“
sig=i.sign(msg) # sig = (der_encoded_pubkey, signature)

3. Client

Create an instance:

fromic.clientimportClientclient=Client(url="https://ic0.app")

4. Candid

Encode parameters:

fromic.candidimportencode, decode, Types# params is an array, return value is encoded bytesparams= [{'type': Types.Nat, 'value': 10}]
data=encode(params)

Decode parameters:

# data is bytes, return value is an parameter arrayparams=decode(data)

5. Agent

Create an instance:

fromic.clientimportClientfromic.identityimportIdentityfromic.agentimportAgent# Identity and Client are dependencies of Agentiden=Identity()
client=Client()
agent=Agent(iden, client)

Query call:

# query the name of token canister `gvbup-jyaaa-aaaah-qcdwa-cai`name=agent.query_raw("gvbup-jyaaa-aaaah-qcdwa-cai", "name", encode([]))

Update call:

# transfer 100 token to blackhole address `aaaaa-aa`params= [
{'type': Types.Principal, 'value': 'aaaaa-aa'},
{'type': Types.Nat, 'value': 10000000000}
]
result=agent.update_raw("gvbup-jyaaa-aaaah-qcdwa-cai", "transfer", encode(params))

6. Canister

Create a canister instance with candid interface file and canister id, and call canister method with canister instance:

fromic.canisterimportCanisterfromic.clientimportClientfromic.identityimportIdentityfromic.agentimportAgentfromic.candidimportTypesiden=Identity()
client=Client()
agent=Agent(iden, client)
# read governance candid from filegovernance_did=open("governance.did").read()
# create a governance canister instancegovernance=Canister(agent=agent, canister_id="rrkah-fqaaa-aaaaa-aaaaq-cai", candid=governance_did)
# call canister method with instanceres=governance.list_proposals(
{
'include_reward_status': [],
'before_proposal': [],
'limit': 100,
'exclude_topic': [],
'include_status': [1]
}
)

7. Async request

ic-py also supports async requests:

importasynciofromic.canisterimportCanisterfromic.clientimportClientfromic.identityimportIdentityfromic.agentimportAgentfromic.candidimportTypesiden=Identity()
client=Client()
agent=Agent(iden, client)
# read governance candid from filegovernance_did=open("governance.did").read()
# create a governance canister instancegovernance=Canister(agent=agent, canister_id="rrkah-fqaaa-aaaaa-aaaaq-cai", candid=governance_did)
# async callasyncdefasync_test():
res=awaitgovernance.list_proposals_async(
{
'include_reward_status': [], 'before_proposal': [],
'limit': 100, 'exclude_topic': [], 'include_status': [1]
}
)
print(res)
asyncio.run(async_test())