Phase 4 : Transmission Protocols

[Victor-Salomon]

TRANSMISSION

WIP - This document specifies the design choices took for the Transmission Protocols pallet implementation in the SDK.
Feel free to comment on certain misunderstandings and new suggestions are warm welcomed.

Sections:

• Events: list of the incoming events from the chain. (6 events)
• Extrinsics: SDK extrinsics to implement on the SDK. (4 helpers)
• Storage: SDK storage to implement on the SDK. (7 getters)
• Constants: SDK constants to implement on the SDK. (4 getters)
• NFT State to be updated : isTransmission

Events

In order to make the returned events datas usefull, we provide both the native format and a friendly ready to use format design format :

• a string as an AccountId32 correspond to a classic user valid address.
• a string as u128 is a BN value as string natively used under the hood by the chain.
• a rounded data (ex: amoutRounded) is the "human" version of a data, (usually a BN) that can be directly used.

6 new events are triggered by the chain in the module transmissionProtocols.

pub enum Event {
  ProtocolSet{
    nft_id,
    recipient,
    protocol,
    cancellation
  },
  ProtocolRemoved{
    nft_id,
  },
  TimerReset: {
	nft_id,
	new_block_number,
  }
  ConsentAdded{
    nft_id,
    from,
  },
  ThresholdReached {
    nft_id,
  },
  Transmitted{
    nft_id,
  }
	// ProtocolFeeSet{
  //  protocol,
  //  fee,
  },
}

SDK events

Additional events will be added to the EventType enum in src > events.ts in the SDK:

export enum EventType {
  ...
  ProtocolSet = "transmissionProtocols.ProtocolSet",
  ProtocolRemoved = "transmissionProtocols.ProtocolRemoved",
  TimerReset = "transmissionProtocols.TimerReset",
  ConsentAdded = "transmissionProtocols.ConsentAdded",
  ThresholdReached = "transmissionProtocols.ThresholdReached",
  Transmitted = "transmissionProtocols.Transmitted",
	...
}

static fromEvent(event: Event): BlockchainEvent {
    ...
    
    switch (name) {
      ...
      // Transmission Protocols
      case EventType.ProtocolSet:
        return new ProtocolSetEvent(event)
      case EventType.ProtocolRemoved:
        return new ProtocolRemovedEvent(event)
      case EventType.TimerReset:
        return new TimerResetEvent(event)
      case EventType.ConsentAdded:
        return new ConsentAddedEvent(event)
      case EventType.ThresholdReached:
        return new ThresholdReachedEvent(event)
      case EventType.Transmitted:
        return new TransmittedEvent(event)
    }

    ...
  }
}

/**
 * This class represents the on-chain ProtocolSetEvent event.
 */
export class ProtocolSetEvent extends BlockchainEvent {
  nftId: number
  recipient: string
  protocol : string // TODO
  cancellation: string // TODO
  /**
   * Construct the data object from the ProtocolSetEvent event
   * @param event The ProtocolSetEvent event
   */
  constructor(event: Event) {
    super(event, EventType.ProtocolSet)
    const [ nftId, recipient, protocol, cancellation] = event.data
    this.nftId = Number.parseInt(nftId.toString())
    this.recipient= recipient.toString()
    this.protocol= protocol.toString() // TODO
    this.cancellation= cancellation.toString() // TODO
  }
}

/**
 * This class represents the on-chain ProtocolRemovedEvent event.
 */
export class ProtocolRemovedEvent extends BlockchainEvent {
  nftId: number
  /**
   * Construct the data object from the ProtocolRemovedEvent event
   * @param event The ProtocolRemovedEvent event
   */
  constructor(event: Event) {
    super(event, EventType.ProtocolRemoved)
    const [nftId] = event.data
    this.nftId = Number.parseInt(nftId.toString())
  }
}

/**
 * This class represents the on-chain TimerResetEvent event.
 */
export class TimerResetEvent extends BlockchainEvent {
  nftId: number
  newBlockNumber: number
  /**
   * Construct the data object from the TimerResetEvent event
   * @param event The TimerResetEvent event
   */
  constructor(event: Event) {
    super(event, EventType.TimerReset)
    const [nftId, newBlockNumber] = event.data
    this.nftId = Number.parseInt(nftId.toString())
    this.newBlockNumber = Number.parseInt(newBlockNumber.toString())
  }
}

/**
 * This class represents the on-chain ConsentAddedEvent event.
 */
export class ConsentAddedEvent extends BlockchainEvent {
  nftId: number
  from: string
  /**
   * Construct the data object from the ConsentAddedEvent event
   * @param event The ConsentAddedEvent event
   */
  constructor(event: Event) {
    super(event, EventType.ConsentAdded)
    const [nftId, from] = event.data
    this.nftId = Number.parseInt(nftId.toString())
    this.from = from.toString()
  }
}

/**
 * This class represents the on-chain ThresholdReachedEvent event.
 */
export class ThresholdReachedEvent extends BlockchainEvent {
  nftId: number
  /**
   * Construct the data object from the ThresholdReachedEvent event
   * @param event The ThresholdReachedEvent event
   */
  constructor(event: Event) {
    super(event, EventType.ThresholdReached)
    const [nftId] = event.data
    this.nftId = Number.parseInt(nftId.toString())
  }
}

/**
 * This class represents the on-chain TransmittedEvent event.
 */
export class TransmittedEvent extends BlockchainEvent {
  nftId: number
  /**
   * Construct the data object from the TransmittedEvent event
   * @param event The TransmittedEvent event
   */
  constructor(event: Event) {
    super(event, EventType.Transmitted)
    const [nftId] = event.data
    this.nftId = Number.parseInt(nftId.toString())
  }
}

Extrinsics

4 extrinsics will be implemented for the transmissionProtocols pallet.

Each helperTx will be duplicated by another helper version with 2 additional parameters: the keyring that will be used to sign and submit the transaction, and a waitUntil callback parameter, to define at which point we want to get the results of the transaction execution.

/**
 * @name setTransmissionProtocolTx
 * @summary    		Adds a transmission protocol to any type of NFT.
 * @param nftId		The NFT Id to add transmission protocol. 
 * @param recipient 	The destination account.
 * @param protocol 	The transmission protocol to execute.
 * @param protocolCancellation 	the cancellation period of the transmission protocol.
 * @returns  		Unsigned unsubmitted Set-Transmission-Protocol Transaction Hash. The Hash is only valid for 5 minutes.
 */
setTransmissionProtocolTx(
	nftId: number,
	recipient: string,
	protocol: TransmissionProtocolType
	protocolCancellation : protocolCancellationType
)

/**
 * @name removeTransmissionProtocolTx
 * @summary    		Creates an unsigned unsubmitted Remove-Transmission-Protocol Transaction Hash for a tansmission protocol.
 * @param nftId		The NFT Id to remove the transmission protocol. 
 * @returns  		Unsigned unsubmitted Remove-Transmission-Protocol Transaction Hash. The Hash is only valid for 5 minutes.
 */
removeTransmissionProtocolTx(
	nftId: number,
)

/**
 * @name resetTranmissionProtocolTimerTx
 * @summary    		Creates an unsigned unsubmitted Reset-Timer Transaction Hash for an AtBlockWithReset protocol.
 * @param nftId		The NFT Id to reset the timer for an AtBlockWithReset protocol.
 * @param blockNumber 	The new blockNumber to execute the AtBlockWithReset protocol.
 * @returns  		Unsigned unsubmitted Reset-Timer Transaction Hash. The Hash is only valid for 5 minutes.
 */
resetTranmissionProtocolTimerTx(
	nftId: number,
	blockNumber: number
)

Users specified in the account list for OnConsent protocol can add their consent to send the NFT.
/**
 * @name addConsentToOnConsentProtocolTx
 * @summary    		Creates an unsigned unsubmitted Add-Consent Transaction Hash for an OnConsent protocol.
 * @param nftId		The NFT Id waiting to get consent added by users.
 * @returns  		         Unsigned unsubmitted Add-Consent Transaction Hash. The Hash is only valid for 5 minutes.
 */
addConsentToOnConsentProtocolTx(
	nftId: number,
)

Storage

7 storage getters will be implemented for the transmissionProtocols pallet.

export enum chainQuery {
  ...
  // transmissionProtocols
	atBlockFee = "atBlockFee"
	atBlockWithResetFee = "atBlockWithResetFee"
	onConsentFee = "onConsentFee"
	onConsentAtBlockFee = "onConsentAtBlockFee"
	atBlockQueue = "atBlockQueue"
	transmissions = "transmissions"
	onConsentData = "onConsentData"
}

/**
 * @name getTransmissionAtBlockFee
 * @summary Fee to set an AtBlock protocol. (extra fee on top of the tx fees).
 * @returns Transmission at block protocol fee.
 */
export const getTransmissionAtBlockFee = async (): Promise<BN> => {
  const fee = await query(txPallets.transmissionProtocols, chainQuery.atBlockFee)
  return fee as any as BN
}

/**
 * @name getTransmissionAtBlockWithResetFee
 * @summary Fee to set an AtBlockWithReset protocol. (extra fee on top of the tx fees).
 * @returns Transmission at block with reset protocol fee.
 */
export const getTransmissionAtBlockWithResetFee = async (): Promise<BN> => {
  const fee = await query(txPallets.transmissionProtocols, chainQuery.atBlockWithResetFee)
  return fee as any as BN
}

/**
 * @name getTransmissionOnConsentFee
 * @summary Fee to set an OnConsentFee protocol. (extra fee on top of the tx fees).
 * @returns Transmission on consent protocol fee.
 */
export const getTransmissionOnConsentFee = async (): Promise<BN> => {
  const fee = await query(txPallets.transmissionProtocols, chainQuery.onConsentFee)
  return fee as any as BN
}

/**
 * @name getTransmissionOnConsentAtBlockFee
 * @summary Fee to set an OnConsentAtBlockFee protocol. (extra fee on top of the tx fees).
 * @returns Transmission on consent at block protocol fee.
 */
export const getTransmissionOnConsentAtBlockFee = async (): Promise<BN> => {
  const fee = await query(txPallets.transmissionProtocols, chainQuery.onConsentAtBlockFee)
  return fee as any as BN
}

/**
 * @name getTransmissionAtBlockQueue
 * @summary Provides the deadlines related to at block transmission protocols in queues.
 * @returns An object containing an array with data related to tranmission queues.
 */
export const getTransmissionAtBlockQueue = async (): Promise<TransmissionAtBlockQueueType> => {
  const data = await query(txPallets.transmissionProtocols, chainQuery.atBlockQueue)
  return ...TODO
}

/**
 * @name getTransmissions
 * @summary Mapping of nft id and transmission data.
 * @param nftId   The ID of the NFT to be transmitted.
 * @returns tbc.
 */
export const getTransmissions = async (): Promise<TransmissionAtBlockQueueType> => {
  const data = await query(txPallets.transmissionProtocols, chainQuery.transmissions)
  return ...TODO
}

/**
 * @name getTransmissionOnConsentData
 * @summary Mapping of nft id and consent vectors.
 * @param nftId   The ID of the NFT to be transmitted.
 * @returns tbc.
 */
export const getTransmissionOnConsentData = async (): Promise<getTransmissionOnConsentType> => {
  const data = await query(txPallets.transmissionProtocols, chainQuery.onConsentData)
  return ...TODO
}

Constants

4 getters will be implemented for the transmissionProtocols pallet.

export enum txPallets {
  ...
  transmissionProtocols = "transmissionProtocols",
}

export enum chainConstants {
  ...
  // transmissionProtocols
  actionsInBlockLimit = "actionsInBlockLimit"
  simultaneousTransmissionLimit = "simultaneousTransmissionLimit"
  maxConsentListSize = "maxConsentListSize"
  maxBlockDuration = "maxBlockDuration"
}

/**
 * @name actionsInBlockLimit
 * @summary Maximum number of actions in one block.
 * @returns Number.
 */
getActionsInBlockLimit(): number => consts(txPallets.transmissionProtocols, chainConstants.actionsInBlockLimit)

/**
 * @name getSimultaneousTransmissionLimit
 * @summary Maximum number of simultaneous transmission protocol.
 * @returns Number.
 */
getSimultaneousTransmissionLimit(): number => consts(txPallets.transmissionProtocols, chainConstants.simultaneousTransmissionLimit)

/**
 * @name getMaxConsentListSize
 * @summary Maximum size for the consent list.
 * @returns Number.
 */
getMaxConsentListSize(): number => consts(txPallets.transmissionProtocols, chainConstants.maxConsentListSize)

/**
 * @name getMaxBlockDuration
 * @summary Maximum block duration for a protocol.
 * @returns Number.
 */
getMaxBlockDuration(): number => consts(txPallets.transmissionProtocols, chainConstants.maxBlockDuration)

[ipapandinas]

Here is my humanized Transmission entity on the Indexer; we can take some inspiration for the destructuring of protocol & cancellation in the ProtocolSet event:

type TransmissionEntity @entity {
  id: ID!
  nftId: String! @index
  from: String!
  to: String!
  isActive: Boolean!
  kind: String!                           #protocol kind
  endBlock: Int
  consentList: [String]
  currentConsent: [String]
  threshold: Int
  cancellationType: String       #cancellation type
  cancellationBlock: Int
  createdAt: Date!
  updatedAt: Date!
  timestampCreate: Date!
  timestampUpdated: Date!
  timestampTransmitted: Date!
}

However I don't think is a good idea to mix 'kind' and 'type', what do you think @Victor-Salomon ?

[Victor-Salomon]

I agree. I would have even switch :
"kind" => "protocol"
"cancellationType" => "cancellation"

In the end we are in the TransmissionEntity so it's clear that this one will only refer to the good value.
Also, I know we register a timestampCancel for auction and rent. Don't you think we could register this one for transmission protocols as well ?

[ipapandinas]

yes good idea, let's do this!

regarding timestampCancel idk, we have timestampUpdated which contains the cancellation time if isActive === false.
we may improve timestamp fields consistance, some are maybe useless and also the naming use sometimes infinitives or conjugated form with '-ed'; let's discuss this in a future dedicated task 👽

[Victor-Salomon]

Seems legit, and agree so much about consistency in conjugated verbs for most of actions. We could try to provide a semi "versionned" version of the indexer on a specific branch indexer-network-next with a dedicated production endpoint to make all the fixs we want and offer some extra time for users to adjust ? Same, let's discuss about it soon