Chia Provider API

Hoogii injects an API access point in the websites accessed by users at window.chia.hoogii. Ultimately it aims to not only provide methods as defined in Chia Improvement Proposal (CHIP) 0002 - dApp protocol, but also extended methods that allow dApp developers to get away from the necessity to deploy their own Chia Blockchain full nodes.

General Usage

For a complete end-to-end use case (e.g., Chia dApp web application), you will have to:

• Detect Chia provider (i.e., window.chia.hoogii) and connect.
• Detect which Chia blockchain the user is connected to (e.g., the main Chia Network mainnet and current Chia Test Network testnet10).
• Get user's Chia accounts.

Followed by these initial steps, you are then able to call other methods as detailed below to read from and write to the blockchain on user's behalf, and obtain off-chain information such as user signature on specific messages.

Below for brevity, we refer to window.chia object with chia, and all documented methods are reachable under window.chia.*.

Version

The Chia provider API defined here is of version 1.0.0.

Properties

chia.hoogii.isHoogii

Value

true if Hoogii Wallet is installed.

Description

Note that non-Hoogii wallets can also set this property to true.

EXTENDED IMPLEMENTATION

This property is not defined in Chia provider API 1.0.0.

Example

if (window.chia.hoogii && window.chia.hoogii.isHoogii) {
  console.log('Hoogii is installed!');
}

chia.hoogii.name

Value

'Hoogii' if Hoogii Wallet is installed.

Description

Wallet name.

chia.hoogii.version

Description

The wallet version. Check GitHub Releases for the exact version string.

chia.hoogii.apiVersion

Value

'1.0.0' for the methods described here.

Description

The API version adopted by the wallet.

Methods

chia.hoogii.isConnected()

Definition

window.chia.hoogii.isConnected(): Promise<boolean>;

Description

Returns a diagnostic message object if the provider is connected.

EXTENDED IMPLEMENTATION

This property is not defined in Chia provider API 1.0.0.

chia.hoogii.isUnlocked()

Definition

window.chia.hoogii.isUnlocked(): Promise<boolean>;

Description

Returns a diagnostic message object if the provider is unlocked.

EXTENDED IMPLEMENTATION

This property is not defined in Chia provider API 1.0.0.

chia.hoogii.on()

Definition

window.chia.hoogii.on(event: string, params?: any): void;

Description

Use chia.hoogii.on to register event callbacks. See Events documentation for details.

chia.hoogii.request()

Definition

interface RequestArguments {
  method: string;
  params?: object;
}

window.chia.hoogii.request(args: RequestArguments): Promise<any>;

Description

Use chia.hoogii.request to submit wallet RPC requests to the Chia Blockchain via Hoogii The returned value is a Promise which resolves to the result of the call. The params and return values will vary by each different call as listed below.

If the RPC call fails for some reason, Errors will be raised.

See the Wallet RPC API documentation for details.

Events

chainChanged

Description

The event will be emitted when a new chain is connected.

Example

window.chia.hoogii.on('chainChanged', listener: ({ chainId: string }) => void);

accountChanged

Description

The event will be emitted when the user selects a new account, typically when user chooses an alternative public wallet key. When you receive this event, you should call accounts to retrieve the latest account information.

NOT IMPLEMENTED

This event trigger is not currently implemented and UnderDevelopment will be raised.

Example

window.chia.hoogii.on('accountChanged', listener: () => void);

Wallet RPC API

All wallet RPCs are made by requesting the endpoint chia.hoogii.request(). Note that this wallet RPC is not the same as Chia Wallet RPC API from the official wallet.

connect

Parameters

No parameters are required.

Returns

boolean: whether the connection is successful.

Description

The application requests permission from the user to connect to Hoogii. Note when the user rejects the request, an error UserRejectedRequestError will be raised.

Example

const connected: boolean = await window.chia.hoogii.request({ method: 'connect' });
console.log(connected);

chainId

Parameters

No parameters are required.

Returns

string: the current chain ID.

Description

The available chain are:

ID	Name	Network
0x01	mainnet	Chia main network
0x02	testnet10	Chia test network #10

Please refer to Chia Testnet Setup to understand about the test network.

ALTERNATIVE IMPLEMENTATION

This RPC endpoint is implemented differently from the Chia provider API 1.0.0. Hoogii reports the ID (i.e., 0x01 and 0x02) rather than the name of the networks.

Example

const chainId: string = await window.chia.hoogii.request({ method: 'chainId' });
console.log(chainId);

walletSwitchChain

Parameters

chainId: a string. The ID of the chain to switch to.

Returns

null: no return value is provided upon success.

Description

The application requests to switch the connected network to another one.

ALTERNATIVE IMPLEMENTATION

This RPC endpoint is implemented differently from the Chia provider API 1.0.0. Hoogii accepts the ID (i.e., 0x01 and 0x02) as the argument chainID rather than the name of the networks.

Example

const params = { chainId: '0x01' };
await window.chia.hoogii.request({ method: 'walletSwitchChain', params });

accounts

Parameters

No parameters are required.

Returns

string[]: the currently selected accounts.

Description

A wallet can hold many different accounts, and this endpoint returns the currently used accounts.

EXTENDED IMPLEMENTATION

This method is not defined in Chia provider API 1.0.0.

Example

const accounts: string[] = await window.chia.hoogii.request({ method: 'accounts' });
console.log(accounts);

transfer

Parameters

• to: A string. The recipient's Chia address.
• amount: An integer. The amount of Chia being transferred, measured in mojo (the smallest unit of Chia, equivalent to 10^-12 XCH).
• memos: An optional list of string. Memos associated with the transfer. Each memo is a hex string that can be used to attach additional data to the transfer.
• assetId: An optional string. The ID of the asset being transferred, if the transfer involves an asset other than XCH. This field is optional and can be left out for XCH transfers.

interface TransferParams {
  to: string;  // bech32m encoded address
  amount: number;
  memos?: string[];
  assetId?: string;
}

Returns

null: no return value is provided upon success.

Description

This API is used for transferring CAT or XCH to a specified recipient, with the option to attach memos.

EXTENDED IMPLEMENTATION

This method is not defined in Chia provider API 1.0.0.

Example

const params = {
  to: 'txch1yw8gm66uzmuzj4ezzk7tmpjk7fzacq8n7tgtdq0zshxj978gp6cq6sm5z8',
  amount: '1000',
  // hex string, "hello chia".encode("utf-8")
  memos: ['0x68656c6c6f2063686961'],  
  assetId:
    '73dd418ff67e6079f06c7cc8cee637c7adc314210dca26997d634692f6c16087',
};
window.chia.hoogii.request({ method: 'transfer', params });

createOffer

Parameters

• requestAssets: An array of objects specifying the assets the user is requesting to receive in the trade. Each object includes the assetId of the asset and the amount requested.
• offerAssets: An array of objects specifying the assets the user is offering to give in the trade. Each object includes the assetId of the asset and the amount offered.

interface Asset {
  assetId?: string;  // 256-bit, 32-bytes, or 64-char hexadecimal string
  amount: number;
}

interface CreateOfferParams {
  requestAssets: Asset[],
  offerAssets: Asset[],
}

Returns

CreateOfferResult: the offer created with fields offer to hold the offer string, and id to hold the transaction ID of the offer.

interface CreateOfferResult {
  offer: string;
  id: string;
}

Description

This API is used for creating a trade offer. Users can specify the assets they are requesting and offering in the trade. The API returns an offer string and a transaction ID for the offer.

EXTENDED IMPLEMENTATION

This method is not defined in Chia provider API 1.0.0.

Example

const params = {
  requestAssets: [
    {
      assetId: '73dd418ff67e6079f06c7cc8cee637c7adc314210dca26997d634692f6c16087',
      amount: 100,
    },
  ],
  offerAssets: [
    {
      assetId: '',
      amount: 100,
    },
  ],
};
const result = await window.chia.hoogii.request({ method: 'createOffer', params });

console.log(result);

takeOffer

NOT IMPLEMENTED

This RPC endpoint is not currently implemented and UnderDevelopment will be raised.

sendTransaction

Parameters

• spendBundle: A SpendBundle object. Contains coin_spends and aggregated_signature.

interface Coin {
  amount: number;
  parent_coin_info: string;
  puzzle_hash: string;
}

interface CoinSpend {
  coin: Coin;
  puzzle_reveal: string;  // a hexadecimal string
  solution: string;  // a hexadecimal string
}

interface SpendBundle {
  coin_spends: CoinSpend[];
  aggregated_signature: string;  // 768-bit, 96-bytes, or 192-char hexadecimal string 
}

interface SendTransactionParams {
  spendBundle: SpendBundle;
}

Returns

SendTransactionResult: an object with a status field to indicate result and error to optionally include error message

enum MempoolInclusionStatus {
  SUCCESS = 1;  // Transaction added to mempool
  PENDING = 2;  // Transaction not yet added to mempool
  FAILED = 3;  // Transaction was invalid and dropped
}

interface TransactionResult {
  status: MempoolInclusionStatus;
  error?: string;
}

Description

dApps can send signed transaction to the full node via this endpoint.

Example

const params = { spendBundle: ... };
const result = await window.chia.hoogii.request({ method: 'sendTransaction', params});

console.log(result);

getPublicKeys

Parameters

• limit: :An optional number of records to return.
• offset:An optional number which row to start retrieving from.

Returns

string[]: the currently selected public keys.

Description

API returns the public keys managed by the wallet. The wallet can limit the total number of managed public keys to return.

EXTENDED IMPLEMENTATION

This method is not defined in Chia provider API 1.0.0.

Example

 const publicKeys = await window.chia.hoogii.request({
    method: 'getPublicKeys',
    params: {},
})
console.log(publicKeys)

getAssetBalance

Parameters

• type: : Asset type, null, cat, did, or nft. null means XCH.
• assetId: It depends on type and will be ignored when type is null. If type is cat, assetId means tail program hash. If type is did, assetId means did id. If type is nft, assetId means nft id.

Returns

AssetBalanceResp:Returns the spendable balance of the wallet's asset.

interface AssetBalanceResp {
  spendableCoinCount: number;
}

Description

Returns the spendable balance of the wallet. It's convenient for the dApp to query the user's balance. Also, the dApp can sum the results by calling getAssetCoins.

ALTERNATIVE IMPLEMENTATION

This method is not defined in Chia provider API 1.0.0. We only provide cat and xch

Example

const balance = await window.chia.hoogii.request({
    method: 'getAssetBalance',
    params: { type: 'cat', assetId: '73dd418ff67e6079f06c7cc8cee637c7adc314210dca26997d634692f6c16087' },
})
console.log('balance', balance.spendableCoinCount)

filterUnlockedCoins

NOT IMPLEMENTED

This RPC endpoint is not currently implemented and UnderDevelopment will be raised.

getAssetCoins

Parameters

• type: Asset type, null, cat, did, or nft. null means XCH
• assetId: It depends on type and will be ignored when type is null. If type is cat, assetId means tail program hash. If type is did, assetId means did id. If type is nft, assetId means nft id.
• offset: specify which row to start retrieving from. The default value is 0.
• limit: specify the number of records to return. The default value is 10.

interface GetAssetCoinsParams {
  type?: string;
  assetId?: string;
  offset?: number;
  limit?: number;
  includedLocked?: boolean;  // always `false`; not specifiable by user 
}

Returns

AssetCoin[]: an list of AssetCoin with the following fields:

• coin: A Chia coin with fields amount, parent_coin_info, and puzzle_hash.
• coinName: The ID of the coin.
• puzzle: The puzzle for the coin, which is a computational task that needs to be solved in order to obtain the coin.
• confirmedBlockIndex: The index number of the confirmed block in which the coin resides
• locked: This API only support unlocked coins, this field is always false.
• lineageProof: The lineage proof for the coin, which includes the name of the coin's parent, the hash value of the inner puzzle, and the amount of the coin. This field is optional, as not all coins have a lineage proof.

interface AssetCoin {
  coin: Coin;
  coinName: string;
  puzzle: string;
  confirmedBlockIndex: number;
  locked: boolean;  // always `false`
  lineageProof?: {
    parentName?: string;
    innerPuzzleHash?: string;
    amount?: number;
  }
}

Description

This is an interface to retrieves information about Chia coins based on certain parameters.

ALTERNATIVE IMPLEMENTATION

This RPC endpoint is implemented differently from the Chia provider API 1.0.0. We only provide unlocked coins.

Example

const xchCoins = await window.chia.hoogii.request({
  method: 'getAssetCoins',
  params: { type: null, assetId: null },
});

console.log('xchCoins', xchCoins);

const catCoins = await window.chia.hoogii.request({
  method: 'getAssetCoins',
  params: {
    type: 'cat',
    assetId: '73dd418ff67e6079f06c7cc8cee637c7adc314210dca26997d634692f6c16087',
  },
});

console.log('assetCoins', assetCoins);

signCoinSpends

Parameters

• coinSpends: A list of coinSpend with the following fields:
  • coin: A Coin object.
  • puzzle_reveal: The puzzle of the Coin.
  • solution: the solution of puzzle.

interface Coin {
  amount: number;
  parent_coin_info: string;
  puzzle_hash: string;
}

interface CoinSpend {
  coin: Coin;
  puzzle_reveal: string;
  solution: string; 
}

Returns

string: The aggregated signature for the coinSpends.

Description

This is a lower-level API that signs custom coin spends and returns the aggregated signature.

ALTERNATIVE IMPLEMENTATION

This RPC endpoint is implemented differently from the Chia provider API 1.0.0. We do not provide an partialSign parameter.

Example

const aggregated_signature = await window.chia.hoogii.request({
  method: 'signCoinSpends',
  params: { coinSpends: ... },
});

console.log(aggregated_signature);

signMessage

NOT IMPLEMENTED

This RPC endpoint is not currently implemented and UnderDevelopment will be raised.

Errors

The errors share a common structure:

interface Error {
  code: number;
  message: string;
  data?: any;
}

InvalidParamsError

Definition

InvalidParamsError = {
  code: 4000,
  message: 'invalid params'
}

UnauthorizedError

Definition

UnauthorizedError = {
  code: 4001,
  message: 'unauthorized'
}

UserRejectedRequestError

Definition

UserRejectedRequestError = {
  code: 4002,
  message: 'user rejected request'
}

SpendableBalanceExceededError

Definition

SpendableBalanceExceededError = {
  code: 4003,
  message: 'spendable balance exceeded'
}

MethodNotFoundError

Definition

MethodNotFoundError = {
  code: 4004,
  message: 'method not found'
}

NoSecretKeyError

Definition

NoSecretKeyError = {
  code: 4005,
  message: 'no secret key for public key'
}

LimitExceedError

Definition

LimitExceedError = {
  code: 4029,
  message: 'too many requests'
}

UnderDevelopment

Definition

UnderDevelopment = {
  code: 4030,
  message: 'under development'
}