Skip to main content

Shade Agent API

The Shade Agent API abstracts away the complexity of the TEE and interacting with the agent contract. The API is packaged as a Docker image and included in your agent when uploaded to Phala Cloud. The API is accessible internally by default on port 3140, it is not accessible from outside the TEE.

When the API image boots up it will automatically create the agents account, fund it with the NEAR_ACCOUNT_ID from the environment variables and register the agent in the agent contract.

The API can be used in any language but we maintain API wrappers in TypeScript and Python. We recommend your develop in TypeScript as it has great synergies with chainsig.js for building multichain transactions.

Setup​

npm install @neardefi/shade-agent-js

Agent Account ID​

Fetches the NEAR account ID of the agent.

import { agentAccountId } from '@neardefi/shade-agent-js';

const res = await agentAccountId();
const accountId = res.accountId

Agent Info​

Fetches the code hash and checksum for the agent.

  • The code hash is the code hash of the app image running inside the agent.
  • The checksum is produced by the TEEs attestation and represents that the agent is registered.

This function will only return the details once the agent has successfully registered in the agent contract. For running the API locally it will only return the code hash not the checksum.

import { agentInfo } from '@neardefi/shade-agent-js';

const res = await agentInfo();
const codehash = res.codehash
const checksum = res.checksum

Agent Balance​

Fetches the NEAR balance of the agent's account in yoctoNEAR (1 NEAR = 10^24 yoctoNEAR).

import { agent } from '@neardefi/shade-agent-js';

const res = await agent("getBalance");
const balance = res.balance

Request Signature​

Requests a signature from the Shade Agent system for a multichain account. It has three arguments:

  • path - An string that maps the signature to a specific account, the path can be set to anything and by changing the path you will be signing for a different account.
  • payload - The hash of the transaction to be signed, given as a hex string.
  • keyType - The signature scheme being used to sign the payload Ecdsa (secp256k1) or Eddsa (ed25519).

It returns the signature for the transaction.

import { requestSignature } from '@neardefi/shade-agent-js';

const res = await requestSignature({
  path: "ethereum-1",
  payload: "cf80cd8a...",
  keyType: "Ecdsa", // Or "Eddsa"
});
Response

For Ecdsa the function returns the components of the signature as hex strings. Note that to get r remove the first two hex characters from big_r.

{
  scheme: 'Secp256k1',
  big_r: {
    affine_point: '03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1'
  },
  s: {
    scalar: '3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725'
  },
  recovery_id: 0
}

For Eddsa the function returns the whole signature as a 64-byte array.

{
  scheme: 'Ed25519',
  signature: [
      5, 105,  30, 208, 192,  39, 154, 105, 252,  20, 132,
      64, 247, 207, 223, 127, 197,  43,  30, 145, 164, 224,
      1,  45, 240,  28, 155, 218, 204,   5, 136, 111, 238,
      40, 120, 122, 249, 166, 193, 174, 120,  94, 177,  39,
      179, 193, 170, 117,  37,  36, 155,  38,  72,  24, 118,
      235, 187, 110, 129,  26, 186,   7,   0,   8
  ]
}

If your using the chainsig.js library you don't need to worry about the format of these responses since the library handles it.

Agent Call​

Makes a function call to the agent contract from the agent. This is used for custom contracts when you want to call a function other than request_signature. It returns the result of the function call.

import { agentCall } from '@neardefi/shade-agent-js';

const res = await agentCall({
  methodName: "example_call_method",
  args: {
    arg1: "Value1",
    arg2: "Value2",
  },
  gas: "30000000000000", // Optional 
})

Agent View​

Makes a function call to a view method (a method that does not require gas) on the agent contract. It returns the result of the function call.

import { agentView } from '@neardefi/shade-agent-js';

const res = await agentView({
  methodName: "example_view_method",
  args: {
    arg1: "value1",
    arg2: "value2",
  },
})