@alephium/web3 0.1.0 → 0.2.0-test.0

package/dist/src/utils/subscription.js

@@ -0,0 +1,52 @@
+"use strict";
+/*
+Copyright 2018 - 2022 The Alephium Authors
+This file is part of the alephium project.
+
+The library is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+The library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with the library. If not, see <http://www.gnu.org/licenses/>.
+*/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Subscription = void 0;
+const eventemitter3_1 = __importDefault(require("eventemitter3"));
+class Subscription {
+    constructor(options) {
+        this.provider = options.provider;
+        this.pollingInterval = options.pollingInterval;
+        this.messageCallback = options.messageCallback;
+        this.errorCallback = options.errorCallback;
+        this.task = undefined;
+        this.cancelled = false;
+        this.eventEmitter = new eventemitter3_1.default();
+    }
+    startPolling() {
+        this.eventEmitter.on('tick', async () => {
+            await this.polling();
+            if (!this.cancelled) {
+                this.task = setTimeout(() => this.eventEmitter.emit('tick'), this.pollingInterval);
+            }
+        });
+        this.eventEmitter.emit('tick');
+    }
+    unsubscribe() {
+        this.eventEmitter.removeAllListeners();
+        this.cancelled = true;
+        if (typeof this.task !== 'undefined') {
+            clearTimeout(this.task);
+        }
+    }
+}
+exports.Subscription = Subscription;

package/dist/src/utils/utils.d.ts

@@ -20,6 +20,8 @@ export declare function addressFromContractId(contractId: string): string;
 export declare function contractIdFromTx(txId: string, outputIndex: number): string;
 export declare function subContractId(parentContractId: string, pathInHex: string): string;
 export declare function stringToHex(str: string): string;
+export declare function hexToString(str: any): string;
+export declare function timeout(ms: number): Promise<unknown>;
 declare type _Eq<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
 export declare type Eq<X, Y> = _Eq<{
     [P in keyof X]: X[P];

package/dist/src/utils/utils.js

@@ -20,7 +20,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertType = exports.stringToHex = exports.subContractId = exports.contractIdFromTx = exports.addressFromContractId = exports.addressFromPublicKey = exports.publicKeyFromPrivateKey = exports.binToHex = exports.hexToBinUnsafe = exports.tokenIdFromAddress = exports.contractIdFromAddress = exports.groupOfAddress = exports.isHexString = exports.signatureDecode = exports.signatureEncode = exports.convertHttpResponse = void 0;
+exports.assertType = exports.timeout = exports.hexToString = exports.stringToHex = exports.subContractId = exports.contractIdFromTx = exports.addressFromContractId = exports.addressFromPublicKey = exports.publicKeyFromPrivateKey = exports.binToHex = exports.hexToBinUnsafe = exports.tokenIdFromAddress = exports.contractIdFromAddress = exports.groupOfAddress = exports.isHexString = exports.signatureDecode = exports.signatureEncode = exports.convertHttpResponse = void 0;
 const elliptic_1 = require("elliptic");
 const bn_js_1 = __importDefault(require("bn.js"));
 const blakejs_1 = __importDefault(require("blakejs"));
@@ -194,6 +194,14 @@ function stringToHex(str) {
     return hex;
 }
 exports.stringToHex = stringToHex;
+function hexToString(str) {
+    return buffer_1.Buffer.from(str.toString(), 'hex').toString();
+}
+exports.hexToString = hexToString;
+function timeout(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+exports.timeout = timeout;
 // eslint-disable-next-line @typescript-eslint/no-empty-function, @typescript-eslint/no-unused-vars
 function assertType() { }
 exports.assertType = assertType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alephium/web3",
-  "version": "0.1.0",
+  "version": "0.2.0-test.0",
   "description": "A JS/TS library to interact with the Alephium platform",
   "license": "GPL",
   "main": "dist/src/index.js",

package/src/api/api-alephium.ts

@@ -96,6 +96,8 @@ export interface Balance {
 
   /** @format x.x ALPH */
   lockedBalanceHint: string
+  tokenBalances?: Token[]
+  lockedTokenBalances?: Token[]
 
   /** @format int32 */
   utxoNum: number

package/src/contract/contract.ts

@@ -27,11 +27,30 @@ import { SignDeployContractTxParams, SignExecuteScriptTxParams, SignerWithNodePr
 import * as ralph from './ralph'
 import { bs58, binToHex, contractIdFromAddress, assertType, Eq } from '../utils'
 
+class SourceFile {
+  readonly dirs: string[]
+  readonly dirPath: string
+  readonly contractPath: string
+  readonly artifactPath: string
+
+  constructor(dirs: string[], fileName: string) {
+    this.dirs = dirs
+    this.dirPath = dirs.length === 0 ? '' : dirs.join('/') + '/'
+    if (fileName.endsWith('.json')) {
+      this.contractPath = './contracts/' + this.dirPath + fileName.slice(0, -5)
+      this.artifactPath = './artifacts/' + this.dirPath + fileName
+    } else {
+      this.contractPath = './contracts/' + this.dirPath + fileName
+      this.artifactPath = './artifacts/' + this.dirPath + fileName + '.json'
+    }
+  }
+}
+
 export abstract class Common {
   readonly sourceCodeSha256: string
   readonly functions: node.FunctionSig[]
 
-  static readonly importRegex = new RegExp('^import "[a-z][a-z_0-9]*.ral"', 'mg')
+  static readonly importRegex = new RegExp('^import "([^"/]+/(([^"]+)/)?)?[a-z][a-z_0-9]*.ral"', 'mg')
   static readonly contractRegex = new RegExp('^TxContract [A-Z][a-zA-Z0-9]*', 'mg')
   static readonly interfaceRegex = new RegExp('^Interface [A-Z][a-zA-Z0-9]* \\{', 'mg')
   static readonly scriptRegex = new RegExp('^TxScript [A-Z][a-zA-Z0-9]*', 'mg')
@@ -56,38 +75,53 @@ export abstract class Common {
     this.functions = functions
   }
 
-  protected static _contractPath(fileName: string): string {
-    if (fileName.endsWith('.json')) {
-      return `./contracts/${fileName.slice(0, -5)}`
-    } else {
-      return `./contracts/${fileName}`
-    }
+  protected static _artifactsFolder(): string {
+    return './artifacts/'
   }
 
-  protected static _artifactPath(fileName: string): string {
-    if (fileName.endsWith('.json')) {
-      return `./artifacts/${fileName}`
-    } else {
-      return `./artifacts/${fileName}.json`
+  static getSourceFile(path: string, _dirs: string[]): SourceFile {
+    const parts = path.split('/')
+    const dirs = Array.from(_dirs)
+    if (parts.length === 1) {
+      return new SourceFile(dirs, path)
     }
+    parts.slice(0, parts.length - 1).forEach((part) => {
+      switch (part) {
+        case '.': {
+          break
+        }
+        case '..': {
+          if (dirs.length === 0) {
+            throw new Error('Invalid file path: ' + path)
+          }
+          dirs.pop()
+          break
+        }
+        default: {
+          dirs.push(part)
+        }
+      }
+    })
+    return new SourceFile(dirs, parts[parts.length - 1])
   }
 
-  protected static _artifactsFolder(): string {
-    return './artifacts/'
-  }
-
-  protected static async _handleImports(contractStr: string, importsCache: string[]): Promise<string> {
+  protected static async _handleImports(
+    pathes: string[],
+    contractStr: string,
+    importsCache: string[]
+  ): Promise<string> {
     const localImportsCache: string[] = []
     let result = contractStr.replace(Common.importRegex, (match) => {
       localImportsCache.push(match)
       return ''
     })
     for (const myImport of localImportsCache) {
-      const fileName = myImport.slice(8, -1)
-      if (!importsCache.includes(fileName)) {
-        importsCache.push(fileName)
-        const importContractStr = await Common._loadContractStr(fileName, importsCache, (code) =>
-          Contract.checkCodeType(fileName, code)
+      const relativePath = myImport.slice(8, -1)
+      const importSourceFile = this.getSourceFile(relativePath, pathes)
+      if (!importsCache.includes(importSourceFile.contractPath)) {
+        importsCache.push(importSourceFile.contractPath)
+        const importContractStr = await Common._loadContractStr(importSourceFile, importsCache, (code) =>
+          Contract.checkCodeType(importSourceFile.contractPath, code)
         )
         result = result.concat('\n', importContractStr)
       }
@@ -96,16 +130,16 @@ export abstract class Common {
   }
 
   protected static async _loadContractStr(
-    fileName: string,
+    sourceFile: SourceFile,
     importsCache: string[],
-    validate: (fileName: string) => void
+    validate: (code: string) => void
   ): Promise<string> {
-    const contractPath = this._contractPath(fileName)
+    const contractPath = sourceFile.contractPath
     const contractBuffer = await fsPromises.readFile(contractPath)
     const contractStr = contractBuffer.toString()
 
     validate(contractStr)
-    return Common._handleImports(contractStr, importsCache)
+    return Common._handleImports(sourceFile.dirs, contractStr, importsCache)
   }
 
   static checkFileNameExtension(fileName: string): void {
@@ -116,25 +150,28 @@ export abstract class Common {
 
   protected static async _from<T extends { sourceCodeSha256: string }>(
     provider: NodeProvider,
-    fileName: string,
-    loadContractStr: (fileName: string, importsCache: string[]) => Promise<string>,
-    compile: (provider: NodeProvider, fileName: string, contractStr: string, contractHash: string) => Promise<T>
+    sourceFile: SourceFile,
+    loadContractStr: (sourceFile: SourceFile, importsCache: string[]) => Promise<string>,
+    compile: (provider: NodeProvider, sourceFile: SourceFile, contractStr: string, contractHash: string) => Promise<T>
   ): Promise<T> {
-    Common.checkFileNameExtension(fileName)
+    Common.checkFileNameExtension(sourceFile.contractPath)
 
-    const contractStr = await loadContractStr(fileName, [])
+    const contractStr = await loadContractStr(sourceFile, [])
     const contractHash = cryptojs.SHA256(contractStr).toString()
     const existingContract = this._getArtifactFromCache(contractHash)
     if (typeof existingContract !== 'undefined') {
       return existingContract as unknown as T
     } else {
-      return compile(provider, fileName, contractStr, contractHash)
+      return compile(provider, sourceFile, contractStr, contractHash)
     }
   }
 
-  protected _saveToFile(fileName: string): Promise<void> {
-    const artifactPath = Common._artifactPath(fileName)
-    return fsPromises.writeFile(artifactPath, this.toString())
+  protected _saveToFile(sourceFile: SourceFile): Promise<void> {
+    const folder = Common._artifactsFolder() + sourceFile.dirPath
+    if (!fs.existsSync(folder)) {
+      fs.mkdirSync(folder, { recursive: true })
+    }
+    return fsPromises.writeFile(sourceFile.artifactPath, this.toString())
   }
 
   abstract buildByteCodeToDeploy(initialFields?: Fields): string
@@ -163,32 +200,38 @@ export class Contract extends Common {
 
   static checkCodeType(fileName: string, contractStr: string): void {
     const interfaceMatches = contractStr.match(Contract.interfaceRegex)
-    if (interfaceMatches) {
-      return
-    }
-
     const contractMatches = contractStr.match(Contract.contractRegex)
-    if (contractMatches === null) {
+    if (interfaceMatches === null && contractMatches === null) {
       throw new Error(`No contract found in: ${fileName}`)
-    } else if (contractMatches.length > 1) {
-      throw new Error(`Multiple contracts in: ${fileName}`)
-    } else {
-      return
+    }
+    if (interfaceMatches && contractMatches) {
+      throw new Error(`Multiple contracts and interfaces in: ${fileName}`)
+    }
+    if (interfaceMatches === null) {
+      if (contractMatches !== null && contractMatches.length > 1) {
+        throw new Error(`Multiple contracts in: ${fileName}`)
+      }
+    }
+    if (contractMatches === null) {
+      if (interfaceMatches !== null && interfaceMatches.length > 1) {
+        throw new Error(`Multiple interfaces in: ${fileName}`)
+      }
     }
   }
 
-  private static async loadContractStr(fileName: string, importsCache: string[]): Promise<string> {
-    return Common._loadContractStr(fileName, importsCache, (code) => Contract.checkCodeType(fileName, code))
+  private static async loadContractStr(sourceFile: SourceFile): Promise<string> {
+    return Common._loadContractStr(sourceFile, [], (code) => Contract.checkCodeType(sourceFile.contractPath, code))
   }
 
-  static async fromSource(provider: NodeProvider, fileName: string): Promise<Contract> {
+  static async fromSource(provider: NodeProvider, path: string): Promise<Contract> {
     if (!fs.existsSync(Common._artifactsFolder())) {
       fs.mkdirSync(Common._artifactsFolder(), { recursive: true })
     }
+    const sourceFile = this.getSourceFile(path, [])
     const contract = await Common._from(
       provider,
-      fileName,
-      (fileName, importCaches) => Contract.loadContractStr(fileName, importCaches),
+      sourceFile,
+      (sourceFile) => Contract.loadContractStr(sourceFile),
       Contract.compile
     )
     this._putArtifactToCache(contract)
@@ -197,7 +240,7 @@ export class Contract extends Common {
 
   private static async compile(
     provider: NodeProvider,
-    fileName: string,
+    sourceFile: SourceFile,
     contractStr: string,
     contractHash: string
   ): Promise<Contract> {
@@ -210,7 +253,7 @@ export class Contract extends Common {
       compiled.events,
       compiled.functions
     )
-    await artifact._saveToFile(fileName)
+    await artifact._saveToFile(sourceFile)
     return artifact
   }
 
@@ -239,13 +282,19 @@ export class Contract extends Common {
   }
 
   // support both 'code.ral' and 'code.ral.json'
-  static async fromArtifactFile(fileName: string): Promise<Contract> {
-    const artifactPath = Contract._artifactPath(fileName)
+  static async fromArtifactFile(path: string): Promise<Contract> {
+    const sourceFile = this.getSourceFile(path, [])
+    const artifactPath = sourceFile.artifactPath
     const content = await fsPromises.readFile(artifactPath)
     const artifact = JSON.parse(content.toString())
     return Contract.fromJson(artifact)
   }
 
+  async fetchState(provider: NodeProvider, address: string, group: number): Promise<ContractState> {
+    const state = await provider.contracts.getContractsAddressState(address, { group: group })
+    return this.fromApiContractState(state)
+  }
+
   override toString(): string {
     return JSON.stringify(
       {
@@ -518,28 +567,24 @@ export class Script extends Common {
     }
   }
 
-  private static async loadContractStr(fileName: string, importsCache: string[]): Promise<string> {
-    return Common._loadContractStr(fileName, importsCache, (code) => Script.checkCodeType(fileName, code))
+  private static async loadContractStr(sourceFile: SourceFile): Promise<string> {
+    return Common._loadContractStr(sourceFile, [], (code) => Script.checkCodeType(sourceFile.contractPath, code))
   }
 
-  static async fromSource(provider: NodeProvider, fileName: string): Promise<Script> {
-    return Common._from(
-      provider,
-      fileName,
-      (fileName, importsCache) => Script.loadContractStr(fileName, importsCache),
-      Script.compile
-    )
+  static async fromSource(provider: NodeProvider, path: string): Promise<Script> {
+    const sourceFile = this.getSourceFile(path, [])
+    return Common._from(provider, sourceFile, (sourceFile) => Script.loadContractStr(sourceFile), Script.compile)
   }
 
   private static async compile(
     provider: NodeProvider,
-    fileName: string,
+    sourceFile: SourceFile,
     scriptStr: string,
     contractHash: string
   ): Promise<Script> {
     const compiled = await provider.contracts.postContractsCompileScript({ code: scriptStr })
     const artifact = new Script(contractHash, compiled.bytecodeTemplate, compiled.fields, compiled.functions)
-    await artifact._saveToFile(fileName)
+    await artifact._saveToFile(sourceFile)
     return artifact
   }
 
@@ -556,8 +601,9 @@ export class Script extends Common {
     return new Script(artifact.sourceCodeSha256, artifact.bytecodeTemplate, artifact.fieldsSig, artifact.functions)
   }
 
-  static async fromArtifactFile(fileName: string): Promise<Script> {
-    const artifactPath = Common._artifactPath(fileName)
+  static async fromArtifactFile(path: string): Promise<Script> {
+    const sourceFile = this.getSourceFile(path, [])
+    const artifactPath = sourceFile.artifactPath
     const content = await fsPromises.readFile(artifactPath)
     const artifact = JSON.parse(content.toString())
     return this.fromJson(artifact)

package/src/contract/events.ts

@@ -16,64 +16,33 @@ You should have received a copy of the GNU Lesser General Public License
 along with the library. If not, see <http://www.gnu.org/licenses/>.
 */
 
-import EventEmitter from 'eventemitter3'
-import { node } from '../api'
-import { NodeProvider } from '../api'
+import { ContractEvent } from '../api/api-alephium'
+import { Subscription, SubscribeOptions } from '../utils'
 
-type EventCallback = (event: node.ContractEvent) => Promise<void>
-type ErrorCallback = (error: any, subscription: Subscription) => Promise<void>
-
-export interface SubscribeOptions {
-  provider: NodeProvider
-  contractAddress: string
-  fromCount?: number
-  pollingInterval: number
-  eventCallback: EventCallback
-  errorCallback: ErrorCallback
-}
-
-export class Subscription {
-  provider: NodeProvider
+export class EventSubscription extends Subscription<ContractEvent> {
   readonly contractAddress: string
-  pollingInterval: number
-
   private fromCount: number
-  private eventCallback: EventCallback
-  private errorCallback: ErrorCallback
-  private task: ReturnType<typeof setTimeout> | undefined
-  private cancelled: boolean
-  private eventEmitter: EventEmitter
 
-  constructor(options: SubscribeOptions) {
-    this.provider = options.provider
-    this.contractAddress = options.contractAddress
-    this.fromCount = typeof options.fromCount === 'undefined' ? 0 : options.fromCount
-    this.pollingInterval = options.pollingInterval
-    this.eventCallback = options.eventCallback
-    this.errorCallback = options.errorCallback
-    this.task = undefined
-    this.cancelled = false
+  constructor(options: SubscribeOptions<ContractEvent>, contractAddress: string, fromCount?: number) {
+    super(options)
+    this.contractAddress = contractAddress
+    this.fromCount = typeof fromCount === 'undefined' ? 0 : fromCount
 
-    this.eventEmitter = new EventEmitter()
+    this.startPolling()
+  }
+
+  override startPolling() {
     this.eventEmitter.on('tick', async () => {
-      await this.fetchEvents()
+      await this.polling()
     })
     this.eventEmitter.emit('tick')
   }
 
-  unsubscribe(): void {
-    this.eventEmitter.removeAllListeners()
-    this.cancelled = true
-    if (typeof this.task !== 'undefined') {
-      clearTimeout(this.task)
-    }
-  }
-
   currentEventCount(): number {
     return this.fromCount
   }
 
-  private async fetchEvents() {
+  override async polling() {
     try {
       const events = await this.provider.events.getEventsContractContractaddress(this.contractAddress, {
         start: this.fromCount
@@ -87,16 +56,20 @@ export class Subscription {
         return
       }
 
-      const promises = events.events.map((event) => this.eventCallback(event))
+      const promises = events.events.map((event) => this.messageCallback(event))
       await Promise.all(promises)
       this.fromCount = events.nextStart
-      await this.fetchEvents()
+      await this.polling()
     } catch (err) {
       await this.errorCallback(err, this)
     }
   }
 }
 
-export function subscribe(options: SubscribeOptions): Subscription {
-  return new Subscription(options)
+export function subscribeToEvents(
+  options: SubscribeOptions<ContractEvent>,
+  contractAddress: string,
+  fromCount?: number
+): EventSubscription {
+  return new EventSubscription(options, contractAddress, fromCount)
 }

package/src/index.ts

@@ -20,5 +20,6 @@ export * from './api'
 export * from './contract'
 export * from './signer'
 export * from './utils'
+export * from './transaction'
 
 export * from './constants'

package/src/transaction/index.ts

@@ -0,0 +1,20 @@
+/*
+Copyright 2018 - 2022 The Alephium Authors
+This file is part of the alephium project.
+
+The library is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+The library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with the library. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+export * from './sign-verify'
+export * from './status'

package/src/{utils/transaction.test.ts → transaction/sign-verify.test.ts}

@@ -19,7 +19,7 @@ along with the library. If not, see <http://www.gnu.org/licenses/>.
 import EC from 'elliptic'
 import assert from 'assert'
 
-import { transactionSign, transactionVerifySignature } from './transaction'
+import { transactionSign, transactionVerifySignature } from './sign-verify'
 
 describe('transaction', function () {
   it('should verify signature', () => {

package/src/{utils/transaction.ts → transaction/sign-verify.ts}

@@ -18,7 +18,7 @@ along with the library. If not, see <http://www.gnu.org/licenses/>.
 
 import { ec as EC } from 'elliptic'
 
-import * as utils from './utils'
+import * as utils from '../utils'
 
 const ec = new EC('secp256k1')
 

package/src/transaction/status.ts

@@ -0,0 +1,58 @@
+/*
+Copyright 2018 - 2022 The Alephium Authors
+This file is part of the alephium project.
+
+The library is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+The library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with the library. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { TxStatus } from '../api/api-alephium'
+import { Subscription, SubscribeOptions } from '../utils'
+
+export class TxStatusSubscription extends Subscription<TxStatus> {
+  readonly txId: string
+  readonly fromGroup?: number
+  readonly toGroup?: number
+
+  constructor(options: SubscribeOptions<TxStatus>, txId: string, fromGroup?: number, toGroup?: number) {
+    super(options)
+    this.txId = txId
+    this.fromGroup = fromGroup
+    this.toGroup = toGroup
+
+    this.startPolling()
+  }
+
+  override async polling() {
+    try {
+      const txStatus = await this.provider.transactions.getTransactionsStatus({
+        txId: this.txId,
+        fromGroup: this.fromGroup,
+        toGroup: this.toGroup
+      })
+
+      await this.messageCallback(txStatus)
+    } catch (err) {
+      await this.errorCallback(err, this)
+    }
+  }
+}
+
+export function subscribeToTxStatus(
+  options: SubscribeOptions<TxStatus>,
+  txId: string,
+  fromGroup?: number,
+  toGroup?: number
+): TxStatusSubscription {
+  return new TxStatusSubscription(options, txId, fromGroup, toGroup)
+}

package/src/utils/index.ts

@@ -20,5 +20,5 @@ export * from './address'
 export * from './bs58'
 export * from './djb2'
 export * from './password-crypto'
-export * from './transaction'
 export * from './utils'
+export * from './subscription'