near-connect-transactions

name	near-connect-transactions
description	Send transactions and sign messages with @hot-labs/near-connect. Covers ConnectorAction format (FunctionCall, Transfer, etc.), @near-js Action compatibility, signAndSendTransaction, signAndSendTransactions, signMessage, signInAndSignMessage, signDelegateActions, and function call access key parameters. Use when a dapp needs to call a NEAR contract, sign a message for authentication, or add a limited-access key.
type	core
library	near-connect
library_version	0.11.3
requires	["near-connect-quickstart"]
sources	["hot-dao/near-selector:src/actions/types.ts","hot-dao/near-selector:src/actions/index.ts","hot-dao/near-selector:src/types/index.ts","hot-dao/near-selector:src/SandboxedWallet/index.ts"]

This skill builds on near-connect-quickstart. Read it first for wallet connection setup.

NEAR Connect — Transactions & Signing

Setup

Get a connected wallet instance (requires sign-in first):

import { NearConnector } from "@hot-labs/near-connect";

const connector = new NearConnector({ network: "mainnet" });
await connector.whenManifestLoaded;
await connector.connect();
const wallet = await connector.wallet();

Core Patterns

Send a single transaction (FunctionCall)

const result = await wallet.signAndSendTransaction({
  receiverId: "contract.near",
  actions: [
    {
      type: "FunctionCall",
      params: {
        methodName: "ft_transfer",
        args: { receiver_id: "bob.near", amount: "1000000000000000000000000" },
        gas: "30000000000000",
        deposit: "1",
      },
    },
  ],
});

console.log("Transaction hash:", result.transaction.hash);

Send multiple transactions in batch

const results = await wallet.signAndSendTransactions({
  transactions: [
    { receiverId: "token.near", actions: [{ type: "FunctionCall", params: { methodName: "ft_transfer", args: {}, gas: "30000000000000", deposit: "1" } }] },
    { receiverId: "nft.near", actions: [{ type: "FunctionCall", params: { methodName: "nft_transfer", args: {}, gas: "30000000000000", deposit: "1" } }] },
  ],
});

Sign a message for authentication

const nonce = crypto.getRandomValues(new Uint8Array(32));

const signed = await wallet.signMessage({
  message: "Sign in to My App",
  recipient: "My App",
  nonce,
});

console.log("Signed by:", signed.accountId, "signature:", signed.signature);

Sign delegate actions (meta-transactions)

const response = await wallet.signDelegateActions({
  delegateActions: [
    {
      receiverId: "contract.near",
      actions: [
        { type: "FunctionCall", params: { methodName: "method", args: {}, gas: "30000000000000", deposit: "0" } },
      ],
    },
  ],
});

Add a function call access key during sign-in

await connector.connect({
  addFunctionCallKey: {
    contractId: "game.near",
    publicKey: "ed25519:4rMHtoFKUoR rageZMwYpGDdGZpWn1eZ3JYaQY8jpRkPLBqoHvBZq",
    allowMethods: { anyMethod: false, methodNames: ["play", "claim"] },
    gasAllowance: { kind: "limited", amount: "250000000000000000000000" },
  },
});

Gas allowance defaults to 0.25 NEAR (in yoctoNEAR) with kind: "limited". Use kind: "unlimited" for no limit.

Action Format Reference

The library accepts two action formats in signAndSendTransaction and signAndSendTransactions:

ConnectorAction (recommended):

Type	Required params
FunctionCall	methodName, args, gas (yoctogas string), deposit (yoctoNEAR string)
Transfer	deposit (yoctoNEAR string)
CreateAccount	none
DeployContract	code (Uint8Array)
DeleteAccount	beneficiaryId (string)
AddKey	publicKey, accessKey
DeleteKey	publicKey
Stake	stake, publicKey
DeployGlobalContract	code, deployMode ("CodeHash" or "AccountId")
UseGlobalContract	contractIdentifier ({ accountId } or { codeHash })

@near-js Action (also accepted):

Actions from @near-js/transactions (e.g. action.functionCall) are automatically converted via nearActionsToConnectorActions. Both formats work, but ConnectorAction is recommended for portability.

Common Mistakes

HIGH Omitting gas and deposit in FunctionCall action

Wrong:

actions: [{ type: "FunctionCall", params: { methodName: "ft_transfer", args: { receiver_id: "bob.near" } } }]

Correct:

actions: [{ type: "FunctionCall", params: { methodName: "ft_transfer", args: { receiver_id: "bob.near", amount: "1000000000000000000000000" }, gas: "30000000000000", deposit: "1" } }]

FunctionCall requires gas (in yoctogas, e.g. "30000000000000" for 30 TGas) and deposit (in yoctoNEAR, e.g. "1" for 1 yoctoNEAR). Omitting them causes protocol-level transaction failure.

Source: src/actions/types.ts:10-18

HIGH Calling signMessage without required nonce

Wrong:

await wallet.signMessage({ message: "Sign in", recipient: "My App" });

Correct:

const nonce = crypto.getRandomValues(new Uint8Array(32));
await wallet.signMessage({ message: "Sign in", recipient: "My App", nonce });

signMessage requires a nonce as Uint8Array. Omitting it causes the wallet to reject the request.

Source: src/types/index.ts:81-87

HIGH Confusing signMessage with signInAndSignMessage

Wrong:

await connector.connect({ walletId: "hot-wallet" });
const wallet = await connector.wallet();
const nonce = crypto.getRandomValues(new Uint8Array(32));
const signed = await wallet.signMessage({ message: "Sign in", recipient: "My App", nonce });

Correct:

const nonce = crypto.getRandomValues(new Uint8Array(32));
await connector.connect({
  walletId: "hot-wallet",
  signMessageParams: { message: "Sign in", recipient: "My App", nonce },
});

signMessage is a standalone call after sign-in requiring two wallet interactions. signInAndSignMessage (triggered via connect({ signMessageParams })) combines both in one interaction. Use the latter for sign-in with ownership verification.

Source: src/NearConnector.ts:297-316

MEDIUM Using near-api-js action format when ConnectorAction is recommended

Wrong:

import { transactions } from "near-api-js";
await wallet.signAndSendTransaction({
  receiverId: "contract.near",
  actions: [transactions.functionCall("method", args, "30000000000000", "1")]
});

Correct:

await wallet.signAndSendTransaction({
  receiverId: "contract.near",
  actions: [{ type: "FunctionCall", params: { methodName: "method", args: {}, gas: "30000000000000", deposit: "1" } }]
});

The library accepts both formats, but ConnectorAction is recommended. It's more portable across wallet types and avoids dependency on near-api-js serialization.

Source: src/actions/types.ts

MEDIUM Wrong gas allowance units for function call keys

Wrong:

addFunctionCallKey: { contractId: "game.near", publicKey: "ed25519:...", allowMethods: { anyMethod: false, methodNames: ["play"] }, gasAllowance: { kind: "limited", amount: "0.25" } }

Correct:

addFunctionCallKey: { contractId: "game.near", publicKey: "ed25519:...", allowMethods: { anyMethod: false, methodNames: ["play"] }, gasAllowance: { kind: "limited", amount: "250000000000000000000000" } }

gasAllowance.amount is in yoctoNEAR. 0.25 NEAR = 250000000000000000000000 yoctoNEAR. Passing a human-readable number creates a key with insufficient or excessive allowance.

Source: src/NearConnector.ts:290-293

Version

Targets @hot-labs/near-connect v0.11.3.