What is eosio.wrap?

Eosio.wrap is an eosio system contract created by block.one. The contract enables an eosio chain administrator to update specifics of another account, e.g. permissions, without requiring the accounts private key. Think of it as sudo for eosio.

In a public permissionless blockchain like EOS, using the wrap contract is heavily restricted and in most circumstances, not recommended. On EOS only the top 21 Block Producing nodes can sign a transaction which uses eosio.wrap. Alternatively, chain administrators could create a contract which calls eosio.wrap to do something useful. Using the contract, just like using root on a Linux system requires thought and consideration.

The images below show the contract deployed on the EOS public network, requiring 15/21 BP sign off. (Image courtesy of bloks.io).

Permissions set on the eosio.wrap account – EOS Public Blockchain

Why Use eosio.wrap?

In recent months, I’ve been building a number of eosio private testnets. I created several accounts on each testnet and saved the private keys to my cleos vault for later use… After a couple of days, I got back to work and realised I’d messed up, the private key wasn’t locked in my vault, I’d only printed it to the console and for some reason, I’d lost my scroll history. DOH! To fix the problem I needed to enable superuser access.


  1. Create eosio.wrap account on your local/private chain
  2. Set the eosio.wrap account to privileged
  3. Deploy the eosio.wrap contract and abi
  4. Fixed broken permissions on your broken account to get yourself out of trouble

Word of warning. This procedure requires access to the original private key for your deployment. Without it, you’re screwed.

Create eosio.wrap Account

cleos -u https://<chain-hostname>:<port> create account eosio eosio.wrap EOS<key> -p eosio

Deploy Contract

Before completing this step you need to 1) have eosio and the eosio.cdt installed and 2) compile the system contracts locally. If you get stuck, refer to the eosio github site, or developers portal.

git clone https://github.com/EOSIO/eosio.contracts.git
cd eosio.contracts/
./build.sh (output to <contracts> directory
cd contracts/eosio.wrap/
cleos -u https://<chain-hostname>:<port> set contract eosio.wrap . eosio.wrap.wasm eosio.wrap.abi

Set eosio.wrap to Privileged Account

In order to updated permissions, the eosio.wrap account must be privileged. This command sets the required privilege level, similar to adding a user to a privileged group on a Linux system.

cleos -u https://<chain-hostname>:<port> push action eosio setpriv '["eosio.wrap", 1]' -p [email protected]

Create an Unsigned Transaction

This command creates an unsigned transaction to change the permissions on <youraccount> to EOS<key>. The unsigned transaction change.json will be stored in the local directory.

cleos -u https://<chain-hostname>:<port> set account permission -s -j -d <youraccount> owner EOS<key> > change.json

Use eosio.wrap To Set Permission

Use eosio system account to run the cleos wrap exec command. This executes the transaction change.json.

cleos -u https://<chain-hostname>:<port> wrap exec eosio change.json

Get confirmation

Finally, check your account to ensure the private key has been updated.

cleos -u https://<chain-hostname>:<port> get account <youraccount>


If you followed the steps (and assuming they worked), your account should now be back up and available.

If you are planning to use eosio.wrap in a production environment, I would highly recommend you think about the implications. The contract exists and is useful. But if left unprotected could leave you in a spot of bother. Feel free to reach out to discuss.