Saltar al contenido principal

Transacciones – Referencia del SDK de TypeScript

Descripción general​

El SDK de TypeScript expone un pequeño conjunto de tipos y métodos para:

  • Abrir una sesión de transaction contra un node
  • Construir, firmar (mediante el backend WASM) y enviar una transaction
  • Inspeccionar la transaction resultante y su estado/salida
  • Trabajar con payloads de transacciones de smart contract

Esta página documenta esos tipos y métodos principales para referencia rápida. Los tutoriales y ejemplos de extremo a extremo se ubicarán en páginas separadas.

Importaciones​

import {
  TransactionSession,
  createTransactionSession,
  DEFAULT_ADMIN_AUTH_GROUP,
} from "@uledgerinc/typescript-sdk";

import {
  TRANSACTION_VERSION,
  TransactionStatus,
  TransactionType,
  TransactionOutput,
  parseTransactionStatus,
  parseTransactionType,
  parseTransactionOutput,
  ULTransaction,
  ULTransactionInput,
  ULTransactionOutputData,
  ULBlock,
  InvokeContractPayload,
  UpgradeContractPayload,
  RollbackContractPayload,
} from "<your-sdk>/types/transaction";

import { Wallet, WASMBackend } from "@uledgerinc/typescript-sdk";

Se debe reemplazar "<your-sdk>" con el nombre o la ruta del paquete.

Constantes y enumeraciones de transaction​

TRANSACTION_VERSION​

export declare const TRANSACTION_VERSION = "2.0.0";

Estado: TransactionStatus​

export declare enum TransactionStatus {
  Invalid = "INVALID",
  Submitted = "SUBMITTED",
  Accepted = "ACCEPTED",
  Rejected = "REJECTED"
}

Refleja el tipo transaction.UL_TransactionStatus de Go.

:::warning Una transaction enviada no es una transaction aceptada El status y el output de la respuesta de envío describen la transaction tal como se entregó al node. No la confirman. Para confirmarla, se debe leer la transaction desde el node hasta que tenga un blockHeight y output sea SUCCESS, o consultar GET {node}/blockchains/{blockchainId}/transactions/{transactionId}/status y verificar que devuelva state: "committed". Una transaction que la red rechaza se descarta y nunca aparece, por lo que, si no ha sido confirmada dentro de la ventana de espera, se debe tratar como fallida y no como pendiente. :::

Tipo: TransactionType​

export declare enum TransactionType {
  Invalid = "",
  Data = "DATA",
  CreateWallet = "CREATE_WALLET",
  AlterWallet = "ALTER_WALLET",
  DeploySmartContract = "DEPLOY_SMART_CONTRACT",
  InvokeSmartContract = "INVOKE_SMART_CONTRACT",
  UpgradeSmartContract = "UPGRADE_SMART_CONTRACT",
  RollbackSmartContract = "ROLLBACK_SMART_CONTRACT"
}

Refleja el tipo transaction.ULTransactionType de Go.

Valores comunes:

  • TransactionType.Data — transaction de datos genérica
  • TransactionType.CreateWallet / TransactionType.AlterWallet — transacciones de gestión de billeteras
  • TransactionType.DeploySmartContract, TransactionType.InvokeSmartContract, TransactionType.UpgradeSmartContract, TransactionType.RollbackSmartContract — operaciones de smart contract

Salida: TransactionOutput​

export declare enum TransactionOutput {
  Invalid = "",
  ToBeProcessed = "TO_BE_PROCESSED",
  Success = "SUCCESS",
  RejectedByDuplicate = "REJECTED_BY_DUPLICATE",
  RejectedByUnexisting = "REJECTED_BY_UNEXISTING",
  RejectedByDisabled = "REJECTED_BY_DISABLED",
  RejectedByUnauthorized = "REJECTED_BY_UNAUTHORIZED",
  RejectedByInvalidSignature = "REJECTED_BY_INVALID_SIGNATURE",
  TransactionError = "TRANSACTION_ERROR"
}

Refleja el tipo transaction.UL_TransactionOutput de Go.

Tipos de transaction​

VectorClock​

export type VectorClock = Record<string, number>;

Refleja el tipo transaction.VectorClock de Go.

Timestamp​

export interface Timestamp {
  exactTime: Date;
  approximateTime: Date;
}

Refleja el tipo transaction.Timestamp de Go.

ULTransactionInput​

Campos utilizados para crear una transaction:

export interface ULTransactionInput {
  blockchainId: string;
  to: string;
  from: string;
  payload: string;
  senderSignature: string;
  payloadType: TransactionType | string;
  suggestor: string;
  senderTimestamp: Date;
  payloadRoot: string;
  keyType: KeyType;
}

Refleja el tipo transaction.ULTransactionInput de Go.

En el uso típico, muchos de estos campos se completan durante la firma por parte del backend WASM.

ULTransactionOutputData​

Campos devueltos por el node:

export interface ULTransactionOutputData {
  transactionId: string;
  blockHeight: number;
  vectorClock: VectorClock;
  timestamp: Timestamp;
  version: string;
  weight: number;
  status: TransactionStatus | string;
  output: TransactionOutput | string;
  proof: string;
  proofVersion: string;
}

Refleja el tipo transaction.ULTransactionOutput de Go.

ULTransaction​

export interface ULTransaction extends ULTransactionInput, ULTransactionOutputData {}

Combina tanto los campos de entrada (lo que se envió) como los campos de salida (lo que devolvió el node), reflejando el tipo transaction.ULTransaction de Go.

ULBlock​

export interface ULBlock {
  blockHash: string;
  previousBlockHash: string;
  height: number;
  transactions: ULTransaction[];
  merkleRoot: string;
  voters: Record<string, string>;
}

Refleja el tipo transaction.ULBlock de Go.

Sesión de transaction​

Clase: TransactionSession​

export declare class TransactionSession {
  constructor(nodeEndpoint: string, wallet: Wallet, backend: WASMBackend);

  initialize(): Promise<void>;

  getWallet(): Wallet;
  getNodeEndpoint(): string;
  getSuggestor(): string;

  submitTransaction(options: CreateTransactionOptions): Promise<ULTransaction>;
  submitData(options: DataTransactionOptions): Promise<ULTransaction>;
  deployContract(options: DeployContractOptions): Promise<ULTransaction>;
  invokeContract(options: InvokeContractOptions): Promise<ULTransaction>;

  upgradeContract(
    blockchainId: string,
    contractAddress: string,
    newSourceCode: string,
    reason?: string
  ): Promise<ULTransaction>;

  rollbackContract(
    blockchainId: string,
    contractAddress: string,
    targetVersion: number,
    reason?: string
  ): Promise<ULTransaction>;

  createWallet(blockchainId: string, walletData: object): Promise<ULTransaction>;
  alterWallet(blockchainId: string, targetWalletAddress: string, alterData: object): Promise<ULTransaction>;

  registerWallet(blockchainId: string, walletToRegister?: Wallet, customAuthGroups?: AuthGroups): Promise<ULTransaction>;

  getTransaction(blockchainId: string, transactionId: string): Promise<ULTransaction>;
  getBlock(blockchainId: string, height: number): Promise<any>;
}

Una sesión encapsula:

  • el node endpoint
  • el suggestor (ID del node utilizado para la transaction)
  • la billetera utilizada para firmar
  • el backend WASM que calcula los compromisos y firmas

createTransactionSession​

export declare function createTransactionSession(
  nodeEndpoint: string,
  wallet: Wallet,
  backend: WASMBackend
): Promise<TransactionSession>;

Función de fábrica que devuelve una sesión inicializada.

initialize()​

initialize(): Promise<void>;

Realiza las siguientes llamadas:

  • GET {nodeEndpoint}/health para obtener el nodeId (almacenado como suggestor)
  • GET {nodeEndpoint}/blockchains para verificar que existe al menos un blockchain

Envío de transacciones en la sesión​

submitTransaction(options)​

submitTransaction(options: CreateTransactionOptions): Promise<ULTransaction>;

Crea, firma (mediante el backend WASM) y envía una transaction a:

POST {nodeEndpoint}/blockchains/{blockchainId}/transactions

submitData(options)​

submitData(options: DataTransactionOptions): Promise<ULTransaction>;

Wrapper de conveniencia para TransactionType.Data. Si data es un objeto, se serializa a JSON antes del envío.

Payloads de smart contract​

ContractArgs​

export interface ContractArgs {
  value: Uint8Array | string;
}

Refleja el tipo transaction.ContractArgs de Go.

InvokeContractPayload​

export interface InvokeContractPayload {
  functionName: string;
  args: ContractArgs[];
  gasLimit: number;
}

Refleja el tipo transaction.InvokeContractPayload de Go.

Se utiliza con TransactionType.InvokeSmartContract (típicamente codificado en JSON dentro de ULTransactionInput.payload).

UpgradeContractPayload​

export interface UpgradeContractPayload {
  newSourceCode: string;
  upgradeReason?: string;
}

Refleja el tipo transaction.UpgradeContractPayload de Go.

Se utiliza con TransactionType.UpgradeSmartContract.

RollbackContractPayload​

export interface RollbackContractPayload {
  targetVersion: number;
  rollbackReason?: string;
}

Refleja el tipo transaction.RollbackContractPayload de Go.

Se utiliza con TransactionType.RollbackSmartContract.

Funciones de parseo​

parseTransactionStatus​

export declare function parseTransactionStatus(str: string): TransactionStatus;

parseTransactionType​

export declare function parseTransactionType(str: string): TransactionType;

parseTransactionOutput​

export declare function parseTransactionOutput(str: string): TransactionOutput;

Esta página está destinada a ser una referencia. Para guías paso a paso, ver la sección de tutoriales.