internet-court/internet-court-skill / vendored/near/near-api-js
near-api-js
VerifiedGuide for developing with near-api-js v7 - the JavaScript/TypeScript library for NEAR blockchain interaction. Use when: (1) building apps that interact with NEAR blockchain, (2) creating/signing transactions, (3) calling smart contracts, (4) managing accounts and keys, (5) working with NEAR RPC API, (6) handling FT/NFT tokens on NEAR, (7) using NEAR cryptographic operations (KeyPair, signing), (8) converting between NEAR units (yocto, gas), (9) gasless/meta transactions with relayers, (10) NEP-413 message signing for authentication, (11) storage deposit management for FT contracts. Triggers on any NEAR blockchain development tasks.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 329 B |
| SKILL.md | skill md | 16.0 KB |
| references/api_patterns.md | markdown | 10.9 KB |
| references/contracts.md | markdown | 4.3 KB |
| references/key_management.md | markdown | 6.4 KB |
| references/meta_transactions.md | markdown | 5.8 KB |
| references/nep413.md | markdown | 2.7 KB |
| references/tokens_guide.md | markdown | 6.1 KB |
references/meta_transactions.md
View on GitHub# Meta Transactions Guide
Gasless (relayer-sponsored) transaction patterns in near-api-js.
## Table of Contents
1. [Overview](#overview)
2. [Creating Signed Delegate Actions](#creating-signed-delegate-actions)
3. [Relayer Integration](#relayer-integration)
4. [Block Height TTL](#block-height-ttl)
5. [Error Handling](#error-handling)
---
## Overview
Meta transactions allow users to sign transactions without paying gas. A relayer submits the transaction on their behalf and covers gas costs.
**Flow:**
1. User creates and signs a `DelegateAction`
2. User sends signed delegate to relayer (off-chain)
3. Relayer wraps it in a transaction and submits to NEAR
4. Relayer pays gas, user's action executes
---
## Creating Signed Delegate Actions
```typescript
import { Account, actions, teraToGas, nearToYocto } from "near-api-js";
const account = new Account(accountId, provider, privateKey);
// Create signed meta transaction
const metaTx = await account.createSignedMetaTransaction({
receiverId: "contract.near",
actions: [
actions.functionCall(
"some_method",
{ arg: "value" },
teraToGas(10), // 10 TGas
nearToYocto("0"), // No deposit
),
],
});
// metaTx contains:
// - signedDelegate: { delegateAction, signature }
// - delegateAction: { senderId, receiverId, actions, nonce, maxBlockHeight, publicKey }
```
### With Custom TTL
```typescript
const metaTx = await account.createSignedMetaTransaction({
receiverId: "contract.near",
actions: [
actions.functionCall("method", {}, teraToGas(10), nearToYocto("0")),
],
blockHeightTtl: 100, // Valid for next 100 blocks (~100 seconds)
});
```
### Multiple Actions
```typescript
const metaTx = await account.createSignedMetaTransaction({
receiverId: "contract.near",
actions: [
actions.functionCall("method1", { a: 1 }, teraToGas(10), nearToYocto("0")),
actions.functionCall("method2", { b: 2 }, teraToGas(10), nearToYocto("0")),
actions.transfer(1_000_000_000_000_000_000_000n),
],
});
```
---
## Relayer Integration
### Using `relayMetaTransaction()`
The simplest way to relay — use `account.relayMetaTransaction()`:
```typescript
import {
Account,
actions,
teraToGas,
nearToYocto,
KeyPairString,
} from "near-api-js";
// User creates signed meta transaction
const metaTx = await userAccount.createSignedMetaTransaction({
receiverId: "hello.near-examples.testnet",
actions: [
actions.functionCall(
"set_greeting",
{ greeting: "meta" },
teraToGas(10),
nearToYocto("0"),
),
],
});
// Relayer submits using relayMetaTransaction()
const result = await relayerAccount.relayMetaTransaction(metaTx.signedDelegate);
console.log("Meta-transaction result:", result);
```
### Full Example: User + Relayer via HTTP
```typescript
// =====================
// USER SIDE
// =====================
const userAccount = new Account("user.near", provider, userPrivateKey);
const metaTx = await userAccount.createSignedMetaTransaction({
receiverId: "nft.near",
actions: [
actions.functionCall(
"nft_mint",
{ token_id: "123", receiver_id: "user.near" },
teraToGas(50),
nearToYocto("0"),
),
],
});
// Send to relayer via HTTP
const response = await fetch("https://relayer.example.com/relay", {
method: "POST",
body: JSON.stringify({
signedDelegate: {
delegateAction: metaTx.signedDelegate.delegateAction,
signature: Array.from(metaTx.signedDelegate.signature.data),
},
}),
});
// =====================
// RELAYER SIDE (e.g. server endpoint)
// =====================
const relayerAccount = new Account("relayer.near", provider, relayerPrivateKey);
const { signedDelegate } = await request.json();
const result = await relayerAccount.relayMetaTransaction(signedDelegate);
```
---
## Block Height TTL
Meta transactions expire after a certain block height to prevent replay attacks.
```typescript
// Default: 100 blocks (~100 seconds at 1 block/second)
const metaTx = await account.createSignedMetaTransaction({
receiverId: "contract.near",
actions: [...],
blockHeightTtl: 100,
});
// Check expiration
const currentBlock = await provider.viewBlock({ finality: "final" });
const expiresAt = metaTx.signedDelegate.delegateAction.maxBlockHeight;
const blocksRemaining = Number(expiresAt) - currentBlock.header.height;
if (blocksRemaining <= 0) {
throw new Error("Meta transaction expired");
}
```
### Short TTL for Security
```typescript
// Very short window (10 blocks = ~10 seconds)
const metaTx = await account.createSignedMetaTransaction({
receiverId: "contract.near",
actions: [
actions.functionCall(
"sensitive_action",
{},
teraToGas(30),
nearToYocto("0"),
),
],
blockHeightTtl: 10,
});
```
---
## Error Handling
### Expired Meta Transaction
```typescript
try {
await relayerAccount.relayMetaTransaction(metaTx.signedDelegate);
} catch (error) {
if (error instanceof DelegateActionExpiredActionError) {
}
}
```
### Nonce Issues
```typescript
try {
await relayerAccount.relayMetaTransaction(signedDelegate);
} catch (error) {
if (error instanceof DelegateActionInvalidNonceActionError) {
// Meta transaction already used
}
}
```
---
## Use Cases
### Gasless NFT Minting
```typescript
const metaTx = await userAccount.createSignedMetaTransaction({
receiverId: "nft.near",
actions: [
actions.functionCall(
"nft_mint",
{ token_id: "1" },
teraToGas(50),
nearToYocto("0"),
),
],
});
// Relayer sponsors the gas
await relayerAccount.relayMetaTransaction(metaTx.signedDelegate);
```
### Batch Onboarding
```typescript
// Multiple users create meta txs
const metaTxs = await Promise.all(
users.map((user) => user.account.createSignedMetaTransaction({ ... })),
);
// Submit all in parallel
await Promise.all(
metaTxs.map((metaTx) =>
relayerAccount.relayMetaTransaction(metaTx.signedDelegate),
),
);
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |