Contract Kit

https://github.com/wharfkit/contract
Admin
Contract Kit is a library designed to simplify interactions with Antelope-based smart contracts,...
Tokens:3,228
Snippets:11
Trust Score:7.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get Ricardian Contracts for Actions with WharfKit

Source: https://context7.com/wharfkit/contract/llms.txt

Retrieve human-readable ricardian contract text for a specific action. Ricardian contracts define the legal terms associated with an action. The code demonstrates how to fetch and display these terms, and how to check if an action has an associated ricardian contract.

```typescript
// Get ricardian contract for an action
const kit = new ContractKit({ client: new APIClient('https://eos.greymass.com') })
const contract = await kit.load('eosio.token')

try {
  const ricardian = contract.ricardian('transfer')
  console.log('Transfer Terms:', ricardian)
  // Returns markdown/text describing the legal implications of the transfer action
} catch (error) {
  console.error('Ricardian contract not available:', error.message)
}

// Check if action has ricardian contract
if (contract.hasAction('transfer')) {
  const terms = contract.ricardian('transfer')
  // Display to user before signing
}
```

--------------------------------

### Get Single Table Row with WharfKit

Source: https://context7.com/wharfkit/contract/llms.txt

Retrieves a single row from a smart contract table using its primary key or a secondary index. It can fetch data with a specific scope and returns `undefined` if the row is not found. Custom row types can be provided for enhanced TypeScript support.

```typescript
// Get a specific producer by name (primary key)
const producersTable = systemContract.table('producers')
const producer = await producersTable.get('teamgreymass')
console.log('Owner:', producer.owner.toString())
console.log('Total votes:', producer.total_votes.toString())

// Get by secondary index
const trendingTable = contract.table('trending')
const row = await trendingTable.get(102465, { index: 'score' })
console.log('Item ID:', row.id)

// Get with specific scope
const accountsTable = tokenContract.table('accounts', 'alice')
const balance = await accountsTable.get()
console.log('Balance:', balance.balance.toString())

// Returns undefined if not found
const missing = await producersTable.get('doesnotexist')
if (!missing) {
  console.log('Producer not found')
}

// With custom row type for TypeScript typing
import { Struct, Name, Asset } from '@wharfkit/antelope'

@Struct.type('account')
class Account extends Struct {
  @Struct.field(Asset) balance!: Asset
}

const typedTable = tokenContract.table<Account>('accounts', 'alice', Account)
const account = await typedTable.get()
console.log(account.balance.value) // TypeScript knows this is an Asset
```

--------------------------------

### Initialize ContractKit and Load Contracts

Source: https://context7.com/wharfkit/contract/llms.txt

Initializes the ContractKit, the main entry point for interacting with smart contracts. It manages ABI caching and allows loading contracts by their account name. Supports custom ABI caches and pre-loading ABIs for efficiency.

```typescript
import { ContractKit } from '@wharfkit/contract'
import { APIClient } from '@wharfkit/antelope'

// Create an API client for your blockchain
const client = new APIClient('https://jungle4.greymass.com')

// Initialize ContractKit
const kit = new ContractKit({ client })

// Load a contract by account name
const tokenContract = await kit.load('eosio.token')
const systemContract = await kit.load('eosio')

// With custom ABI cache
import { ABICache } from '@wharfkit/abicache'
const customCache = new ABICache(client)
const kitWithCache = new ContractKit({ client }, { abiCache: customCache })

// Pre-load ABIs to avoid network calls
const kitWithABIs = new ContractKit({ client }, {
  abis: [
    { name: 'mycontract', abi: { version: 'eosio::abi/1.2', structs: [...], actions: [...] } }
  ]
})

// Enable debug mode for JSON responses
const debugKit = new ContractKit({ client }, { debug: true })
const contract = await debugKit.load('eosio.token')
```

--------------------------------

### Create Blockchain Actions with Contract.action()

Source: https://context7.com/wharfkit/contract/llms.txt

Generates Action objects for submitting transactions. Actions are automatically serialized using the contract's ABI and can be used with @wharfkit/session for signing. Supports single actions, multiple actions, and custom authorizations.

```typescript
import { PlaceholderAuth } from '@wharfkit/signing-request'

// Create a token transfer action
const transferAction = tokenContract.action('transfer', {
  from: 'alice',
  to: 'bob',
  quantity: '10.0000 EOS',
  memo: 'Payment for services'
})

// With custom authorization
const authorizedAction = tokenContract.action('transfer', {
  from: 'alice',
  to: 'bob',
  quantity: '10.0000 EOS',
  memo: 'Payment'
}, {
  authorization: [{ actor: 'alice', permission: 'active' }]
})

// Create multiple actions at once
const actions = systemContract.actions([
  {
    name: 'newaccount',
    data: {
      creator: 'alice',
      name: 'newuser',
      owner: { threshold: 1, keys: [{ key: 'EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV', weight: 1 }], accounts: [], waits: [] },
      active: { threshold: 1, keys: [{ key: 'EOS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV', weight: 1 }], accounts: [], waits: [] }
    }
  },
  {
    name: 'buyrambytes',
    data: { payer: 'alice', receiver: 'newuser', bytes: 8192 },
    authorization: [{ actor: 'alice', permission: 'active' }]
  }
])

// Use with session for transaction signing
import { Session } from '@wharfkit/session'
const result = await session.transact({ actions: [transferAction] })
```

--------------------------------

### Fetch First N Table Rows Efficiently with WharfKit

Source: https://context7.com/wharfkit/contract/llms.txt

Allows for the efficient retrieval of a specified number of initial rows from a smart contract table. It achieves this by creating a cursor with a `maxRows` limit and then fetching all results from that limited cursor.

```typescript
// Get first 10 rows
const firstTen = systemContract.table('namebids').first(10)
const rows = await firstTen.all()
console.log(`Retrieved ${rows.length} rows`)

// With filtering and scope
const firstFiltered = systemContract.table('delband').first(5, {
  scope: 'teamgreymass',
  from: 'alice',
  to: 'bob'
})
const results = await firstFiltered.all()
```

--------------------------------

### Inspect Contract Metadata with WharfKit

Source: https://context7.com/wharfkit/contract/llms.txt

Access contract metadata such as available tables, actions, and ABI information for introspection and validation. The code shows how to list table and action names, check for their existence, and access the contract's ABI and account details.

```typescript
// Check available tables
console.log('Tables:', systemContract.tableNames)
// Output: ['voters', 'producers', 'global', 'delband', ...]

if (systemContract.hasTable('voters')) {
  const votersTable = systemContract.table('voters')
}

// Check available actions
console.log('Actions:', tokenContract.actionNames)
// Output: ['transfer', 'issue', 'create', ...]

if (tokenContract.hasAction('transfer')) {
  const action = tokenContract.action('transfer', {...})
}

// Access ABI directly
const abi = systemContract.abi
console.log('ABI version:', abi.version)
console.log('Account:', systemContract.account.toString())

// Inspect table structure
const table = systemContract.table('producers')
console.log('Table name:', table.name.toString())
console.log('Table ABI:', table.tableABI)
```

--------------------------------

### Query Table Rows with Cursor using WharfKit

Source: https://context7.com/wharfkit/contract/llms.txt

Enables iteration over smart contract table rows using a cursor, supporting filtering, pagination, and index-based queries for efficient handling of large datasets. The cursor can be reset to restart iteration.

```typescript
// Query all rows in a table
const cursor = producersTable.query()
const allProducers = await cursor.all()
console.log(`Found ${allProducers.length} producers`)

// Filter by range on primary index
const filteredCursor = trendingTable.query({
  from: 101511,
  to: 105056,
  index: 'score'
})
const rows = await filteredCursor.all()

// Paginate through results
const paginatedCursor = producersTable.query({ maxRows: 100 })
const firstBatch = await paginatedCursor.next()
const secondBatch = await paginatedCursor.next()

// Query with specific scope
const scopedCursor = systemContract.table('delband').query({
  scope: 'teamgreymass',
  maxRows: 10
})
const delegations = await scopedCursor.all()

// Reverse order
const reverseCursor = trendingTable.query({
  from: 5,
  to: 10,
  reverse: true
})
const reversedRows = await reverseCursor.all()

// Control API request size
const controlledCursor = trendingTable.query({
  rowsPerAPIRequest: 100,
  maxRows: 1000
})
while (true) {
  const batch = await controlledCursor.next()
  if (batch.length === 0) break
  console.log(`Processing ${batch.length} rows`)
}

// Use async iteration
const iterCursor = producersTable.query({ maxRows: 1000 })
for await (const producer of iterCursor) {
  console.log('Producer:', producer.owner.toString())
}

// Reset cursor to start overcursor.reset()
const freshResults = await cursor.all()
```

--------------------------------

### Fetch All Table Rows Conveniently with WharfKit

Source: https://context7.com/wharfkit/contract/llms.txt

Provides a simple method to fetch all rows from a smart contract table in a single operation. This method internally utilizes a cursor and manages pagination automatically, offering typed data structures.

```typescript
// Fetch all rows from a table
const allBids = await systemContract.table('namebids').all()
console.log(`Total bids: ${allBids.length}`)

// With filtering
const filtered = await trendingTable.all({
  from: 100,
  to: 200,
  index_position: 'secondary'
})

// With specific scope
const tokenBalances = await tokenContract.table('accounts').all({
  scope: 'alice'
})

// Returns typed data
allBids.forEach(bid => {
  console.log(`${bid.newname.toString()}: ${bid.high_bid.toString()}`)
})
```

--------------------------------

### Query Table Scopes with WharfKit Contract API

Source: https://context7.com/wharfkit/contract/llms.txt

Retrieve all scopes for a table, filter them by range, or paginate through them. This is particularly useful for multi-index tables that partition data by scope. The API allows controlled pagination using `rowsPerAPIRequest`.

```typescript
// Get all scopes for a table
const proposalTable = msigContract.table('proposal')
const scopesCursor = proposalTable.scopes()
const allScopes = await scopesCursor.all()
console.log(`Found ${allScopes.length} scopes`)
allScopes.forEach(scope => {
  console.log(`Scope: ${scope.scope.toString()}, Rows: ${scope.count}`)
})

// Filter scopes by range
const filteredScopes = proposalTable.scopes({
  from: 'teamgreymass',
  to: 'telosdompet1'
})
const scopeList = await filteredScopes.all()

// Paginate through scopes
const scopesPaginated = proposalTable.scopes()
const firstBatch = await scopesPaginated.next(10)
const secondBatch = await scopesPaginated.next(10)

// Use rowsPerAPIRequest for controlled pagination
const controlledScopes = proposalTable.scopes({ rowsPerAPIRequest: 2 })
while (true) {
  const batch = await controlledScopes.next()
  if (batch.length === 0) break
  batch.forEach(s => console.log(`Scope: ${s.scope.toString()}`))
}
```

--------------------------------

### Advanced WharfKit Usage: Custom Types and Debug Mode

Source: https://context7.com/wharfkit/contract/llms.txt

Work with custom struct types for strong typing and enable debug mode for development and troubleshooting. Custom types provide type safety when interacting with contract tables, while debug mode returns JSON data instead of binary for easier inspection.

```typescript
import { Struct, Name, Int64, TimePoint } from '@wharfkit/antelope'

// Define custom row type
@Struct.type('name_bid')
class NameBid extends Struct {
  @Struct.field(Name) newname!: Name
  @Struct.field(Name) high_bidder!: Name
  @Struct.field(Int64) high_bid!: Int64
  @Struct.field(TimePoint) last_bid_time!: TimePoint
}

// Use with table for full type safety
const bidTable = systemContract.table<NameBid>('namebids', undefined, NameBid)
const bid = await bidTable.get()
console.log(bid.newname.toString()) // TypeScript knows this is a Name
console.log(bid.high_bid.value) // TypeScript knows this is Int64

// Debug mode returns JSON instead of binary
const debugTable = new Table({
  abi: systemContract.abi,
  account: 'eosio',
  client,
  name: 'namebids',
  debug: true
})
const jsonRow = await debugTable.get()
console.log(JSON.stringify(jsonRow, null, 2))

// Numeric scopes for special use cases
const waxKit = new ContractKit({ client: new APIClient('https://wax.greymass.com') })
const dexContract = await waxKit.load('alcordexmain')
const buyOrders = await dexContract.table('buyorder').query({ scope: 0 }).all()
const sellOrders = await dexContract.table('sellorder').query({ scope: 0 }).all()

// Access cursor internals
const cursor = bidTable.query({ maxRows: 100 })
await cursor.next()
console.log('Next key:', cursor.nextkey)
console.log('Rows retrieved:', cursor.rowsCount)
```

--------------------------------

### Execute Read-Only Transactions with Contract.readonly()

Source: https://context7.com/wharfkit/contract/llms.txt

Executes smart contract actions without broadcasting to the blockchain, ideal for querying view functions. The function automatically decodes data based on the ABI's return type and supports typed data according to the ABI definition.

```typescript
// Call a read-only action that returns data
const contract = await kit.load('mycontract')

try {
  const result = await contract.readonly('getbalance', {
    account: 'alice'
  })
  console.log('Balance:', result)
  // Result is automatically decoded based on the ABI return type
} catch (error) {
  console.error('Read-only call failed:', error.message)
}

// Call without parameters
const info = await contract.readonly('getinfo')

// Returns typed data according to ABI definition
const stats = await contract.readonly('getstats', { symbol: 'EOS' })
console.log('Total supply:', stats.supply.toString())
console.log('Max supply:', stats.max_supply.toString())
```
Tokens:
Raw