Wrapped ICP - WICP

Wrapped ICP (WICP) is a wrapped version of the IC's native token, ICP. Each WICP will be backed 1:1 with ICP, meaning that 1 WICP will always have the exact same value as 1 ICP. The only difference is that, unlike ICP, WICP uses the DIP20 fungible token standard that is specifically designed to allow for interoperability between dApps and other tokens.

🧰 Interacting with Wrapped ICP (WICP) - On Mainnet (DFX)

In order to interact with the Internet Computer mainnet version of the Wrapped ICP (WICP) canister, you need the address.

WICP Canister ID: utozz-siaaa-aaaam-qaaxq-cai
WICP Account ID: cc659fe529756bae6f72db9937c6c60cf7ad57eb4ac5f930a75748927aab469a

You have to use this address (Canister ID) to make your calls, with the exception of the Account ID during the mint.

✒️ Update Calls

All update functions are allowed to trap, instead of returning an error in order to take advantage of the canisters automatic, atomic state rollback.

Deposit ICP to mint an WICP balance - mint

Using the mint method is done in two steps. First, we need to make a transfer call at the ICP ledger to the WICP account ID. Using the following command you’ll be returned the block height when your transaction was approved.

dfx ledger --network ic transfer --amount value "cc659fe529756bae6f72db9937c6c60cf7ad57eb4ac5f930a75748927aab469a" --memo 0

Now that we have the blockheight of our ICP transfer, we can call the mint method on the WICP canister. In addition, the mint method takes ‘subaccount’, a parameter that allows you to specify if you’ve made the previous ICP transfer from a subaccount. Index 0 is your main account, while all non-zero indices refer to subaccounts.

dfx canister --no-wallet --network ic call utozz-siaaa-aaaam-qaaxq-cai mint '(subaccount, blockheight:nat64)'

Unwrap your WICP and regain a balance of ICP - withdraw

Calling withdraw unwraps your WICP, burns it, and then unlocks and sends ICP from the WICP canister to the balance of the Principal ID you specify.

The Withdraw method takes two parameters, ‘value’ and ‘to’. Value is an integer that represents the amount of WICP you’d like to withdraw to ICP. To is a string that should be the Principal ID that you wish the ICP to be transferred to.

dfx canister --no-wallet --network ic call utozz-siaaa-aaaam-qaaxq-cai withdraw '(value:nat64, "account id")'

Transfer WICP to Another WICP Balance - transfer

You can transfer WICP to any other valid Principal ID. Your balance at the WICP ledger will be deducted and the Principal ID you transfer to, will be incremented.

Transfers ‘value’ (Nat) amount of tokens to user ‘to’ (Principal), returns a TxReceipt which contains the transaction index or an error message.

dfx canister --network=ic --no-wallet call utozz-siaaa-aaaam-qaaxq-cai transfer "(principal \"to-account-principal\", 1000:nat)"

Set an Allowance to Another Identity - approve

You can set an allowance using this method, giving a third-party access to a specific number of tokens they can withdraw from your balance if they want.

An allowance permits the ‘spender’ (Principal) to withdraw tokens from your account, up to the ‘value’ (Nat) amount. If it is called again it overwrites the current allowance with ‘value’ (Nat). There is no upper limit for value, you can approve a larger value than you have, but 3rd parties are still bound by the upper limit of your account balance.

dfx canister --network=ic --no-wallet call utozz-siaaa-aaaam-qaaxq-cai approve "(principal \"third-party-principal-id\", 1000:nat)"

Transfer WICP on Another User's Behalf - transferFrom

Transfers ‘value’ (Nat) amount of tokens from user ‘from’ (Principal) to user ‘to’ (Principal), this method allows canister smart contracts to transfer tokens on your behalf, it returns a TxReceipt which contains the transaction index or an error message.

dfx canister --network=ic --no-wallet call utozz-siaaa-aaaam-qaaxq-cai transferFrom "(principal \"from-account-principal\",principal \"to-account-principal\", 1000:nat)"

📡 Query Calls

The query calls in this section do not require any fee as they are only reading information, not modifying it.

Check your Balance - balanceOf

Returns the balance of user who.

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai balanceOf "(principal \"who-account-principal\")"

Check the set allowance for an ID - allowance

Returns the amount which spender is still allowed to withdraw from owner.

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai allowance "(principal \"owner-account-principal\", principal \"spender-account-principal\")"

Get token logo - logo

Returns the logo of Wrapped ICP (WICP).

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai logo

Get token name - name

Returns the name of Wrapped ICP (WICP).

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai name

Get token symbol - symbol

Returns the symbol of the token.

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai symbol

Get token decimals - decimals

Returns the decimals of the token.

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai decimals

Get total supply of token - totalSupply

Returns the total supply of the token.

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai totalSupply

Get token’s metadata - getMetadata

Returns the metadata of the token.

dfx canister --network=ic --no-wallet call --query utozz-siaaa-aaaam-qaaxq-cai getMetadata

historySize

Returns the history size.

dfx canister --network=ic --no-wallet call --query wicp historySize

🤖 Using this project

You can use this projects tooling with either npm run <script> or yarn <script>

Healthcheck

The healthcheck can be run with

npm run dip20:healthcheck

This installs WICP and CAP to the local replica and runs a basic flow of usage, for 2 temporary user identities Alice and Bob

Deploy

The deploy script can be used with any network configured in dfx.json. If you want to completely wipe the canister state and reinstall, use the optional flag

npm run dip20:deploy <network> [reinstall]

Using existing CAP canister

CAP can be manually deployed, using

cap:init # only needs to be ran once to initalize the cap submodule
cap:deploy

You can set the environment variable CAP_ID to skip the cap prompts and setting up a new cap canister on the network, if you already have one setup.

CAP_ID=lj532-6iaaa-aaaah-qcc7a-cai npm run dip20:deploy local

This also works with the healthcheck. The mainnet CAP canister is automatically used if the network is ic, unless explicitly specified.

CAP requires ic-cdk-optimizer to be installed with cargo to build.

🙏 Contributing

Create branches from the main branch and name it in accordance to conventional commits here, or follow the examples bellow:

test: 💍 Adding missing tests
feat: 🎸 A new feature
fix: 🐛 A bug fix
chore: 🤖 Build process or auxiliary tool changes
docs: ✏️ Documentation only changes
refactor: 💡 A code change that neither fixes a bug or adds a feature
style: 💄 Markup, white-space, formatting, missing semi-colons...

qalqi / wicp